exploration-strategy

# Exploration Strategy > Status: v0.1 baseline draft — derived from the case catalog and axis definitions; awaiting trace evidence from Fable 5.1 case runs. ## When to apply - You are dropped into a repository you have never seen and asked to change or fix something in it. - A task description references symbols, modules, or behaviors you cannot yet locate in the code. - You are about to edit code whose callers, config sources, or side effects you have not confirmed. - A bug report describes a symptom but you do not yet know which layer produces it. - Your context was compacted or the session resumed, and your prior map of the codebase may be stale. - You catch yourself editing based on what a file "probably" contains rather than what you read. ## Core loop 1. **Restate the task as a location question.** Before any file read, write one sentence: "To do X, I need to find where Y happens and what touches it." This defines the exploration target; every subsequent read is judged against it. If you cannot phrase the target, the task itself is underspecified — resolve that first. 2. **Breadth-first structural scan (hard cap: ~10 tool calls).** List the top-level directory tree. Read the manifest (`package.json` / `Cargo.toml` / `go.mod` / `pyproject.toml` / `Makefile`) and the README headings only. Output for yourself: language, build system, test command, and 3-6 candidate directories relevant to the task. Do not open individual source files yet. 3. **Locate entry points.** Find where execution starts for the behavior in question: `main`, HTTP route tables, CLI arg parsers, event handlers, exported public API, scheduled jobs. Grep for the task's key nouns first — error strings, endpoint paths, flag names, config keys. Literal strings lifted from the task description are the highest-signal search keys available: near-zero false positives. 4. **Trace ONE representative path end-to-end.** Pick the single most task-relevant flow and follow it from entry point to observable effect (response written, file persisted, state mutated), reading only files on that path. Depth-first on one path beats shallow reads of ten files: the traced path reveals the layering conventions, error-handling style, and data shapes that generalize to the rest of the codebase. 5. **Maintain a known/assumed ledger.** As you trace, keep two explicit lists: - KNOWN — facts confirmed by reading code or running commands, each with a file:line or command receipt. - ASSUMED — inferences from names, docs, comments, or convention. Every ASSUMED item is a liability. Promote it to KNOWN by reading the code, or carry it into the plan as a named risk. Never let an assumption become load-bearing silently. 6. **Probe dynamically if cheap.** If the project runs or tests in one command, run it once before editing. One observed runtime behavior — a log line, a passing suite, a reproduced error — outweighs ten inferred ones, and it validates the build/verify loop before you depend on it. 7. **Apply the sufficiency test.** Stop exploring when you can answer all four: - (a) Where exactly will my edit go? - (b) What calls into it, and what does it call? - (c) How will I verify the change worked? - (d) What is the most likely way my change breaks something else? Four yes answers → begin editing immediately. Any no → that question names the next thing to read; read only that. 8. **Declare the model, then act.** Write a 3-6 line summary: architecture in one line, the traced path, the edit site, the verification plan, and the surviving ASSUMED items. This is your checkpoint — if an assumption later proves wrong, you know exactly which belief to revise instead of restarting exploration. 9. **Re-explore only on surprise.** During implementation, return to exploration only when reality contradicts the ledger (a KNOWN item was wrong, or an ASSUMED item turned out to matter). Fix that one entry, re-trace the minimal affected path, resume. Do not rescan the repository. ## Heuristics - Read the manifest and directory tree before any source file; the build system reveals the architecture faster than the code does. - Grep for literal strings from the task (error messages, route paths, config keys) before grepping for concept words. - One end-to-end trace of a representative path teaches more than skimming N sibling files; siblings usually mirror the traced one's structure. - Time-box the structural scan: if step 2 hits ~10 tool calls without candidate directories, switch to keyword grep instead of browsing further. - Exploration budget scales with blast radius, not repo size: a one-line fix in a 1M-line repo needs only the traced path around that line. - If two consecutive reads produce no new KNOWN entries, exploration has saturated — run the sufficiency test now. - Tests are compressed documentation: a module's test file states intended behavior and canonical call patterns; read it before the implementation when both exist. - Never trust a function by its name alone; if your change depends on its behavior, read its body — name/behavior mismatch is a top source of wrong edits. - Prefer one cheap runtime probe (run tests, curl the endpoint, execute the script) over three more file reads when the project boots in under a minute. - After context compaction or session resume, re-verify the top three KNOWN items you are about to build on; stale certainty is worse than admitted ignorance. ## Anti-patterns - **Edit-first archaeology.** Making the "obvious" change immediately, then discovering three call sites break. → Corrective: pass the four-question sufficiency test before the first edit; question (b) — callers and callees — is the one this failure skips. - **Exploration as procrastination.** Reading a twentieth file "for context" when the edit site was clear ten files ago, because reading feels safer than committing to an edit. → Corrective: the no-new-KNOWN-in-two-reads rule; when it fires, write the model summary and start editing. - **Breadth without depth.** Opening the first 30 lines of fifteen files and knowing the shape of nothing. → Corrective: pick one representative path and trace it fully to its side effect before opening any file off that path. - **Silent assumption stacking.** Chaining "this probably validates input" → "so the bug must be downstream" without confirming the first link. → Corrective: every "probably" enters the ASSUMED list out loud; any assumption load-bearing for the fix gets promoted by reading the code before building on it. - **Doc-trust over code-trust.** Building the mental model from a README or comments that no longer match the implementation. → Corrective: docs generate ASSUMED entries only; only code and command output generate KNOWN entries. - **Full restart on surprise.** One wrong assumption during implementation triggers re-reading the whole subsystem from scratch. → Corrective: revise the single falsified ledger entry, re-trace only paths that depended on it, resume. ## Worked example *Illustrative construction, not a recorded run.* Task: "POST /orders sometimes returns 500 when a discount code is applied. Fix it." Unfamiliar Node.js repo, ~40k lines. - Agent restates the target: "Find where POST /orders handles discount codes, and what in that path can throw." (step 1) - Agent lists the root tree and reads `package.json` → Express + Prisma, `npm test` exists. Candidate dirs: `src/routes/`, `src/services/`, `src/db/`. No source files opened yet. (step 2) - Agent greps `"orders"` under `src/routes/` → `routes/orders.js` maps POST to `orderService.create`. Greps `discount` → `services/discount.js`, `services/order.js`. Entry point located in 3 tool calls. (step 3) - Agent traces one path: `routes/orders.js` → `order.create()` → `discount.apply()` → Prisma write → response, reading each file on the path fully. Observes `discount.apply()` calls `code.toUpperCase()` on the raw request field with no null guard. (step 4) - Ledger. KNOWN: route wiring (`routes/orders.js:24`); `apply()` dereferences `code` unguarded (`services/discount.js:11`); error middleware converts any throw into a 500 (`middleware/errors.js:8`). ASSUMED: clients sometimes omit `code`; no upstream validation layer strips or defaults the field. (step 5) - Agent promotes the assumption because the fix depends on it: greps for validation middleware on the orders route → none registered. Runs `npm test` — green, so the test loop works. Reproduces with `curl -d '{"items":[...]}'` → 500 with `TypeError: Cannot read properties of undefined (reading 'toUpperCase')`. The assumption becomes KNOWN via runtime evidence. (steps 5-6) - Sufficiency test: edit site known (`discount.js:11`); callers/callees known (only `order.create` calls it; it only reads the codes table); verification known (rerun the curl repro, add a regression test); blast radius known (single call site). Four yes → exploration stops. (step 7) - Agent declares the model in 4 lines, adds a guard returning 400 for missing/unknown codes, adds a test for the no-code case, reruns curl → 400, `npm test` → green. Total exploration: ~9 tool calls, one path traced end-to-end, zero unrelated files read. (steps 8-9) ## Trace evidence | Case | Session | What it showed | |------|---------|----------------| | _awaiting case runs_ | — | — |