| name | executing-tickets-with-subagents |
| description | Use when a GitHub ticket/issue bundles multiple sub-tasks or fixes that will take hours, span context compactions, and ship as one reviewed PR — or when the user asks for subagent-driven execution, "the 4875 workflow", or proper progress tracking in the ticket. |
Executing Tickets with Subagents
Overview
The main conversation is an orchestrator only: it holds decisions, dispatches subagents, triages their reports, and maintains durable state in files. It never implements, reviews, or QAs inline. Durable state lives on disk and GitHub — never in conversation memory, which compaction can erase at any moment.
When to Use
- Ticket with 3+ sub-issues, a rolling PR, hours of work, human + bot review
- User asks to "work through these one by one and keep status updated"
NOT for single small fixes — the tracking overhead outweighs the work.
Phase 0 — Intake
Before brainstorming, grilling, or asking the user anything:
- Fetch the full issue thread — every comment and every attached image (
gh issue view <n> --comments; download images and actually read them). Comments routinely override or extend the original body; an unread comment is a spec you don't have.
- Do your own codebase research first — verify claims against the code before bringing questions to the user. Questions earn their place only after the thread and the code have both been read.
Phase 1 — Lock, plan, instrument
- Explore the code with parallel read-only agents; verify each sub-issue's claimed state in code first.
- Grill the user (AskUserQuestion, concrete options, recommended-first): task order, PR strategy, done-bar per task, tracking method, anything user-owned (migrations, commit policy). Locked answers are law for every later dispatch.
- Spec then plan (see superpowers:writing-plans): per-task briefs with exact code, locatable by symbol/content — line numbers rot.
- Instrument tracking before task 1:
- Ledger (e.g.
.superpowers/sdd/progress.md) — THE recovery map, see contract below
tasks/todo.md checklist- One editable GitHub checklist comment on the issue (status + root cause per item; save its comment id in the ledger; update via
gh api ... -X PATCH -F body=@file, verify by read-back)
- Harness tasks (TaskCreate/TaskUpdate)
Ledger contract
Written for a reader with zero context — assume the next writer remembers nothing. Update after EVERY wave, not at milestones. Must contain: per-task status with commit SHAs; the current NEXT ACTION stated imperatively; accumulated minor findings awaiting triage; standing process rules (permissions granted, environment quirks + fallbacks, QA credentials/data notes); locations of briefs/artifacts.
Phase 2 — Per-task loop
- Brief to scratchpad; if HEAD moved since planning, run an Explore drift-check and write an addendum (addendum wins; locate by symbol).
- Fresh implementer agent — never implement in main context. Bug fixes are TDD (failing test first, watch it fail). Formatter before commit; type-check loop until clean; single conventional commit; push.
- Two-stage review, separate subagents — one combined reviewer anchors on whichever lens it starts with; two fresh ones don't. Both verdicts are required; a report missing either is not a review:
- Stage 1 — spec compliance: reviewer gets the task brief + diff — never the implementer's summary; agent reports are unverified claims — and verdicts against the ticket requirements: Missing / Extra / Misunderstood, with file:line evidence. Give it the named risks to verify.
- Stage 2 — code quality: independent reviewer for correctness, error handling, tests that assert real behavior, and structure; findings ranked Critical / Important / Minor. AI-bot CLI review runs alongside.
- Triage every finding: FIX-NOW (fix agent, then re-review both stages until spec passes and quality approves — a task with open Critical/Important findings is not complete) / DISMISS only with a verified rationale (check the locked design/brief first — reviewers re-litigate settled decisions) / DEFER (log in ledger minors).
- Browser QA agent for UI tasks: records original data, restores it, proves restoration; artifacts to scratchpad only.
- Bookkeeping: tick todo, PATCH checklist comment, TaskUpdate, ledger — then next task.
Phase 3 — Endgame
- Final whole-branch review from the recomputed merge-base (it moves; exclude generated files), hunting cross-task interactions no per-task reviewer could see, and triaging all ledger minors FIX-NOW / FOLLOW-UP / DROP.
- Fix wave → reply-and-resolve every external review thread citing commit SHAs or rationale.
- Update PR body to final state. Mark ready only with user approval; watch CI on the final head — drafts and merge conflicts silently skip
pull_request workflows, so "no failures" may mean "never ran".
- Manual-QA handoff doc — standard closing artifact for bundled bug-fix tickets. Per fixed item: link to the originating issue comment, what was wrong before vs what changed (plain language), and step-by-step testing instructions so the user can validate each fix.
- File follow-ups, never bundle them silently into the current PR: small stray findings → ONE consolidated follow-up ticket; major findings → a dedicated issue each. Assign all of them to the user.
Hard rules
| Rule | Why |
|---|
| Orchestrator never implements/reviews/QAs inline | Main context stays small; compaction loses less; fresh eyes per task |
| Ledger update after every wave | Compaction strikes without warning; the ledger is the only reliable resume point |
| Never run browser QA while an implementer edits the same app | Hot reload contaminates the session mid-test |
| Never blind-retry a mutating command (gh/API/git push) | Empty stdout ≠ failure; verify by read-back first or you double-post |
| Wedged agent → dispatch a fresh one | Re-nudging a stuck agent wastes more than restarting |
| Dispatch prompts are self-contained | Paths, env, locked decisions, verification commands, commit format, report format, environment-quirk fallbacks — the agent has no other context |
| Agent reports are raw data | SHAs, counts, file:lines, ran-vs-inspected; "should work" is not a report |
| User-owned territory (migrations, merges, un-drafting) → ask | One approval does not extend to the next category |
Common mistakes
- Subagents only for search, edits done inline — the biggest regression; the loop's value is fresh implementer + independent reviewers per task.
- Treating todo.md as the recovery map — working notes are not a zero-context ledger with NEXT ACTION.
- Skipping the review wave because CI + review bot run on push — bots miss spec violations; give reviewers named risks.
- Merging spec + quality into one reviewer, or accepting a report with only one verdict — spec compliance and code quality are separate passes by separate subagents, and both must pass before the task closes.
- Trusting plan line numbers after other tasks land — drift-check, locate by content.
- Reporting "done" from type-check alone — the done-bar locked in Phase 1 decides (tests, browser QA, evidence).
