iterative-retrieval

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

1. After each cycle, the coordinator evaluates the output against the success criteria before accepting it or spawning the next cycle.
2. Objective context forward: each subsequent spawn includes a summary of what was tried and what is still missing — not just a repeat of the original task.
3. Cycle 3 exhausted → escalate: write a summary to .squad/decisions/inbox/, label the issue status:needs-decision, and notify the user.