iterative-retrieval

name	iterative-retrieval
description	4-phase retrieval loop — dispatch broad, score relevance 0-1, refine criteria, loop up to N cycles. Use when a subagent or phase needs scoped context from a large source (codebase, catalogue, web).
origin	ECC
tier	global
stage	["seeding","loop"]
status	active

Iterative Retrieval

Borrowed from everything-claude-code. Solves the "context problem" where a naive retrieval dumps too much irrelevant material, wasting tokens and diluting the signal.

When to activate

• Seeding / brainstorm: competitive landscape research across unknown sources
• Seeding / competition: feature pattern surveying
• Loop / building: "find every consumer of X" or "find the existing pattern for Y" in a large codebase
• Loop / analyzing: "find all prior cycles that hit similar root causes"

Four phases

1. Dispatch

Start with a broad query. Collect candidate items without filtering.

2. Evaluate

Score each candidate 0.0–1.0 against the actual need:

• 0.8–1.0 — directly answers the question
• 0.5–0.7 — related pattern, adapt with care
• 0.2–0.4 — tangential, keep only if top N are thin
• 0.0–0.2 — irrelevant, discard

3. Refine

If the top scores are < 0.6, the query was off. Update criteria based on what the scored items revealed. Re-dispatch with narrower terms.

4. Loop

Max 3 refinement cycles. If still no 0.6+ match after 3 cycles, escalate ("no match found, suggest relaxing scope or asking human").

Output shape

{
  "query_initial": "...",
  "cycles": [
    { "query": "...", "candidates_scored": [...], "top_score": 0.85 }
  ],
  "selected": [
    { "source": "path/or/url", "score": 0.9, "why": "..." }
  ],
  "escalated": false
}

Config

{ "max_cycles": 3, "min_acceptable_score": 0.6, "top_n": 5 }

Anti-patterns

• Don't skip the Evaluate phase. Unscored retrieval is grep.
• Don't loop past max_cycles. Escalate instead.
• Don't keep items scoring below 0.4 unless you have less than top_n above.