Build an accurate mental model of this codebase (or the area named in $ARGUMENTS)
and report it back so the user (and your future self) can navigate confidently.
1. Scope
If $ARGUMENTS names a path, feature, or subsystem, focus there. Otherwise survey
the whole repository. State your scope in one sentence before you start.
2. Explore in parallel
Do not read files one-by-one from the root. Dispatch focused exploration and let it
fan out:
- Shape: top-level layout, package manifests, build/test/lint scripts, entry points.
- Architecture: the main runtime surfaces and how data flows between them.
- Conventions: naming, error handling, module boundaries, test style.
- Risk: anything surprising (large files, dead code, TODO/FIXME, security-sensitive paths).
For a repo of any real size, launch the Explore agent (or several in one batch, one
per concern above) rather than reading everything yourself. Prefer breadth first, then
drill into the 3–5 files that actually matter.
3. Synthesize
Produce a tight report:
- One-paragraph summary: what this project is and does.
- Architecture map: the major components and how they connect (a short list or
simple diagram, not a wall of prose).
- Key files: the handful worth reading first, each with a one-line "why", formatted
as clickable
path:line references.
- Conventions: the patterns a new contributor must follow.
- Watch-outs: risks, rough edges, or anything that would surprise someone.
4. Offer next steps
End with 2–3 concrete things the user is now equipped to do (e.g. "ready to add a route",
"ready to debug the failing build"). Keep the whole report skimmable; link files, don't
paste them.
1---2name: revelation3description: Deeply explore a codebase and explain how it fits together.4---56Build an accurate mental model of this codebase (or the area named in `$ARGUMENTS`)7and report it back so the user (and your future self) can navigate confidently.89## 1. Scope1011If `$ARGUMENTS` names a path, feature, or subsystem, focus there. Otherwise survey12the whole repository. State your scope in one sentence before you start.1314## 2. Explore in parallel1516Do not read files one-by-one from the root. Dispatch focused exploration and let it17fan out:1819- **Shape**: top-level layout, package manifests, build/test/lint scripts, entry points.20- **Architecture**: the main runtime surfaces and how data flows between them.21- **Conventions**: naming, error handling, module boundaries, test style.22- **Risk**: anything surprising (large files, dead code, TODO/FIXME, security-sensitive paths).2324For a repo of any real size, launch the `Explore` agent (or several in one batch, one25per concern above) rather than reading everything yourself. Prefer breadth first, then26drill into the 3–5 files that actually matter.2728## 3. Synthesize2930Produce a tight report:3132- **One-paragraph summary**: what this project is and does.33- **Architecture map**: the major components and how they connect (a short list or34 simple diagram, not a wall of prose).35- **Key files**: the handful worth reading first, each with a one-line "why", formatted36 as clickable `path:line` references.37- **Conventions**: the patterns a new contributor must follow.38- **Watch-outs**: risks, rough edges, or anything that would surprise someone.3940## 4. Offer next steps4142End with 2–3 concrete things the user is now equipped to do (e.g. "ready to add a route",43"ready to debug the failing build"). Keep the whole report skimmable; link files, don't44paste them.
patrickking67