# Iterative Retrieval

Max-3-cycle protocol for agent sub-tasks with WHY context and coordinator validation.

- Repository: https://github.com/microsoft/waza (1496 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add microsoft/waza --skill iterative-retrieval -g -a claude-code -y`
Codex: `npx skills add microsoft/waza --skill iterative-retrieval -g -a codex -y`
Cursor: `npx skills add microsoft/waza --skill iterative-retrieval -g -a cursor -y`
Gemini CLI: `npx skills add microsoft/waza --skill iterative-retrieval -g -a gemini-cli -y`

## Description

Max-3-cycle protocol for agent sub-tasks with WHY context and coordinator validation. Use when spawning sub-agents to complete scoped work.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Iterative Retrieval Skill

Squad agents frequently spawn sub-agents to complete scoped work. Without structure, these
handoffs become vague, cycles multiply, and outputs land without being checked. The
**Iterative Retrieval Pattern** caps cycles at 3, mandates WHY context in every spawn, and
requires the coordinator to validate agent output before closing an issue.

---

## Spawn Prompt Template

Every agent spawn must include the following four sections. Copy and fill in the template:

```
## Task
{What you need done, concrete and bounded}

## WHY this matters
{The motivation and context. What system or user goal does this serve? What breaks if skipped?}

## Success criteria
{How you will know the output is correct. Be explicit, list acceptance criteria, not vibes.}
Example:
- [ ] File X exists and contains Y
- [ ] No regressions in existing tests
- [ ] PR is open targeting main with description matching the issue

## Escalation path
{What the agent should do if uncertain or stuck. "Stop and ask me" is valid.}
Example:
- If requirements are ambiguous → stop, comment on the issue, set label status:needs-decision
- If blocked by a dependency → label status:blocked, explain in a comment
- If 3 cycles exhausted without resolution → write a summary to inbox and surface to coordinator
```

---

## 3-Cycle Protocol

| Cycle | Description | Exit condition |
|-------|-------------|----------------|
| **1** | Initial attempt | Done → coordinator validates. Incomplete → surface delta. |
| **2** | Targeted retry with specific corrections | Done → coordinator validates. Incomplete → one more. |
| **3** | Final attempt with all context from cycles 1, 2 | Done or escalate, no cycle 4. |

### Rules

The rest: https://github.com/microsoft/waza/blob/HEAD/.github/skills/iterative-retrieval/SKILL.md