Gap-Driven Iterative Retrieval

These examples and illustrative results are independently authored teaching materials, not measured model results.

Use case

Add rate limiting to API endpoints. The first rate limit search misses implementation, but middleware mentions throttle. The teaching project has middleware/index.ts referencing throttle.ts and router.ts wiring middleware. Inspect these materials before choosing reuse or new code.

Mechanism

Search from the task concept, then record relevance reasons and missing information. Refine with observed terms/references, retrieving implementation, wiring and related tests. Stop when ownership, interface and call path are sufficiently established. Preserve gaps at the agreed budget rather than using file counts or numeric scores as proof of sufficiency.

Bad example

Search rate limit once; zero matches means no limiter, so write another implementation without following the throttle reference.

Good example

Use at most three targeted rounds for this teaching task. Search rate limit and middleware entrypoints, recording implementation/wiring gaps. Follow throttle to throttle.ts, router.ts and relevant tests. Explain the gap each new read resolves. Stop once ownership, call path and integration conditions are known, preferring verified reuse. Report remaining gaps at budget exhaustion instead of inferring absence from the first empty search.

Why the change matters

Observed vocabulary and open questions guide the next query, repairing an initial terminology miss. Explicit gaps also keep expansion purposeful instead of treating every candidate as required context.

Observable expectation

An illustrative ledger finds throttle with implementation missing in round one, reads implementation/router in round two and checks tests if needed in round three. It explains reuse or a still-unverified condition.

Repeated identical queries, stopping at three files regardless of gaps or declaring absence after finding implementation fail.

Limits

Three rounds and filenames are teaching choices, not universal limits. Relevance scores are not calibrated probabilities. Preserve incomplete conclusions and avoid out-of-scope sensitive material when key paths remain unknown.