iterative-retrieval
/iterative-retrieval
Narzuca protokół maksymalnie trzech cykli dla zadań subagentów z kontekstem celu i walidacją przez koordynatora przy zlecaniu ograniczonej pracy.
- Autor
- azure-samples ↗
- Repozytorium
- eshoplite ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 27.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Narzuca protokół maksymalnie trzech cykli dla zadań subagentów z kontekstem celu i walidacją przez koordynatora przy zlecaniu ograniczonej pracy.
Oryginalny opis (EN)
Max-3-cycle protocol for agent sub-tasks with WHY context and coordinator validation. Use when spawning sub-agents to complete scoped work.
Jak działa
- Spawn Prompt Template
- 3-Cycle Protocol
- Coordinator Validation Checklist
- When to Escalate vs Retry
- Issue Dedup Check (Mandatory)
- Mandatory Output Requirement (Research-Then-Execute)
- Anti-Patterns
- Examples
Podgląd SKILL.md
---
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.
```
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · azure-samples/eshoplite | 100 | MIT |
| aAAaqwq/AGI-Super-Team | 100 | MIT |
| affaan-m/ECC | 100 | MIT |
| SHRIJANAGAIN/Nemo-Cli | 100 | Apache-2.0 |
| nasac0x/code-orchestrator | 100 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki aefa65a9c065 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100coordinator-dispatching-work
Wprowadza dyscyplinę koordynatora przy rozpoczynaniu epiku, zlecaniu pracy implementatorowi, tworzeniu worktree dla agenta i uruchamianiu subagentów. - 100coordinator-dispatching-work
Wprowadza dyscyplinę koordynatora przy rozpoczynaniu epiku, zlecaniu pracy implementatorowi, tworzeniu worktree dla agenta i uruchamianiu subagentów. - 95skill-iterative-loop
Uruchamia zadania w pętli aż do osiągnięcia celu, przy iteracyjnym dopracowywaniu, odpytywaniu i zbieżności wyników. - 100coordinator-helper
Zarządza zadaniami demona koordynatora, zatwierdza lub odrzuca pracę i monitoruje autonomicznych agentów, w tym przez przepływ zatwierdzania oparty na GitHubie. - 100coordinator-helper
Zarządza zadaniami demona koordynatora, zatwierdza lub odrzuca pracę i monitoruje autonomicznych agentów, w tym przez przepływ zatwierdzania oparty na GitHubie. - 98agentic-rag
Buduje systemy agentowego RAG z planowaniem zapytań, refleksją i iteracyjnym wyszukiwaniem w wielu źródłach.