context-retrieval-loop · diff
git:20260504.2eb5b21 to git:20260504.96c4113
100 added, 1 removed. Audit B to A.
---
name: context-retrieval-loop
- description: Root copy placeholder
+ description: Deterministic 3-cycle loop for gathering codebase context before acting. Broad search → exact source and tests → target-specific docs and setup. Stop after enough context or report what is still missing.
---
+
+ # Context Retrieval Loop
+
+ Gather the right codebase context before making changes or spawning subagents. Prevents acting on incomplete information.
+
+ ## When to Use
+
+ - Starting work on an unfamiliar area of a codebase
+ - Spawning a subagent that needs targeted file context
+ - Failing to find a relevant file on the first search pass
+ - Unsure which files are in scope for a task
+
+ ## The 3-Cycle Loop
+
+ Each cycle builds on the previous. Stop early when you have enough context. Do not exceed 3 cycles.
+
+ ### Cycle 1 — Broad Search
+
+ ```bash
+ # Find files by keyword
+ rg "<primary-keyword>" --type ts --type js -l
+ rg "<primary-keyword>" --glob "*.py" -l
+
+ # Find by filename pattern
+ find . -name "*<keyword>*" -not -path "*/node_modules/*" -not -path "*/.git/*"
+ ```
+
+ Collect: file paths, key terms, naming conventions seen.
+
+ **Stop here if:** 3 or more directly relevant files found with no critical gaps.
+
+ ### Cycle 2 — Exact Source and Tests
+
+ Read the most relevant files from Cycle 1 in full. Then:
+
+ ```bash
+ # Find tests for those files
+ rg "<filename-stem>" --glob "*.test.*" --glob "*.spec.*" -l
+ rg "import.*<module-name>" -l
+
+ # Find call sites
+ rg "<function-name>|<class-name>" --type ts --type js -l
+ ```
+
+ Collect: imports used, function signatures, test patterns, adjacent files referenced.
+
+ **Stop here if:** You can describe the change needed and its blast radius.
+
+ ### Cycle 3 — Docs and Setup
+
+ ```bash
+ # Check project-specific docs
+ ls docs/ README.md AGENTS.md CLAUDE.md .claude/ 2>/dev/null
+
+ # Check config for feature flags, env vars, or schema
+ rg "<keyword>" .env.example *.config.* *.toml *.yaml -l 2>/dev/null
+ ```
+
+ Collect: configuration constraints, environment requirements, anything that would block a change.
+
+ ## Stopping Conditions
+
+ Stop the loop (whichever comes first):
+ - You have 3+ high-relevance files and understand the change scope
+ - Cycle 3 complete
+ - Each new cycle returns only files already seen
+
+ ## Output
+
+ After the loop, report:
+
+ ```
+ Context gathered:
+ <file-path> — <one-line reason for relevance>
+ ...
+
+ Missing context (if any):
+ <what is still unclear and why it matters>
+ ```
+
+ If context is missing, state it explicitly. Do not proceed with guesses when a known gap exists.
+
+ ## Integration with Subagents
+
+ When dispatching a subagent, pass only the gathered file list — not the full conversation context:
+
+ ```
+ Relevant files for this task:
+ src/auth/tokens.ts — contains TokenService used by the bug
+ src/auth/session.ts — session state management
+ src/auth/tokens.test.ts — existing test patterns
+ ```
+
+ ## Constraints
+
+ - Max 3 cycles. Diminishing returns beyond that.
+ - Do not read files speculatively. Read only files flagged as relevant.
+ - Do not inline entire file contents into the subagent prompt; pass paths.
+ - Report gaps rather than silently proceeding with incomplete context.