OutlineDriven Paced explanation
Contract
| Field | Bound contract |
|---|---|
| Trigger | User asks to teach or explain a subsystem, module, pattern, or change. |
| Authority | Read-only. No file, VCS, credential, paid, published, deployed, or remote mutation. |
| Side effect | Chat output only; inline diagrams on request. |
| Done | Four layers delivered in sequence (purpose, structure, behavior, code), each grounded in concrete file paths, line ranges, or symbols from the resolved target; the explanation progresses purpose → structure → behavior → code without skipping a layer; deeper layers offered after each. The explanation may stop after any delivered layer that was followed by a deeper offer. |
Inputs
- Target (required): the subsystem, module, pattern, or change to explain. Supplied as an argument, a file path, or the current conversation context.
- Depth (optional): explicit depth ceiling or focus area. Absent means begin at the purpose layer (Layer 1) and offer deeper.
Procedure
- Identify the target. Resolve the target to concrete code: file paths, line ranges, and key symbols. Use
grep,glob,read, or LSP tools. If the target cannot be resolved after one read of the conversation, stop and ask one clarifying question naming what to explain. Done when: the target is resolved to concrete file paths, line ranges, and key symbols, or one clarifying question is asked. - Map the scope. Identify the entry point, internal structure, and external interfaces of the target. Build a lightweight mental map: what the subsystem owns, what it delegates, and how it is named in the codebase. Done when: the entry point, internal structure, and external interfaces are identified.
- Explain in progressive layers. Deliver the explanation as a flat sequence from surface to depth, with each layer building on the previous:
- Layer 1: Purpose: what the target does and why it exists in one sentence.
- Layer 2: Structure: how the target is organized and what the main components are.
- Layer 3: Behavior: how the components interact and what the key inputs and outputs are.
- Layer 4: Code: the key symbols, line ranges, and the logic they encode. Done when: all four layers are delivered in sequence from purpose to code.
- Offer deeper layers. After each layer, invite the user to request more depth. Accept a focus area or continue layer by layer. Stop when the user stops. Done when: an explicit invitation to go deeper follows each delivered layer, and no layer is delivered without the offer that follows it.
- Render diagrams on request. If the user asks for a diagram, render an inline diagram (ASCII, Mermaid, or HTML) showing the structure or flow. No external diagram tool required. Done when: the requested diagram is rendered inline.
Failure and recovery
- Unresolvable target: the target cannot be identified from argument, path, or conversation context. Stop. Ask one question naming what to explain. Do not invent a target.
- Partial code context: the target resolves to a partial view of the codebase. Explain what is visible. Mark where the picture is incomplete. Do not claim the explanation is complete when it is not.
- No rollback required: this skill is read-only. No file, state, or remote resource is modified.
Output
A single plain explanation in layered prose, starting from purpose and progressing to code depth on request. Diagrams rendered inline on explicit request. No persistent workspace, no session state, no multi-turn follow-up required.