How

How

Explore the codebase to answer "how does X work?" Produce an architectural explanation at the level of a senior engineer onboarding onto a subsystem.

Explain only. For adversarial review of an architecture or a diff, route to interrogate or structural-review.

Companion to why. This skill answers what the code does. why answers what forces led to its shape.

Contract

Inputs:

• A how-question: subsystem, feature flow, architectural overview, or runtime trace

Outputs:

• The structured explanation below

Creates/Modifies:

• None

External Side Effects:

• None. Read-only exploration.

Confirmation Required:

• None

Delegates To:

• None. May spawn read-only explorer and explainer subagents.

Explain

Step 1. Understand the question

Parse the ask. If ambiguous, state the best-guess interpretation and proceed. Do not ask. Let the user redirect.

Simple (one module, a narrow function): skip explorer agents. The explainer explores and explains in one pass.

Complex (multiple files or services, a cross-cutting feature): spawn 2-4 parallel explorers, then one explainer. When in doubt, lean simple.

Step 2a. Explore (complex only)

Decompose into 2-4 distinct slices so explorers do not duplicate work. Spawn all explorers in one message on the fast cheap tier, read-only. Each explorer gets references/explorer-prompt.md plus its slice. Each traces input to output without hand-waving.

Step 2b. Direct explain (simple)

Spawn one read-only explainer on the strongest judgment tier. It explores and writes the explanation. Use references/explainer-prompt.md.

Step 3. Synthesize (complex only)

Once explorers return, spawn one explainer on the strongest judgment tier with all findings. It reconciles overlap and contradictions.

Step 4. Present

Present the explainer's output. Light edits for clarity are fine. Do not substantially rewrite.

Output format

Overview. 1-2 paragraphs. What it is, what it does, why it exists.

Key Concepts. The types, services, or abstractions needed to follow the rest.

How It Works. The flow: trigger, steps, data, decision points. Prose, not pseudocode. Cite files and functions.

Where Things Live. A brief map of the relevant files.

Gotchas. Non-obvious edges and historical scars.

How procedure

Read how procedure when running this workflow. Apply the authorized scope and mode of this entry point to every step. Resolve other skills through this distribution’s active catalog; resolve resources relative to the installed skill directory.