| 1 | --- |
| 2 | name: how |
| 3 | description: "Use for \"how does X work\" |
| 4 | disable-model-invocation: true |
| 5 | --- |
| 6 | |
| 7 | # How |
| 8 | |
| 9 | 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. |
| 10 | |
| 11 | Each spawn below names a role line in the `pstack-models.mdc` rule and a default. Set `model` to that line's value, or to the default if the rule or the line is missing. Leave |
| 12 | |
| 13 | ## Step 1. Assess Complexity |
| 14 | |
| 15 | If the scope is ambiguous, state your interpretation and explore. The user can redirect. |
| 16 | |
| 17 | - **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. |
| 18 | - **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. |
| 19 | |
| 20 | When in doubt, take the simple path. |
| 21 | |
| 22 | ## Step 2a. Explore (complex questions only) |
| 23 | |
| 24 | Decompose the question into 2 to 4 exploration angles, each a distinct slice of the subsystem. Spawn all explorers in a single message: |
| 25 | |
| 26 | - `subagent_type`: `general-purpose` |
| 27 | - `model`: the `how explorer` line, default |
| 28 | - `readonly`: `true` |
| 29 | |
| 30 | Each explorer gets the prompt in `references/explorer-prompt.md` with its angle filled in. Then go to Step 3. |
| 31 | |
| 32 | ## Step 2b. Direct Explain (simple questions) |
| 33 | |
| 34 | Spawn one Agent subagent that explores and explains in one pass: |
| 35 | |
| 36 | - `subagent_type`: `general-purpose` |
| 37 | - `model`: the `how explainer` line, default |
| 38 | - `readonly`: `true` |
| 39 | |
| 40 | Build its prompt from `references/explainer-prompt.md` without the explorer-findings section. Go to Step 4. |
| 41 | |
| 42 | ## Step 3. Synthesize (complex questions only) |
| 43 | |
| 44 | Once all explorers have returned, spawn one Agent subagent to synthesize their findings into one explanation: |
| 45 | |
| 46 | - `subagent_type`: `general-purpose` |
| 47 | - `model`: the `how explainer` line, default |
| 48 | - `readonly`: `true` |
| 49 | |
| 50 | Build its prompt from `references/explainer-prompt.md` with every explorer's findings filled in. |
| 51 | |
| 52 | ## Step 4. Present |
| 53 | |
| 54 | Present the explainer's output to the user. Light edits for clarity or context from the conversation are fine. Do not substantially rewrite it. |
| 55 | |
| 56 | ## Output Format |
| 57 | |
| 58 | 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. |