iterative-retrieval_skill

Overview

This skill implements an iterative retrieval pattern for progressively refining the context supplied to subagents. It prevents sending too much or too little code by looping through dispatch, evaluation, refine, and loop phases. The approach targets multi-agent workflows where the right context isn’t known upfront and optimizes token use and relevance.

How this skill works

Start with a broad file-and-keyword query to gather candidate files (DISPATCH). Score and explain each candidate for relevance and identify missing gaps (EVALUATE). Use those signals to expand patterns and keywords, exclude irrelevant paths, and focus on specific gaps (REFINE). Repeat up to three cycles, returning high-relevance files and the minimal context needed for the subagent.

When to use it

• Spawning subagents that need unpredictable codebase context
• Designing multi-agent workflows where context is refined iteratively
• Resolving "context too large" or "missing context" failures
• Building RAG-style retrieval pipelines for code exploration
• Optimizing token usage in agent orchestration

Best practices

• Start with broad queries; avoid over-specifying upfront
• Score files on a 0–1 relevance scale and record reasons for each score
• Explicitly identify missing context to drive refinements
• Limit cycles (recommend max 3) and stop when good-enough context is found
• Exclude low-relevance paths confidently to reduce noise

Example use cases

• Bug fix: iterate on keywords like "token", "refresh", "jwt" to gather auth-related files
• Feature addition: discover project terminology (e.g., "throttle" vs "rate") and refine searches to find middleware and routers
• Code review assistant: progressively collect the most relevant modules for a focused review
• Onboarding agent: surface representative files and naming conventions for new contributors
• Efficiency tuning: reduce token load by returning a few high-relevance files instead of many marginal ones