Codebase Explanation
Explain mechanics from the code that exists now.
Read context map when the explanation must support later navigation or a resumed session.
Workflow
- Clarify the behavior or path the user wants explained and bound the relevant component.
- Locate entrypoints, public interfaces, owners of state, configuration, and the main callers and consumers.
- Trace control flow and data flow separately. Name validation, transformations, persistence, concurrency, retries, and error paths where present.
- Cite concrete files and symbols. Distinguish runtime code from tests, fixtures, generated output, documentation, and proposed designs.
- Verify important claims through tests, call sites, configuration, or safe execution when appropriate and authorized.
- Explain the smallest coherent model first, then add edge cases and uncertainty.
Boundaries
Use investigate-design-rationale for historical intent or why a design was chosen.
- Current code can establish mechanics, not historical intent. Label rationale as inference unless direct evidence supports it.
- Do not change code merely because the explanation reveals a defect or awkward design.
- Do not imply that an unexecuted path, configuration, or deployment is active.
Output
Lead with the answer. Use the shortest format that retains the required evidence and limits; expand when requested or needed. The items below describe required content, not mandatory headings.
Lead with a plain-language summary, then provide Entrypoints, Flow, State and ownership, Interfaces, Failure paths, Evidence, and Unknowns.
Example
Synthetic example; not an observed client result.
Input: Requests enter Router, call InvoiceService, and persist through InvoiceStore.
Output: Router handles transport, InvoiceService applies invoice rules, and InvoiceStore owns persistence. Those observed calls define the current request path.
1---2name: explain-codebase3description: "Explains existing code when asked how a request flows, where behavior lives, or what a module does; grounds the explanation in current files rather than inferred historical intent."4license: MIT5metadata:6 source: https://skillmd.com/skills/jovanipink/explain-codebase7 author: "Measured Studios"8 version: "0.19.0"9 plugin: "measured-workflows"10 invocation: "implicit"11 provenance: "original"12 risk_class: "read-only"13---1415# Codebase Explanation1617Explain mechanics from the code that exists now.1819Read [context map](references/context-map.md) when the explanation must support later navigation or a resumed session.2021## Workflow22231. Clarify the behavior or path the user wants explained and bound the relevant component.242. Locate entrypoints, public interfaces, owners of state, configuration, and the main callers and consumers.253. Trace control flow and data flow separately. Name validation, transformations, persistence, concurrency, retries, and error paths where present.264. Cite concrete files and symbols. Distinguish runtime code from tests, fixtures, generated output, documentation, and proposed designs.275. Verify important claims through tests, call sites, configuration, or safe execution when appropriate and authorized.286. Explain the smallest coherent model first, then add edge cases and uncertainty.2930## Boundaries3132Use `investigate-design-rationale` for historical intent or why a design was chosen.3334- Current code can establish mechanics, not historical intent. Label rationale as inference unless direct evidence supports it.35- Do not change code merely because the explanation reveals a defect or awkward design.36- Do not imply that an unexecuted path, configuration, or deployment is active.3738## Output3940Lead with the answer. Use the shortest format that retains the required evidence and limits; expand when requested or needed. The items below describe required content, not mandatory headings.4142Lead with a plain-language summary, then provide `Entrypoints`, `Flow`, `State and ownership`, `Interfaces`, `Failure paths`, `Evidence`, and `Unknowns`.4344## Example4546Synthetic example; not an observed client result.4748Input: Requests enter Router, call InvoiceService, and persist through InvoiceStore.4950Output: Router handles transport, InvoiceService applies invoice rules, and InvoiceStore owns persistence. Those observed calls define the current request path.