@cryptotaxi247 / SquadScope-1
Code Commits Issues Pulls Sessions CI/CD
main
main
md 165 lines 6.19 KB
Rendered Raw
1 ---
2 name: "iterative-retrieval"
3 description: "Max-3-cycle protocol for agent sub-tasks with WHY context and coordinator validation. Use when spawning sub-agents to complete scoped work."
4 domain: "agent-coordination"
5 confidence: "high"
6 license: MIT
7 ---
8
9 # Iterative Retrieval Skill
10
11 Squad agents frequently spawn sub-agents to complete scoped work. Without structure, these
12 handoffs become vague, cycles multiply, and outputs land without being checked. The
13 **Iterative Retrieval Pattern** caps cycles at 3, mandates WHY context in every spawn, and
14 requires the coordinator to validate agent output before closing an issue.
15
16 ---
17
18 ## Spawn Prompt Template
19
20 Every agent spawn must include the following four sections. Copy and fill in the template:
21
22 ```
23 ## Task
24 {What you need done — concrete and bounded}
25
26 ## WHY this matters
27 {The motivation and context. What system or user goal does this serve? What breaks if skipped?}
28
29 ## Success criteria
30 {How you will know the output is correct. Be explicit — list acceptance criteria, not vibes.}
31 Example:
32 - [ ] File X exists and contains Y
33 - [ ] No regressions in existing tests
34 - [ ] PR is open targeting main with description matching the issue
35
36 ## Escalation path
37 {What the agent should do if uncertain or stuck. "Stop and ask me" is valid.}
38 Example:
39 - If requirements are ambiguous → stop, comment on the issue, set label status:needs-decision
40 - If blocked by a dependency → label status:blocked, explain in a comment
41 - If 3 cycles exhausted without resolution → write a summary to inbox and surface to coordinator
42 ```
43
44 ---
45
46 ## 3-Cycle Protocol
47
48 | Cycle | Description | Exit condition |
49 |-------|-------------|----------------|
50 | **1** | Initial attempt | Done → coordinator validates. Incomplete → surface delta. |
51 | **2** | Targeted retry with specific corrections | Done → coordinator validates. Incomplete → one more. |
52 | **3** | Final attempt with all context from cycles 1–2 | Done or escalate — no cycle 4. |
53
54 ### Rules
55
56 1. **After each cycle**, the coordinator evaluates the output against the success criteria
57 before accepting it or spawning the next cycle.
58 2. **Objective context forward**: each subsequent spawn includes a summary of what was tried
59 and what is still missing — not just a repeat of the original task.
60 3. **Cycle 3 exhausted** → escalate: write a summary to `.squad/decisions/inbox/`, label the
61 issue `status:needs-decision`, and notify the user.
62
63 ---
64
65 ## Coordinator Validation Checklist
66
67 Before accepting agent output and closing an issue, the coordinator must check:
68
69 - [ ] All success criteria from the spawn prompt are met
70 - [ ] PR exists and description matches the issue (if code work)
71 - [ ] No obvious regressions (grep for TODO/FIXME introduced, build passes)
72 - [ ] Agent did not silently skip parts of the task
73 - [ ] If the agent reported uncertainty — was it resolved or escalated?
74
75 If any item fails → do **not** accept. Spawn cycle N+1 (up to cycle 3) with specific deltas.
76
77 ---
78
79 ## When to Escalate vs Retry
80
81 **Retry (cycle N+1)** when:
82 - Output is structurally correct but missing specific items
83 - Agent misunderstood scope (provide more context and re-run)
84 - Partial success — clearly identified remaining delta
85
86 **Escalate** when:
87 - Requirements are fundamentally unclear (decision needed)
88 - 3 cycles complete without convergence
89 - Agent returned conflicting results across cycles
90 - Task requires elevated permissions or external action
91 - The work depends on another issue that isn't done yet
92
93 ---
94
95 ## Issue Dedup Check (Mandatory)
96
97 Before any agent creates a GitHub issue, it **must** search for existing open issues to avoid
98 duplicates.
99
100 ```bash
101 # Check for existing open issues before creating a new one
102 gh issue list --search "<keywords from your issue title>" --state open
103 ```
104
105 - If an open issue already covers the same problem → **comment on it** instead of creating a new one.
106 - If no duplicate → proceed to create the issue.
107 - Use 2–3 representative keywords from the planned issue title as the search query.
108
109 ---
110
111 ## Mandatory Output Requirement (Research-Then-Execute)
112
113 Every research or analysis task completed under this protocol **MUST** end with at least one
114 concrete action before the cycle is closed. Acceptable follow-up actions:
115
116 - GitHub issue created documenting the findings and next steps
117 - PR opened implementing a recommendation
118 - Decision recorded in `.squad/decisions/inbox/`
119 - Documented recommendation with a named assignee and due date
120
121 **Pure analysis reports without actionable follow-up will be rejected during triage.**
122 If no action is warranted, the agent must explicitly state why and get coordinator sign-off.
123
124 ---
125
126 ## Anti-Patterns
127
128 - **Spawning without WHY** — agents can't prioritise trade-offs without motivation context.
129 - **Accepting output without validating** — one failed check avoids merging broken work.
130 - **Cycle 4+** — if 3 cycles haven't converged, the problem is in the requirements, not the agent.
131 - **Vague success criteria** — "looks good" is not a criterion. Use checkboxes.
132 - **Forwarding WHAT without delta** — cycle 2+ prompts must include what cycle 1 got wrong.
133 - **Creating issues without dedup check** — always search before creating.
134 - **Research without action** — delivering analysis with no issue, PR, decision, or assignee is incomplete work.
135
136 ---
137
138 ## Examples
139
140 ### Good spawn prompt
141 ```
142 ## Task
143 Add an "Iterative Retrieval Protocol" section to `.squad/agents/coordinator/charter.md` explaining
144 the 3-cycle rule, WHY format, and validation checklist.
145
146 ## WHY this matters
147 The coordinator spawns sub-agents on every round. Without a documented protocol, agents run unbounded
148 cycles and outputs go unvalidated — leading to stale issues and silent failures.
149
150 ## Success criteria
151 - [ ] Section "Iterative Retrieval Protocol" exists in charter.md
152 - [ ] Section documents max-3-cycles rule
153 - [ ] Section documents WHY format requirement
154 - [ ] Section contains validation checklist (at least 4 items)
155 - [ ] No other sections of charter.md are modified
156
157 ## Escalation path
158 If the charter.md format is unclear, check another agent charter as a reference.
159 If uncertain about content, stop and surface to coordinator.
160 ```
161
162 ### Bad spawn prompt (don't do this)
163 ```
164 Update the coordinator charter with the iterative retrieval stuff.
165 ```