references/explainer-prompt.md
# Explainer Prompt Template
Build the explainer subagent's prompt from this template. Fill in the placeholders.
---
You are writing an architectural explanation for a senior engineer. Multiple explorer agents have traced different slices of the codebase in parallel and gathered findings. Synthesize their findings into one coherent, well-structured explanation.
## Original Question
> {QUESTION}
## Explorer Findings
{EXPLORER_FINDINGS_ALL}
## Instructions
The explorers each investigated a different angle of the same subsystem. Their findings will overlap in places and may occasionally contradict. Reconcile them. Merge overlapping descriptions, resolve contradictions by checking the code yourself, and combine the separate slices into a unified picture.
Write an explanation a senior engineer unfamiliar with this area could read and walk away with a solid mental model, understanding the architecture well enough to start working in it confidently.
You have read-only access to the codebase to check anything, clarify a detail, or fill a gap. Use Read, Grep, and Glob as needed. The explorers did the work, so you shouldn't need to re-explore from scratch.
## Output Format
Use this structure, adapted to what makes sense for the question. Not every section is needed for every question.
### Overview
1-2 paragraphs. What is this thing, what does it do, why does it exist. Someone should be able to read just this and decide whether to keep reading.
### Key Concepts
The important types, services, or abstractions needed to follow the rest. Brief definitions, not exhaustive.
### How It Works
The core of the explanation, and the longest section. Walk through the flow: what triggers it, what happens step by step, where data goes, what the decision points are.
Use prose, not pseudocode. Reference specific files and functions so the reader knows where to look, but don't dump large code blocks unless a snippet is essential to a point.
When the flow involves multiple components talking to each other, or data transforming through stages, include a diagram. Use mermaid (```mermaid) for structured flows (sequence diagrams, flowcharts, component graphs) or ASCII art for simpler relationships where mermaid would be overkill. Use your judgment. A diagram should clarify, not decorate. If prose covers the flow, skip the diagram.
### Where Things Live
A brief file/directory map. Just the ones someone would need to start working here.
### Gotchas
Non-obvious things, surprising behavior, historical context, pitfalls. Skip this section if there's nothing worth calling out.
## Communication Style
- Use concrete language, not abstractions-about-abstractions
- Say "the `UserService` calls `AuthClient.refresh()`" not "the service delegates to the client"
- When something is complex, explain why it's complex. Don't just describe the complexity
- When something is simple, don't pad it out
- If there's a helpful analogy, use it. If there isn't, don't force one
- If the explorers flagged open questions or gaps, acknowledge them rather than hiding them
references/explorer-prompt.md
# Explorer Prompt Template
Build each explorer subagent's prompt from this template. Fill in the placeholders.
---
You are exploring a codebase to understand how something works. Gather facts: trace code paths, read implementations, map components. A separate agent will write the human-facing explanation from your findings, so favor thoroughness and accuracy over prose.
Other explorers are investigating different slices of the same subsystem in parallel. Don't try to cover everything. Focus on your assigned angle and go deep.
## Question
> {QUESTION}
## Your Exploration Angle
{EXPLORATION_ANGLE}
## Exploration Instructions
Start by finding the relevant code. Use Glob to find directories and files, Grep to find key symbols, Read to understand the actual implementation. Don't guess from names. Read the code.
Follow this pattern:
1. **Find the entry point.** What triggers this behavior? A user action, an API call, a scheduled job? Find where it starts.
2. **Trace the flow.** Follow the call chain from the entry point. Read each function. Understand what data flows through and how it transforms.
3. **Map the key abstractions.** What types, interfaces, services, or classes are central? Read their definitions. Understand what they represent and why they exist.
4. **Find the boundaries.** Where does this subsystem interface with others? What goes in, what comes out?
5. **Look for the non-obvious.** Anything surprising? Anything that looks like a historical artifact? Anything a newcomer would misunderstand?
Keep exploring until you can describe the full picture without hand-waving. If you hit a part you can't trace, say so explicitly. "I couldn't determine how X connects to Y" is better than making something up.
## Output
Return your findings in this structure. Be factual and specific. Reference exact file paths, function names, type names, and line numbers where relevant.
### Components Found
The key types, services, classes, and abstractions. For each: name, file path, and a one-sentence description of what it does.
### Flow
The execution flow step by step. For each step: what function/method runs, what file it's in, what it does, what it calls next. Include the data that flows between steps.
### Files Read
Every file you read during exploration, so the explainer can reference them.
### Boundaries
Where this subsystem connects to other parts of the codebase. The inputs and outputs.
### Non-Obvious Things
Anything surprising, historically motivated, or easy to get wrong. Things that look like they should work one way but work another.
### Open Questions
Anything you couldn't fully trace or understand. Be honest about gaps.
SKILL.md
---
name: how
description: "Use for \"how does X work\", code walkthroughs before changing something, and placement / ownership / layering questions (\"where should this live\", \"which package owns this\", \"is this the right layer\"). Explains subsystem architecture, runtime flow, onboarding mental models. Use why for motivation."
disable-model-invocation: true
---
# How
Explore the codebase to answer "how does X work?" questions. Produce architectural explanations at the level of a senior engineer onboarding onto a subsystem, enough to build a working mental model, not so much that it reads like annotated source code.
## Step 1. Assess Complexity
If the scope is ambiguous, state your interpretation and explore. The user can redirect.
- **Simple** (a single module, a small utility, a narrow question such as "how does function X work"): no explorers. One explainer explores and explains in a single pass. Go to Step 2b.
- **Complex** (a subsystem spanning multiple files or services, a cross-cutting feature, a full architectural overview): spawn parallel explorers first, then hand off to the explainer. Go to Step 2a.
When in doubt, take the simple path.
## Step 2a. Explore (complex questions only)
Decompose the question into 2 to 4 exploration angles, each a distinct slice of the subsystem. Spawn all explorers in a single message:
- `subagent_type`: `generalPurpose`
- `model`: your configured how-explorer model (default `grok-4.6-fast-xhigh`)
- `readonly`: `true`
Each explorer gets the prompt in `references/explorer-prompt.md` with its angle filled in. Then go to Step 3.
## Step 2b. Direct Explain (simple questions)
Spawn one Task subagent that explores and explains in one pass:
- `subagent_type`: `generalPurpose`
- `model`: your configured how-explainer model (default `claude-fable-5-1-thinking-max`)
- `readonly`: `true`
Build its prompt from `references/explainer-prompt.md` without the explorer-findings section. Go to Step 4.
## Step 3. Synthesize (complex questions only)
Once all explorers have returned, spawn one Task subagent to synthesize their findings into one explanation:
- `subagent_type`: `generalPurpose`
- `model`: your configured how-explainer model (default `claude-fable-5-1-thinking-max`)
- `readonly`: `true`
Build its prompt from `references/explainer-prompt.md` with every explorer's findings filled in.
## Step 4. Present
Present the explainer's output to the user. Light edits for clarity or context from the conversation are fine. Do not substantially rewrite it.
## Output Format
The explanation uses the sections defined in `references/explainer-prompt.md`, dropping any that do not apply: Overview, Key Concepts, How It Works, Where Things Live, Gotchas.