context-retrieval-loop

What it does and when to use it

Use when starting work in an unfamiliar area of a codebase, spawning a subagent that needs targeted file context, a first search pass missed the relevant file, or the file scope of a task is unclear.

How it works

1. When to Use
2. The 3-Cycle Loop
3. Stopping Conditions
4. Output
5. Integration with Subagents
6. Verification

---
name: context-retrieval-loop
description: Use when starting work in an unfamiliar area of a codebase, spawning a subagent that needs targeted file context, a first search pass missed the relevant file, or the file scope of a task is unclear.
---

# Context Retrieval Loop

Gather the right codebase context before making changes or spawning subagents.

## When to Use

- Starting work in an unfamiliar area
- Spawning a subagent that needs targeted file context
- First search pass returned nothing useful

## The 3-Cycle Loop

### Cycle 1 — Broad Search

```bash
rg "<primary-keyword>" --type ts --type js -l
find . -name "*<keyword>*" -not -path "*/node_modules/*"
```

Stop here if 3+ directly relevant files found.

### Cycle 2 — Exact Source and Tests

Read the most relevant files from Cycle 1. Then find:
```bash
rg "<filename-stem>" --glob "*.test.*" --glob "*.spec.*" -l
rg "import.*<module-name>" -l
```

Stop here if you can describe the change and its blast radius.

### Cycle 3 — Docs and Setup

```bash
ls docs/ README.md AGENTS.md CLAUDE.md .claude/ 2>/dev/null
rg "<keyword>" .env.example *.config.* 2>/dev/null
```

## Stopping Conditions

Stop when: 3+ high-relevance files understood, OR Cycle 3 complete, OR new cycles return only files already seen.

## Output

```
Context gathered:
  <file-path> — <one-line reason>

Missing context (if any):
  <what is still unclear>
```

State gaps explicitly. Do not proceed with guesses when a known gap exists.

## Integration with Subagents

Pass file paths to subagents, not file contents:
```
Relevant files: src/auth/tokens.ts, src/auth/session.ts, src/auth/tokens.test.ts
```

## Verification

- [ ] The loop stopped at a stopping condition — never past 3 cycles
- [ ] Every gathered file is listed with a one-line relevance reason
- [ ] Missing context is stated explicitly — no proceeding on guesses when a gap is known
- [ ] Subagents received file paths, not inlined file contents

Versions

Database snapshot: 13.11.2026 · package version c5f32a2ace17 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

• 100explore-area
  Orient on a new codebase area using get_context for token-budgeted exploration. Use when the user asks "what does this module do", "explain this part", or wants to understand an unfamiliar area before making changes.
• 100iterative-retrieval
  Pattern for progressively refining context retrieval to solve the subagent context problem. Use when spawning subagents that need codebase context they cannot predict upfront, or when building multi-agent workflows where context is progressively refined.
• 100map
  Generate semantic codebase symbol map. Use when navigating unfamiliar code or before refactoring.
• 100focus
  Use to narrow attention to a feature/file set/area for the current session. Different from /scope (which enforces via hook) — focus is advisory + helps memory + retrieval prioritise the area.
• 100research-first
  Researches existing code, docs, and prior art before proposing designs or writing code. Use this skill when entering an unfamiliar area, choosing a library, or before design-exploration when facts are missing. Do not use when/for executing an already-researched implementation…
• 100ds-plan-loop
  Write a numbered plan with an acceptance check for each step, critique it once in a fresh pass, revise it, then execute one step at a time. Use when a task touches more than one file, has unclear scope, or failed before because steps were missed. Invoke as /ds-plan-loop.