iterative-retrieval

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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.

---

## Coordinator Validation Checklist

Before accepting agent output and closing an issue, the coordinator must check:

- [ ] All success criteria from the spawn prompt are met
- [ ] PR exists and description matches the issue (if code work)
- [ ] No obvious regressions (grep for TODO/FIXME introduced, build passes)
- [ ] Agent did not silently skip parts of the task
- [ ] If the agent reported uncertainty — was it resolved or escalated?

If any item fails → do **not** accept. Spawn cycle N+1 (up to cycle 3) with specific deltas.

---

## When to Escalate vs Retry

**Retry (cycle N+1)** when:
- Output is structurally correct but missing specific items
- Agent misunderstood scope (provide more context and re-run)
- Partial success — clearly identified remaining delta

**Escalate** when:
- Requirements are fundamentally unclear (decision needed)
- 3 cycles complete without convergence
- Agent returned conflicting results across cycles
- Task requires elevated permissions or external action
- The work depends on another issue that isn't done yet

---

## Issue Dedup Check (Mandatory)

Before any agent creates a GitHub issue, it **must** search for existing open issues to avoid
duplicates.

```bash
# Check for existing open issues before creating a new one
gh issue list --search "<keywords from your issue title>" --state open
```

- If an open issue already covers the same problem → **comment on it** instead of creating a new one.
- If no duplicate → proceed to create the issue.
- Use 2–3 representative keywords from the planned issue title as the search query.

---

## Mandatory Output Requirement (Research-Then-Execute)

Every research or analysis task completed under this protocol **MUST** end with at least one
concrete action before the cycle is closed. Acceptable follow-up actions:

- GitHub issue created documenting the findings and next steps
- PR opened implementing a recommendation
- Decision recorded in `.squad/decisions/inbox/`
- Documented recommendation with a named assignee and due date

**Pure analysis reports without actionable follow-up will be rejected during triage.**
If no action is warranted, the agent must explicitly state why and get coordinator sign-off.

---

## Anti-Patterns

From jb-apei/squad-skills, MIT.

More from jb-apei/squad-skills