Generate an engaging, deep-dive explanation document (FOR_[NAME].md) that explains a codebase or domain in plain language with analogies, lessons learned, and practical wisdom.
Generate a FOR_[NAME].md document that explains a codebase, project, or domain in an engaging, memorable way.
This isn't documentation. Documentation tells you what exists. This tells you:
The output should read like a senior engineer explaining the project over coffee, not like a README.
Check $ARGUMENTS:
| Input | Action |
|---|---|
| Empty | Analyze current working directory |
| Path | Analyze specified directory |
--name <name> | Use custom name for FOR_[NAME].md |
--domain <topic> | Focus on specific domain/subsystem |
| `--depth shallow | medium |
Use AskUserQuestion to understand scope:
What should I focus on?
Options:
1. Full codebase overview (architecture, patterns, lessons)
2. Specific subsystem or feature
3. Recent changes and their rationale
4. Onboarding guide for new contributors
Use the Explore agent to understand structure:
Task({
subagent_type: "Explore",
description: "Map codebase architecture",
prompt: `
Explore this codebase and identify:
1. Main entry points
2. Core abstractions and patterns
3. Directory structure philosophy
4. Key configuration files
5. Test patterns
6. External dependencies and why they're used
Return a structured summary, not raw file listings.
`
})
Look for:
Grep({ pattern: "TODO|HACK|FIXME|XXX|NOTE:", output_mode: "content" })
Every codebase has a narrative. Find it.
What pain does this code solve? Not the feature list—the actual human frustration it addresses.
Bad: "This is a task management CLI" Good: "This exists because every task app assumes you'll check it daily, but ADHD brains don't work that way"
What architectural choices were made and why? Look for:
What would someone wish they knew before diving in? This includes:
Use this template structure, adapting sections as needed:
# [Project Name]: The Story Behind the Code
*[One-line hook that makes someone want to read more]*
---
## The Problem We're Actually Solving
[Start with the human problem, not the technical solution]
---
## The Architecture: [Memorable Analogy]
[Use an analogy that makes the structure intuitive]
[Include ASCII diagrams where helpful]
### Why This Separation Matters
[Explain the reasoning, not just the structure]
---
## The Technical Stack (And Why Each Piece)
### [Technology 1]
[What it is, why we chose it, what we'd lose without it]
### [Technology 2]
[Same pattern - every tool earns its place]
---
## [Core Feature/System Deep Dive]
[Pick the most interesting/complex part and explain it thoroughly]
### The Problem It Solves
[Specific pain point]
### The Solution
[How it works, with code examples where helpful]
### Why This Approach
[Alternative approaches considered and rejected]
---
## Bugs We Hit (And How We Fixed Them)
### Bug #1: [Descriptive Name]
**Symptom:** [What you saw]
**Root Cause:** [What was actually wrong]
**Fix:** [What we did]
**Lesson:** [What to remember]
[Repeat for significant bugs]
---
## Best Practices Embedded in This Codebase
### 1. [Practice Name]
[Explain the practice and show an example from the code]
[Repeat for 3-5 key practices]
---
## How Good Engineers Think
[Meta-lessons about engineering mindset learned from this project]
---
## What's Next
[Future directions this architecture enables]
---
## Final Thoughts
[Wrap up with the core insight or philosophy]
---
*— [Sign-off that fits the project's personality]*
1. Analogies Over Abstractions
Instead of:
"The event system uses a pub-sub pattern with topic-based routing"
Write:
"Think of it like a newspaper. Publishers write articles, subscribers pick which sections they care about. The event bus is the printing press—it doesn't care what's in the message, just where it needs to go."
2. Show the Evolution
Instead of:
"We use worker threads for CPU-intensive tasks"
Write:
"Version 1 was single-threaded. Then we hit a wall processing 10,000 records—users stared at a frozen screen for 30 seconds. Worker threads turned that into a 3-second background job. The code is uglier, but the UX is worth it."
3. Honest About Trade-offs
Instead of:
"The system is highly scalable"
Write:
"It scales horizontally, but there's a catch: every new instance needs 2GB RAM for the in-memory cache. At 10 instances, you're paying for 20GB of RAM that's 80% duplicate data. We accept this because cold-start latency matters more than memory cost—for now."
4. Name the Dragons
Instead of:
"Be careful with the date handling code"
Write:
"The
parseDate()function looks innocent. It has eaten three afternoons of my life. The issue: it silently coerces invalid dates to the Unix epoch instead of throwing. If you see January 1, 1970 in your output, check your inputs."
Does the document answer:
Does the document:
Write({
file_path: "[project_root]/FOR_[NAME].md",
content: generatedDocument
})
Shallow (5-10 min read):
Medium (15-20 min read):
Deep (30+ min read):
Focus on:
Focus on:
Focus on:
# Full codebase explanation for yourself
/explain-codebase
# Explain a specific subsystem
/explain-codebase --domain "authentication"
# Create onboarding doc for a teammate
/explain-codebase --name "Sarah" --depth deep
# Explain an external project you're learning
/explain-codebase ~/code/some-open-source-project
Load these as needed for specific domains: