feat(skills): add iterative-retrieval skill -- max-3-cycle agent spawn protocol

.changeset/iterative-retrieval-skill.md

@@ -0,0 +1,5 @@
+---
+"@bradygaster/squad-cli": minor
+"@bradygaster/squad-sdk": minor
+---
+feat: add iterative-retrieval skill for structured max-3-cycle agent spawning

docs/proposals/iterative-retrieval.md

@@ -0,0 +1,69 @@
+# Proposal: Iterative Retrieval Skill
+
+**Issue:** bradygaster/squad#622
+**Author:** tamirdresher
+**Date:** 2026-03-26
+**Status:** Proposal
+
+---
+
+## Problem Statement
+
+Agents that spawn sub-agents or issue retrieval operations have no standardized protocol for
+how many cycles are acceptable before escalating. This leads to:
+- Unbounded loops when agents keep spawning without convergence
+- Missed escalations when 1 cycle is insufficient but the agent gives up
+- Inconsistent behavior across coordinators
+
+---
+
+## Proposed Approach
+
+A structured 3-cycle protocol for iterative information retrieval with mandatory checkpoints:
+
+**Cycle 1:** Broad scan — identify the domain, key files, and initial findings
+**Cycle 2:** Targeted retrieval — follow up on specific gaps identified in Cycle 1
+**Cycle 3 (max):** Final fill — address remaining gaps only. If still incomplete, escalate
+
+The skill provides:
+- Spawn prompt templates for each cycle (what to include, what to stop)
+- A coordinator validation checklist (did previous cycle produce actionable output?)
+- Issue deduplication logic (don't spawn for issues already in progress)
+- Good/bad example spawn prompts to calibrate agent behavior
+
+---
+
+## Fit with Existing Architecture
+
+- **Complements** error-recovery skill (escalate pattern is the fallback at cycle 3)
+- **No code changes** — template-only skill
+- **Coordinator-agnostic** — works with any existing Ralph or custom coordinator
+- **Consistent with** the 3-round Ralph pattern already used in production
+
+---
+
+## What Changes
+
+- New skill: packages/squad-cli/templates/skills/iterative-retrieval/SKILL.md
+- New skill: packages/squad-sdk/templates/skills/iterative-retrieval/SKILL.md
+- New changeset: .changeset/iterative-retrieval-skill.md
+
+## What Stays the Same
+
+- No existing skills modified
+- No CLI or SDK runtime code changed
+
+---
+
+## Risks and Mitigations
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| 3-cycle limit is too restrictive for complex tasks | Low | Medium | Skill explicitly allows coordinator to extend with justification |
+| Conflicts with future built-in spawn limiting | Low | Low | Template-only — naturally superseded |
+
+---
+
+## References
+
+- Issue: bradygaster/squad#622

packages/squad-cli/templates/skills/iterative-retrieval/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: "iterative-retrieval"
+description: "Max-3-cycle protocol for agent sub-tasks with WHY context and coordinator validation. Use when spawning sub-agents to complete scoped work."
+domain: "agent-coordination"
+confidence: "high"
+license: MIT
+---
+
+# 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
+
+- **Spawning without WHY** — agents can't prioritise trade-offs without motivation context.
+- **Accepting output without validating** — one failed check avoids merging broken work.
+- **Cycle 4+** — if 3 cycles haven't converged, the problem is in the requirements, not the agent.
+- **Vague success criteria** — "looks good" is not a criterion. Use checkboxes.
+- **Forwarding WHAT without delta** — cycle 2+ prompts must include what cycle 1 got wrong.
+- **Creating issues without dedup check** — always search before creating.
+- **Research without action** — delivering analysis with no issue, PR, decision, or assignee is incomplete work.
+
+---
+
+## Examples
+
+### Good spawn prompt
+```
+## Task
+Add an "Iterative Retrieval Protocol" section to `.squad/agents/coordinator/charter.md` explaining
+the 3-cycle rule, WHY format, and validation checklist.
+
+## WHY this matters
+The coordinator spawns sub-agents on every round. Without a documented protocol, agents run unbounded
+cycles and outputs go unvalidated — leading to stale issues and silent failures.
+
+## Success criteria
+- [ ] Section "Iterative Retrieval Protocol" exists in charter.md
+- [ ] Section documents max-3-cycles rule
+- [ ] Section documents WHY format requirement
+- [ ] Section contains validation checklist (at least 4 items)
+- [ ] No other sections of charter.md are modified
+
+## Escalation path
+If the charter.md format is unclear, check another agent charter as a reference.
+If uncertain about content, stop and surface to coordinator.
+```
+
+### Bad spawn prompt (don't do this)
+```
+Update the coordinator charter with the iterative retrieval stuff.
+```