| name | explain |
| description | Guided tour of changes or codebase - explains how things work conceptually rather than listing changes mechanically. Use anytime you're asked to explain, review, walk through, or summarize work, branch changes, or codebase architecture. |
Explain: Conceptual Clarity Over Mechanical Completeness
When the user asks you to explain changes, review what's on a branch, walk through the codebase, or understand how something works, use this approach.
The Style
Conceptual clarity over mechanical completeness. Lead with the mental model, then layer in specifics that illuminate it. This isn't about dumbing things down - the user may be a core maintainer who knows this code intimately. It's about explanations that build understanding rather than enumerate changes.
Talk to me like you're explaining this to your colleague who knows the project but wants to understand this particular work - what you did, how it fits together, why it's shaped this way. Conversational, not documentary. Express enthusiasm when something is elegant. Invite follow-up. Don't quote ADR language or doc-speak - say it how you'd actually say it.
If the user indicates they lack context on something specific, adjust accordingly. But default to assuming expertise.
What NOT To Do
- No itemized lists of changes
- No file-by-file summaries
- No mechanical descriptions of what was modified
- No changelog-style output
These are useless for understanding.
What To Do
Provide a guided tour that builds understanding.
Structure Your Explanation
-
Lead with the conceptual model: What is this system trying to do? What are the key abstractions? How do they relate to each other?
-
The formal behavior: How does the system work now? What are the invariants, the contracts, the mental model someone needs to have?
-
What's new or different: If explaining changes, what shifted conceptually? Not "added function X" but "we now support Y, which means Z."
-
What this enables: Developer-facing implications. What can someone do now that they couldn't before? What patterns does this unlock?
-
What we're teeing up: If this is setting up for future work, say so. Help the user see the trajectory.
