context-retrieval-loop

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

# 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:

# 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

# 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>