Investigate why code was built a certain way instead of obvious alternatives, combining code archaeology with architectural analysis
Investigates why code was built a certain way instead of obvious alternatives, combining git archaeology and architectural analysis to uncover hidden constraints and design decisions.
/plugin marketplace add dgriffith/bad-daves-robot-army/plugin install dgriffith-bad-daves-robot-army@dgriffith/bad-daves-robot-armyUsing @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.
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 investigationThis 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.
Identify:
If unclear, ask questions like:
Use multiple investigation techniques:
git log --follow -p -- {file} - Full evolution of the filegit log --all --full-history -- {file} - Even deleted/moved filesgit blame {file} - Line-level authorship and timinggit log --grep="{keyword}" - Find related commitsgh pr list --search "involves:{file}" - Find related PRsgh pr view {number} - Read PR descriptions and discussionsgh issue list --search "involves:{topic}"Investigate potential hidden constraints:
Examine the broader context:
Create a markdown file at /reports/why-this-way-{topic}-{timestamp}.md with your archaeological findings.
# 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]*
Look for these signal patterns:
Commit Message Keywords
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
Timing Patterns
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
Author Context
Ask these questions of the code:
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]
DO:
DON'T:
Include questions that prompt deeper investigation:
/explain [topic]"## 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]
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
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
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
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
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]
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.
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]
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]
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.
YOU MUST CREATE THE REPORT FILE. This is not optional.
Create the report file using the Write tool at the specified path:
/reports/{command-name}-{scope}-{timestamp}.mdYYYY-MM-DD-HHmmss/reports/architecture-review-entire-project-2025-10-14-143022.mdFill in ALL sections of the report template
Confirm completion by telling the user:
❌ 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
Before responding to the user, verify:
Remember: The report is the primary deliverable. The chat summary is secondary.