/why-this-way

Using @agent-mentor investigate why specific code was implemented in its current form rather than obvious alternatives, combining historical analysis and architectural reasoning to uncover hidden constraints and design decisions.

Input Parsing

The user invoked: /why-this-way {code_or_context}

Examples:

• /why-this-way src/auth/session.ts - Why this specific implementation?
• /why-this-way why callbacks instead of async/await in parser - Why this pattern choice?
• /why-this-way the manual SQL queries in reports module - Why not use the ORM?
• /why-this-way - Interactive mode to identify what needs investigation

Your Task

This is an archaeological and analytical investigation focused on understanding, not improvement. The goal is to help developers comprehend the reasoning, constraints, and context behind seemingly odd or non-obvious implementation choices.

1. Initial Investigation

Identify:

• What code or pattern needs investigation
• What the "obvious alternative" would be
• What makes the current approach surprising or non-intuitive
• The scope of the implementation (single function, module, architectural pattern)

If unclear, ask questions like:

• "What aspect of this implementation surprises you?"
• "What alternative approach would you have expected?"
• "Is this a recent change or legacy code?"

2. Archaeological Research Phase

Use multiple investigation techniques:

Git History Analysis

• git log --follow -p -- {file} - Full evolution of the file
• git log --all --full-history -- {file} - Even deleted/moved files
• git blame {file} - Line-level authorship and timing
• git log --grep="{keyword}" - Find related commits
• Find when the pattern was introduced and if it changed over time

Pull Request Archaeology

• gh pr list --search "involves:{file}" - Find related PRs
• gh pr view {number} - Read PR descriptions and discussions
• Look for review comments that explain decisions
• Check for linked issues that provide context

Context Mining

• Search commit messages for keywords like "workaround", "temporary", "fix", "revert"
• Look for comments in the code explaining unusual choices
• Check for TODO/FIXME/HACK comments near the code
• Search for related issues: gh issue list --search "involves:{topic}"

Co-change Pattern Analysis

• What other files changed in the same commits?
• Are there related constraints in dependencies?
• Did external dependencies influence the approach?

3. Constraint Discovery

Investigate potential hidden constraints:

Technical Constraints

• Performance requirements: Was speed critical? (Check benchmarks, profiling)
• Memory limitations: Were resources constrained? (Check memory usage patterns)
• Browser compatibility: Legacy browser support? (Check build configs, polyfills)
• Dependency limitations: Was a library missing features? (Check package.json history, versions)
• Platform constraints: OS-specific issues? (Check for platform-specific code paths)
• Build system limitations: Bundler, transpiler restrictions? (Check build configs)

Business Constraints

• Timeline pressure: Was this a hotfix or rush job? (Check commit timing, PR velocity)
• Resource constraints: Team size, expertise available? (Check authorship patterns)
• Legal/compliance: Licensing, security requirements? (Check for audit trails, compliance docs)
• Third-party integration: External system requirements? (Check API integrations)

Historical Constraints

• State of the art: What was possible/known at the time? (Check commit dates against library release dates)
• Language/framework version: Older version limitations? (Check package.json history)
• Migration in progress: Caught between old and new patterns? (Look for mixed patterns)
• Known bugs: Working around external bugs? (Check for bug tracker references)

4. Pattern Analysis

Examine the broader context:

Architectural Alignment

• Does this fit a larger architectural pattern?
• Is it consistent with other similar code?
• Does it solve a recurring problem in the codebase?
• Is it part of a gradual migration strategy?

Team Learning Curve

• Was this an early experiment with a technology?
• Did the team's understanding evolve afterward?
• Is newer code using different patterns?

5. Save Output

Create a markdown file at /reports/why-this-way-{topic}-{timestamp}.md with your archaeological findings.

Output Format

# Why This Way: [Code/Pattern Description]

## The Question
**Current Implementation**: [Brief description]
**Obvious Alternative**: [What seems more natural]
**Investigation Scope**: [Files/modules examined]

## Summary
[2-3 sentence TL;DR of why it's built this way]

---

## Archaeological Findings

### Timeline
[When was this introduced? Key dates in its evolution]

YYYY-MM-DD: Initial implementation by [author] commit: abc1234 Context: [What the commit message says]

YYYY-MM-DD: Significant modification by [author] commit: def5678 Context: [Why it changed]

### Key Commits
[Most relevant commits with links and explanations]

- **[abc1234](link)** - "Initial auth refactor"
  - Author: @developer
  - Date: 2023-04-15
  - Insight: [What this tells us]

### Pull Request Discussions
[Relevant PR conversations that explain decisions]

- **PR #123**: "Switch to callback pattern"
  - Discussion: [Key points from review comments]
  - Decision rationale: [Why this approach was chosen]
  - Link: [PR URL]

---

## Discovered Constraints

### Technical Constraints
[What technical limitations influenced this design]

- **Performance**: [Specific performance requirements]
  - Evidence: [Benchmark results, profiling data, commit messages]

- **Compatibility**: [Browser/platform constraints]
  - Evidence: [Build configs, polyfill usage, issue discussions]

- **Dependencies**: [External library limitations]
  - Evidence: [Package versions, issue tracker links]

### Business Constraints
[Non-technical factors that influenced the design]

- **Timeline**: [Was this rushed?]
  - Evidence: [Commit timing, PR velocity, comments]

- **Resources**: [Team or expertise limitations]
  - Evidence: [Authorship patterns, learning curve indicators]

### Historical Context
[What was the state of the world when this was written]

- **Technology Maturity**: [What was/wasn't available]
  - When written: [Date and context]
  - Available alternatives: [What existed at the time]

- **Framework/Language Version**: [Version constraints]
  - Evidence: [Package.json history, compatibility notes]

---

## Architectural Reasoning

### Pattern Context
[How this fits into the larger system]

- Is this pattern used elsewhere? [Links to similar code]
- Does it solve a recurring problem? [Problem description]
- Is it part of a migration strategy? [Migration plan evidence]

### Design Trade-offs
[What this approach gains vs. what it sacrifices]

**Gains:**
- [Benefit 1]: [Explanation with evidence]
- [Benefit 2]: [Explanation with evidence]

**Trade-offs:**
- [Cost 1]: [What was sacrificed and why it was acceptable]
- [Cost 2]: [What was sacrificed and why it was acceptable]

---

## The "Why Not" Answers

### Why Not [Alternative 1]?
[Specific reasons the obvious alternative wasn't used]

- **Reason**: [Technical or business reason]
- **Evidence**: [Commit message, comment, PR discussion, or technical limitation]
- **Context**: [Additional explanation]

### Why Not [Alternative 2]?
[If there are multiple obvious alternatives]

---

## Questions to Explore Further

[Open questions that could deepen understanding]

- [ ] [Question about related code or history]
  - Suggested investigation: [How to explore this]
  - Relevant files: [Where to look]

- [ ] [Question about future direction]
  - Context: [Why this matters]
  - Who might know: [Team members, commit authors]

---

## Human Factors

### Team Context
[Evidence of human realities affecting decisions]

- **Code authorship**: [Who wrote this, their experience level at the time]
- **Team composition**: [Size, expertise, distributed or co-located]
- **Timing indicators**: [Evidence of time pressure, late-night commits, holidays]

### Learning Journey
[How the team's understanding evolved]

- **Initial approach**: [First implementation]
- **Evolution**: [How it changed over time]
- **Current state**: [Where similar code is now]

---

## References

### Commits
[Full list of relevant commits with links]

### Pull Requests
[All related PRs]

### Issues
[Related GitHub issues or bug reports]

### External References
[Blog posts, Stack Overflow, documentation that may have influenced decisions]

### Related Code
[File paths to similar patterns, related modules]

---

## Learning Takeaways

[What this investigation teaches about the codebase]

1. [Key insight about the system]
2. [Understanding of constraints]
3. [Pattern to recognize elsewhere]
4. [How to think about future changes]

---

*Investigation completed: [timestamp]*
*Files examined: [count]*
*Commits analyzed: [count]*
*Time period: [earliest to latest commit]*

Investigation Techniques

Finding the Real Story

Look for these signal patterns:

1. Commit Message Keywords

   • "workaround" → External constraint
   • "temporary" → Time pressure or incomplete solution
   • "revert" → Something didn't work, read the discussion
   • "fixes #123" → Check the issue for context
   • "performance" → Optimization constraint
   • "compatibility" → Browser/platform constraint

2. Code Comment Archaeology

   // TODO: This should use async/await when Node 12 support is dropped
   // HACK: Working around webpack bug #12345
   // NOTE: Don't refactor - see PR #456 for why callbacks are required
   

3. Timing Patterns

   • Late-night commits → Time pressure
   • Multiple rapid commits → Fixing urgent issues
   • Long PR review times → Controversial decision
   • Commits right before releases → Stability constraints

4. Co-change Analysis

   # Find what else changed when this was introduced
   git log --all --oneline --follow -- {file} | head -1 | awk '{print $1}' | xargs git show --stat
   

5. Author Context

   • First commits from an author → Learning curve
   • Different authors over time → Knowledge transfer
   • Single author dominance → Specialized knowledge

Interview the Codebase

Ask these questions of the code:

• When: What else was happening in the codebase at this time?
• Who: What was their experience level? Were they new to the team/tech?
• What: What problem were they actually solving? (Read the issue/PR)
• Why: What constraints existed? (Check configs, dependencies, platform targets)
• How: What alternatives were discussed? (PR comments, commit history)

Handling Missing Information

When you can't find definitive answers:

## Hypothesis: [Possible Explanation]

**Supporting Evidence:**
- [Circumstantial evidence 1]
- [Circumstantial evidence 2]

**Confidence Level**: Medium/Low

**How to Verify:**
- Ask @original-author about [specific question]
- Check [external resource] for [information]
- Investigate [related code] for [context]

**Questions to Ask:**
- [Specific question for team members]
- [What to look for in external docs]

Educational Approach

Focus on Understanding, Not Judgment

DO:

• Present findings objectively
• Acknowledge time and resource constraints
• Recognize the context at the time of writing
• Appreciate working solutions even if unconventional
• Link to learning resources

DON'T:

• Judge code or developers
• Assume ignorance or incompetence
• Recommend refactoring (unless explicitly asked)
• Dismiss constraints as "excuses"
• Present obvious alternatives as "better" without context

Encourage Curiosity

Include questions that prompt deeper investigation:

• "Want to know more about [related topic]? Try /explain [topic]"
• "Curious how this pattern evolved? Check out commits [abc]..[def]"
• "See a similar pattern in [other file]? It might have related history"
• "This connects to [architectural decision]. Want to explore that?"

Connect to Broader Learning

## Related Patterns

This investigation revealed [pattern]. You might also find this pattern in:
- [File 1]: [Similar constraint]
- [File 2]: [Similar solution]

## Further Reading

To understand this better, you might want to:
- `/explain [related concept]`
- Read about [external topic]: [link]
- Explore the evolution of [related code]

Example Scenarios

Scenario 1: Manual SQL Instead of ORM

Investigation reveals:
- ORM was too slow for reporting queries (benchmarks in commit message)
- 100x performance improvement with raw SQL
- Comment references profiling results
- Decision made in PR #234 with performance data
- Trade-off: maintainability for speed in reporting-critical path

Scenario 2: Callbacks Instead of Async/Await

Investigation reveals:
- Code written in 2016, before async/await was widely supported
- Node version constraint (v4) didn't support it
- Package.json shows node version updated in 2018
- Similar new code uses async/await
- Technical debt acknowledged in TODO comments

Scenario 3: Strange Validation Logic

Investigation reveals:
- Working around third-party API bug
- Issue #567 documents the API returning invalid data
- API vendor notified but never fixed
- Defensive code protects against edge case
- Comment includes link to vendor issue tracker

Scenario 4: Unusual Data Structure

Investigation reveals:
- Optimized for mobile client constraints
- PR discussion mentions 3G network performance
- Data structure reduces payload by 60%
- Decision made with mobile team input
- Trade-off: server complexity for client performance

Response Templates

When Context is Clear

I'll investigate why [code] was built this way instead of [alternative]. Let me dig through the git history, pull requests, and architectural context to uncover the constraints and reasoning behind this design decision.

[Conducts investigation]

[Presents findings in report format]

When Context is Unclear

I can help investigate why code was built a certain way. To focus my investigation, I need to understand:

1. What specific code or pattern surprises you?
2. What alternative approach would seem more natural?
3. Are you looking at a specific file, or a broader pattern?

Once I know what to investigate, I'll dig through git history, PRs, and architectural context to uncover the real story.

When Findings are Clear

Found it! The [pattern] was chosen because [key constraint].

Here's the archaeological trail:
- [Date]: Original implementation in commit [hash]
- Constraint: [Specific limitation]
- Evidence: [PR discussion/commit message/code comment]

[Save full report and provide link]

When Findings are Unclear

I've investigated the history, but the reasoning isn't definitively documented. Here's what I found:

**Likely explanation**: [Hypothesis based on circumstantial evidence]

**Supporting evidence**:
- [Evidence 1]
- [Evidence 2]

**To verify this**, you could:
- Ask @original-author about [specific question]
- Check [external resource]

[Save full report with hypotheses and provide link]

Important Guidelines

1. Be a detective, not a judge - Investigate objectively
2. Respect constraints - They were real at the time
3. Value working code - It solved a problem
4. Acknowledge uncertainty - Don't speculate wildly
5. Encourage questions - Foster curiosity about history
6. Connect to learning - Help understand the system better
7. Avoid prescriptive advice - This is about understanding, not refactoring

Remember: Every "weird" implementation has a story. Your job is to uncover that story and help developers understand the real constraints and decisions that shaped the code. Sometimes you'll find brilliant solutions to hidden problems. Sometimes you'll find technical debt from time pressure. Both are valuable to understand.

---

CRITICAL: Report Generation

YOU MUST CREATE THE REPORT FILE. This is not optional.

Final Steps (MANDATORY)

1. Create the report file using the Write tool at the specified path:

   • Path format: /reports/{command-name}-{scope}-{timestamp}.md
   • Use ISO timestamp format: YYYY-MM-DD-HHmmss
   • Example: /reports/architecture-review-entire-project-2025-10-14-143022.md

2. Fill in ALL sections of the report template

   • Do not leave placeholder text
   • Provide specific, actionable findings
   • Include file paths and line numbers where relevant

3. Confirm completion by telling the user:

   • "Report saved to: [full path]"
   • Brief summary of key findings
   • Next steps or how to use the report

Common Mistakes to Avoid

❌ DON'T: Just summarize findings in the chat ❌ DON'T: Say "I'll create a report" without actually doing it ❌ DON'T: Leave sections incomplete or with placeholders ❌ DON'T: Forget to use the Write tool

✅ DO: Always use the Write tool to create the markdown file ✅ DO: Fill in every section with real findings ✅ DO: Provide the full path to the user when done ✅ DO: Include actionable recommendations

Verification Checklist

Before responding to the user, verify:

• Report file created with Write tool
• All template sections filled in
• Specific findings with file references
• Actionable recommendations included
• Timestamp in filename
• Full path provided to user

Remember: The report is the primary deliverable. The chat summary is secondary.