v1.0.0 to v1.0.0

---

name: "iterative-retrieval"

description: "Progressive context refinement for subagents and tool-using LLMs. Use when a parent agent must delegate research, code reading, or document Q&A to a subagent with a tight context budget. Replaces one-shot context dumps with a query -> retrieve -> filter -> requery loop that returns only the evidence the parent needs."

metadata:

version: "1.0.0"

created: "2026-05-17"

updated: "2026-05-30"

compatibility:

frameworks: ["agentx", "copilot", "claude-code"]

---

# Iterative Retrieval for Subagents

> **Purpose**: Keep subagent context budgets small while still answering the parent agent's real question.

> **Scope**: Subagent delegation, RAG-style scoped reads, multi-pass code search, evidence extraction.

---

## When to Use This Skill

- Parent agent needs a subagent to read large files, long docs, or many search hits and return a short answer.

- The naive approach ("here is the whole repo, summarize") will blow the subagent context.

- The question is open enough that one search query will miss relevant evidence.

- Answer must cite specific files, lines, or sections, not just produce a paraphrase.

## When NOT to Use

- Single-file edits where you can read the file directly.

- Questions answerable from titles or filenames alone.

- Tasks where the parent agent already has the relevant content in context.

## The Anti-Pattern (One-Shot Context Dump)

```

Parent: "Read these 40 files and tell me where auth is handled."

-> subagent loads 40 files

-> hits context limit at file 17

-> hallucinates the rest, or returns truncated nonsense

```

This fails because:

- Subagent burns budget on irrelevant files before reaching the answer.

- No evidence trail; parent cannot verify the claim.

- Re-running with a refined query wastes the same budget again.

## The Iterative Retrieval Pattern

Five phases, executed by the subagent under a strict turn budget (typically 5-8 turns).

### Phase 1: Scope

The subagent restates the parent's question in its own words and lists what it does NOT need to know.

```

Question: "Where is authentication handled?"

In scope: middleware, login endpoints, token validation, session lifecycle.

Out of scope: UI login forms, password reset email templates, OAuth provider config.

Budget: 6 turns, 30 KB of file reads.

```

### Phase 2: Broad Probe

Run one cheap, high-recall search to map the territory. Read filenames and one-line previews only.

```

Text search (regex): "authenticate|authorize|login|session|token"

File-name search (glob): "**/auth/**", "**/*auth*.ts"

```

Return: a ranked list of candidate files with one-line evidence each. Do NOT read full files yet.

### Phase 3: Filter

Discard candidates that are clearly out of scope (tests, mocks, vendor code, docs) unless the parent asked for them. Keep the top 3-5 candidates.

### Phase 4: Targeted Read

Read only the surviving candidates, and only the specific ranges that matched. Use line-ranged reads, not whole-file reads.

```

read_file path=src/auth/session.ts lines=40-120

read_file path=src/middleware/authGuard.ts lines=1-60

```

### Phase 5: Synthesize and Cite

Return a short answer with one citation per claim. Citation = file path + line range. No paraphrasing without a citation.

```

Authentication is handled in two layers:

- Session creation: src/auth/session.ts:55-82 (issues JWT, sets cookie)

- Request gating: src/middleware/authGuard.ts:18-44 (verifies token on every request)

Open questions: refresh-token rotation lives in src/auth/refresh.ts but I did not read it; flag if relevant.

```

The "open questions" line is mandatory. It tells the parent what the subagent did not look at.

## Requery Loop

If the parent rejects the answer or asks a follow-up, the subagent does NOT re-read the same files. It runs Phase 2 again with a refined query, reusing the surviving candidates from the previous pass as priors.

| Trigger | Action |

|---------|--------|

| Parent says "you missed X" | Add X to the probe terms, rerun Phase 2 with the previous candidates as the negative set. |

| Parent says "go deeper on file Y" | Skip Phase 2; read Y with a wider line range. |

| Parent says "is there anything else?" | Rerun Phase 2 with synonyms and adjacent terms; explicitly mark `coverage: partial` if budget runs out. |

## Budget Rules

- **Turn budget**: parent SHOULD set a max turn count when delegating. Default 6.

- **Read budget**: subagent MUST stop reading and synthesize when it has used 70% of its read budget. The last 30% is reserved for one requery if needed. This reserve applies to read size (bytes/KB), not to the turn count.

- **Citation budget**: target 1 citation per significant claim. If a claim has no citation, drop the claim or mark it `unverified`.

## Parent Agent Contract

When the parent delegates, it MUST provide:

1. The specific question (not "look at auth", but "where is the JWT secret loaded?")

2. The scope (in / out)

3. The budget (turns, read size)

4. The expected output shape (short answer + citations + open questions)

When the parent receives the answer, it MUST:

1. Treat unverified claims as unverified -- do not promote them in its own output.

2. Use the open-questions list to decide whether to requery.

3. Never silently expand the scope beyond what was delegated.

## Anti-Patterns to Reject

| Anti-pattern | Why it breaks |

|--------------|---------------|

| Subagent reads every file it finds in Phase 2 | Burns budget before filtering, hits context limit. |

| Parent asks "summarize the codebase" | No scope, no measurable answer; loop cannot terminate. |

| Subagent returns a paraphrase without citations | Parent cannot distinguish recall from hallucination. |

| Subagent omits the open-questions list | Parent assumes coverage was complete, misses gaps. |

| Parent re-delegates the same question without refining | Same budget, same blind spots, same failure. |

- Pair with the `context-management` skill for token-budget hygiene at the parent level.

- Pair with the `cognitive-architecture` skill when the retrieval is over a vector store rather than the filesystem.

- The Reviewer agent SHOULD use this pattern when reading long PRs; do not load the whole diff if a scoped read answers the review question.

- The Architect agent SHOULD use this pattern when reading existing specs to extract decisions; do not load every ADR.

## Self-Check Before Returning

- [ ] Every non-trivial claim has a citation

- [ ] Open-questions list exists and is honest

- [ ] Read budget was respected (did not exceed declared cap)

- [ ] Out-of-scope material was not pulled in opportunistically

- [ ] If coverage is partial, that fact is stated, not hidden

---

**See Also**: [context-management](../context-management/SKILL.md) | [rag-pipelines](../rag-pipelines/SKILL.md) | [agent-memory-systems](../agent-memory-systems/SKILL.md)