codebase-exploration-loop
A configuration of loop-controller. That skill supplies the loop
machinery — primitive selection, the full guardrail stack, state
externalization. This skill supplies the three things specific to "understand
this codebase": the seed-question proof (a default-FAIL question list that
only flips on a code citation), the read-only fan-out that maps subsystems
in parallel, and the loop-until-dry stop on remaining understanding gaps.
Read loop-controller for the guardrails; they're inherited, not repeated here.
Why disable-model-invocation: this loop spends tokens fanning out a wave
of subagents per iteration, repeatedly, until your questions are answered. It
is user-driven — you want to type /codebase-exploration-loop with your
questions, not have Claude silently launch an exploration swarm because you
asked a passing question about a file.
The 5-part contract
| Part |
This loop |
| trigger |
"I don't understand X" about an unfamiliar repo — onboarding, reverse-engineering, or an explicit /codebase-exploration-loop with a list of seed questions |
| action |
ONE round: read the gap list → fan out read-only subagents (one per open subsystem/question, parallelism capped) → each returns findings + file:line citations → synthesize into the architecture summary → mark answered questions, surface newly-discovered gaps |
| proof |
the architecture summary answers every seed question, each answer citing a path:line (or symbol) in the code, with zero open "I don't understand X" gaps — default-FAIL: every question starts answered: false and flips only on a citation |
| memory |
seed-questions.json (the default-FAIL question list + the new gaps each round surfaces) and ARCHITECTURE-SUMMARY.md (the growing synthesis) — durable across rounds; no reliance on conversation memory |
| stop |
every question answered: true with a citation OR loop-until-dry (a round surfaces no new gaps and answers nothing new) OR iteration/round cap OR no-progress for 2 rounds OR budget cap |
The proof: seed questions answered with citations, default-FAIL
"Understood" is not "I read a lot of files and it feels familiar." It is every
seed question on the list marked answered: true, and each answer points at the
path:line (or symbol) in the actual code that backs it. Assume not
understood until that citation exists — that's the default-FAIL stance, and it's
what stops the loop from declaring victory on a vibe. An answer with no code
citation is an unanswered question.
Name the artifact: seed-questions.json (one entry per question, each defaulting
answered: false) plus ARCHITECTURE-SUMMARY.md (the prose synthesis that cites
the code per answer). Both must agree before the loop is done — a question can't
be true in the JSON without a citation in the summary.
Step 1 — Capture the seed questions (default-FAIL)
Before any fan-out, write the seed questions to seed-questions.json, every one
answered: false. These are your questions — "where does a request enter?",
"how is auth enforced?", "what's the data model?", "where's the build
configured?" — not a generic checklist. If the user gave questions, use them
verbatim; otherwise propose a starter set and confirm. The list grows: when a
round reveals you didn't understand something you thought you did, add it as a
new default-FAIL entry. The loop is done only when the list is fully true and
stops growing. The JSON schema and the gap-discovery rule are in
references/exploration.md.
Step 2 — Fan out read-only subagents (cap the parallelism)
This is the deep-research fan-out shape pointed at the local codebase:
one subagent per open subsystem or question, dispatched in parallel, each given
Read/Grep/Glob/Bash-to-inspect only — no Write/Edit, no web. A read-only
mapper cannot accidentally change the code it's studying, and (per
loop-controller's evaluator pattern) a fresh subagent reports what's there
rather than what it hopes is there. Each returns a short findings memo with
path:line citations.
Cap the fan-out width per round (default ~4-6 concurrent) — per loop-controller
Step 5, more parallel readers do not equal faster understanding, they equal a
synthesis you can't reconcile and a budget you can't predict. The dispatch
recipe (and the /deep-research-vs-this distinction) is in
references/exploration.md.
Step 3 — Synthesize, then find the next gaps
Merge the round's memos into ARCHITECTURE-SUMMARY.md: update the section per
subsystem, attach each citation to the question it answers, and flip those
questions to answered: true. Then do the load-bearing step — read the
summary as a whole and ask what you still can't explain. A subsystem memo that
answers "how does X work" usually exposes "...but what calls X, and where does
its data come from?" Those become new default-FAIL entries. This is the
loop-until-dry engine: the loop runs until a round both answers nothing new and
surfaces no new gaps.
How this differs from its neighbors
This loop's whole reason to exist is the convergence on YOUR questions — it
is the lightweight, iterative member of a family of heavier one-shot tools, and
it delegates to them rather than re-implementing them.
- vs
repo-deep-dive — that is a one-shot, heavyweight deliverable: a
comprehensive 12-14 document reference series for a whole repo, grounded in a
pre-run deep-research markdown. This loop is the lighter, iterative,
seed-question-driven path that stops the moment your questions are answered
— it may never document a subsystem you didn't ask about. When the user wants
the full series, hand off to repo-deep-dive (the boundary and handoff
trigger are in references/exploration.md); don't grow into it.
- vs
project-profiler — that produces a fixed one-shot artifact
(CLAUDE.md + profile.yaml) on a standard template. This loop's deliverable
is the question-answering summary plus the loop discipline. It can feed
project-profiler — invoke it to refresh CLAUDE.md from what the loop learned
— but profiling is not its proof.
- vs
deep-research — same fan-out → verify → synthesize shape, but
deep-research goes to the web with citations to sources; this goes to the
local code with citations to path:line, read-only, no network.
If after those boundaries this still reads like "deep-research on local code,"
that is exactly the point: the genuine contribution is the loop-until-the-seed-
questions-are-answered convergence and the read-only fan-out discipline —
not a new documentation format.
Guardrails specific to this loop
Inherits the full stack from loop-controller → references/safety.md. The caps
this loop sets:
- Round / iteration cap — default ~6-8 rounds (read from
.claude/profile.yaml if set). Hitting it is a stop-and-report what's still
unanswered, not a license to mark questions true without a citation.
- No-progress detection — if a round answers no new question and surfaces
no new gap, the loop is dry — stop. If the same gap survives 2
consecutive rounds with no new citation, surface it to the human; some
questions need the code's author, not a third fan-out.
- Budget cap — a fan-out of subagents per round multiplies token spend; per
loop-controller enforce a ceiling that terminates the loop, and keep the
per-round width capped (Step 2).
- Read-only is the boundary. Mapper subagents get no Write/Edit and no web —
full stop. This loop studies code; it does not modify it. Refreshing
CLAUDE.md is a separate, explicit project-profiler invocation, not
something a mapper does mid-round. There is no irreversible action inside the
loop, so it is AFK-safe within that read-only boundary.
- Never cheat the proof. Don't flip a question to
answered: true without a
real code citation, and don't drop a hard question off the list to empty it. A
summary that "answers" by hand-waving is a finding, not understanding.
Choosing the driver primitive
Per loop-controller Step 1, this is a dynamic-workflow / fan-out loop, not
a /goal finish-line race — each round is a parallel dispatch:
- Default — dynamic workflow / fan-out (the
/deep-research engine over
local code): each round fans read-only mappers across subsystems, then
synthesizes. Compose with the orchestrator's Workflow mode when you want
the fan-out managed as a workflow with an explicit token budget.
/goal can drive the outer convergence — condition: "seed-questions.json
has every entry answered: true with a citation, or stop after N rounds" — with
each turn doing one fan-out-and-synthesize round. Remember /goal has no native
budget; embed the round cap.
Reference files
references/exploration.md — the seed-questions.json schema and default-FAIL
/ gap-discovery rule, the read-only fan-out dispatch pattern (and how it differs
from /deep-research), and the hand-off-to-repo-deep-dive boundary.
1---2name: codebase-exploration-loop3version: 1.0.04description: >-5 Build a working mental model of an unfamiliar codebase by looping: fan out6 read-only subagents to map subsystems, synthesize, find the gaps in your7 understanding, and repeat until a written architecture summary answers every8 seed question — each answer citing where in the code it comes from. The9 deep-research fan-out shape applied to the LOCAL codebase (Read/Grep, no web),10 with a subagent-parallelism cap and a loop-until-dry stop on understanding11 gaps. Use when onboarding to a new repo,12 reverse-engineering someone else's code, or answering "I don't understand how X13 works here" before you touch it.14 Trigger on "help me understand this codebase", "onboard me to this repo", "how15 does X work in this code", "build a mental model of this project", "explore16 this codebase", "map this codebase", "I don't understand this code", "explore17 until I understand". A configuration of loop-controller.18requires_claude_code: true19min_plan: starter20disable-model-invocation: true21allowed-tools: ["Read", "Write", "Grep", "Glob", "Bash", "Agent", "Workflow"]22composes_with: ["loop-controller", "project-profiler", "repo-deep-dive", "orchestrator"]23spawned_by: []24metadata:25 source: https://skillmd.com/skills/ivy00johns/codebase-exploration-loop26---2728# codebase-exploration-loop2930> **A configuration of [`loop-controller`].** That skill supplies the loop31> machinery — primitive selection, the full guardrail stack, state32> externalization. This skill supplies the three things specific to "understand33> this codebase": the **seed-question proof** (a default-FAIL question list that34> only flips on a code citation), the **read-only fan-out** that maps subsystems35> in parallel, and the **loop-until-dry** stop on remaining understanding gaps.36> Read `loop-controller` for the guardrails; they're inherited, not repeated here.37>38> **Why `disable-model-invocation`:** this loop spends tokens fanning out a wave39> of subagents per iteration, repeatedly, until your questions are answered. It40> is user-driven — you want to *type* `/codebase-exploration-loop` with your41> questions, not have Claude silently launch an exploration swarm because you42> asked a passing question about a file.4344## The 5-part contract4546| Part | This loop |47|---|---|48| **trigger** | "I don't understand X" about an unfamiliar repo — onboarding, reverse-engineering, or an explicit `/codebase-exploration-loop` with a list of seed questions |49| **action** | ONE round: read the gap list → fan out read-only subagents (one per open subsystem/question, parallelism capped) → each returns findings + file:line citations → synthesize into the architecture summary → mark answered questions, surface newly-discovered gaps |50| **proof** | the architecture summary answers **every** seed question, each answer **citing a `path:line` (or symbol) in the code**, with zero open "I don't understand X" gaps — default-FAIL: every question starts `answered: false` and flips only on a citation |51| **memory** | `seed-questions.json` (the default-FAIL question list + the new gaps each round surfaces) and `ARCHITECTURE-SUMMARY.md` (the growing synthesis) — durable across rounds; no reliance on conversation memory |52| **stop** | every question `answered: true` with a citation **OR** loop-until-dry (a round surfaces no new gaps and answers nothing new) **OR** iteration/round cap **OR** no-progress for 2 rounds **OR** budget cap |5354## The proof: seed questions answered with citations, default-FAIL5556"Understood" is not "I read a lot of files and it feels familiar." It is **every57seed question on the list marked `answered: true`, and each answer points at the58`path:line` (or symbol) in the actual code that backs it**. Assume *not*59understood until that citation exists — that's the default-FAIL stance, and it's60what stops the loop from declaring victory on a vibe. An answer with no code61citation is an unanswered question.6263Name the artifact: `seed-questions.json` (one entry per question, each defaulting64`answered: false`) plus `ARCHITECTURE-SUMMARY.md` (the prose synthesis that cites65the code per answer). Both must agree before the loop is done — a question can't66be `true` in the JSON without a citation in the summary.6768## Step 1 — Capture the seed questions (default-FAIL)6970Before any fan-out, write the seed questions to `seed-questions.json`, every one71`answered: false`. These are *your* questions — "where does a request enter?",72"how is auth enforced?", "what's the data model?", "where's the build73configured?" — not a generic checklist. If the user gave questions, use them74verbatim; otherwise propose a starter set and confirm. The list grows: when a75round reveals you didn't understand something you thought you did, add it as a76new default-FAIL entry. The loop is done only when the list is fully `true` *and*77stops growing. The JSON schema and the gap-discovery rule are in78`references/exploration.md`.7980## Step 2 — Fan out read-only subagents (cap the parallelism)8182This is the `deep-research` fan-out shape pointed at the **local codebase**:83one subagent per open subsystem or question, dispatched in parallel, each given84**Read/Grep/Glob/Bash-to-inspect only — no Write/Edit, no web**. A read-only85mapper cannot accidentally change the code it's studying, and (per86`loop-controller`'s evaluator pattern) a fresh subagent reports what's *there*87rather than what it hopes is there. Each returns a short findings memo with88`path:line` citations.8990Cap the fan-out width per round (default ~4-6 concurrent) — per `loop-controller`91Step 5, more parallel readers do not equal faster understanding, they equal a92synthesis you can't reconcile and a budget you can't predict. The dispatch93recipe (and the `/deep-research`-vs-this distinction) is in94`references/exploration.md`.9596## Step 3 — Synthesize, then find the next gaps9798Merge the round's memos into `ARCHITECTURE-SUMMARY.md`: update the section per99subsystem, attach each citation to the question it answers, and flip those100questions to `answered: true`. Then do the load-bearing step — **read the101summary as a whole and ask what you still can't explain.** A subsystem memo that102answers "how does X work" usually exposes "...but what calls X, and where does103its data come from?" Those become new default-FAIL entries. This is the104loop-until-dry engine: the loop runs until a round both answers nothing new and105surfaces no new gaps.106107## How this differs from its neighbors108109This loop's whole reason to exist is the **convergence on YOUR questions** — it110is the lightweight, iterative member of a family of heavier one-shot tools, and111it *delegates* to them rather than re-implementing them.112113- **vs [`repo-deep-dive`]** — that is a **one-shot, heavyweight deliverable**: a114 comprehensive 12-14 document reference series for a whole repo, grounded in a115 pre-run deep-research markdown. This loop is the **lighter, iterative,116 seed-question-driven** path that stops the moment *your* questions are answered117 — it may never document a subsystem you didn't ask about. When the user wants118 the full series, **hand off to `repo-deep-dive`** (the boundary and handoff119 trigger are in `references/exploration.md`); don't grow into it.120- **vs [`project-profiler`]** — that produces a fixed one-shot artifact121 (`CLAUDE.md` + `profile.yaml`) on a standard template. This loop's deliverable122 is the **question-answering summary plus the loop discipline**. It can *feed*123 project-profiler — invoke it to refresh `CLAUDE.md` from what the loop learned124 — but profiling is not its proof.125- **vs `deep-research`** — same fan-out → verify → synthesize *shape*, but126 deep-research goes to the **web with citations to sources**; this goes to the127 **local code with citations to `path:line`**, read-only, no network.128129If after those boundaries this still reads like "deep-research on local code,"130that is exactly the point: the genuine contribution is the **loop-until-the-seed-131questions-are-answered convergence** and the **read-only fan-out discipline** —132not a new documentation format.133134## Guardrails specific to this loop135136Inherits the full stack from `loop-controller` → `references/safety.md`. The caps137this loop sets:138139- **Round / iteration cap** — default ~6-8 rounds (read from140 `.claude/profile.yaml` if set). Hitting it is a *stop-and-report what's still141 unanswered*, not a license to mark questions `true` without a citation.142- **No-progress detection** — if a round answers no new question **and** surfaces143 no new gap, the loop is **dry** — stop. If the **same** gap survives **2144 consecutive rounds** with no new citation, surface it to the human; some145 questions need the code's author, not a third fan-out.146- **Budget cap** — a fan-out of subagents per round multiplies token spend; per147 `loop-controller` enforce a ceiling that *terminates* the loop, and keep the148 per-round width capped (Step 2).149- **Read-only is the boundary.** Mapper subagents get no Write/Edit and no web —150 full stop. This loop *studies* code; it does not modify it. Refreshing151 `CLAUDE.md` is a separate, explicit `project-profiler` invocation, not152 something a mapper does mid-round. There is no irreversible action inside the153 loop, so it is AFK-safe within that read-only boundary.154- **Never cheat the proof.** Don't flip a question to `answered: true` without a155 real code citation, and don't drop a hard question off the list to empty it. A156 summary that "answers" by hand-waving is a *finding*, not understanding.157158## Choosing the driver primitive159160Per `loop-controller` Step 1, this is a **dynamic-workflow / fan-out** loop, not161a `/goal` finish-line race — each round *is* a parallel dispatch:162163- **Default — dynamic workflow / fan-out** (the `/deep-research` engine over164 local code): each round fans read-only mappers across subsystems, then165 synthesizes. Compose with the [`orchestrator`]'s Workflow mode when you want166 the fan-out managed as a workflow with an explicit token budget.167- **`/goal`** can drive the *outer* convergence — condition: "`seed-questions.json`168 has every entry `answered: true` with a citation, or stop after N rounds" — with169 each turn doing one fan-out-and-synthesize round. Remember `/goal` has no native170 budget; embed the round cap.171172## Reference files173174- `references/exploration.md` — the `seed-questions.json` schema and default-FAIL175 / gap-discovery rule, the read-only fan-out dispatch pattern (and how it differs176 from `/deep-research`), and the hand-off-to-`repo-deep-dive` boundary.177178[`loop-controller`]: ../loop-controller/SKILL.md179[`repo-deep-dive`]: ../../workflows/repo-deep-dive/SKILL.md180[`project-profiler`]: ../../workflows/project-profiler/SKILL.md181[`orchestrator`]: ../../orchestrator/SKILL.md