When things fail

autoducks never fails as a silent red X in the Actions tab. Every run reports on the issue itself — this page is the map from “what you see” to “what to do”.

Reading the status comment

Each agent run posts one bot-owned status comment and edits it in place:

You see	It means	What to do
Agent: running on workflow #id	In progress	Wait — the link opens the live run
✅ Agent: finished working	Success — details and the next step follow	Follow the Next: line
🔁 Agent: not ready — delegated	A Definition-of-Ready guard dispatched a prerequisite agent	Nothing — the pipeline resumes itself
⚠️ Agent: failed	The run failed	Read the failure report posted below it

Reactions on your comment mirror the outcome: 👀 started, 👍 success, 😕 failure.

The failure report

On failure, a categorized report is posted with the diagnosis, a View the run logs link, and the exact retry command:

Category	What happened	Remedy
merge-conflict	The task PR couldn’t merge into the pipeline branch (usually conflicts with work another wave task merged first)	Resolve the conflict on the PR, or /fix on the task — it rebases and retries
no-changes	The agent finished but produced no code changes	Refine the task spec / acceptance criteria, then /fix
scope-missing	The agent didn’t produce its expected output (design or plan file)	Re-run /architect or /engineer
parse	The plan couldn’t be parsed into tasks (a template hint is posted)	Re-run /engineer
max_turns	The agent hit its turn limit — partial work preserved (the report names the branch)	re-run /execute turns=<n> (or /run turns=<n>) — resumes the preserved branch and raises the turn budget; /fix also resumes but at the same budget
infra	Unexpected error (API, git, runtime) before finishing	/fix to retry; check the run logs

Task failures under a feature also post a mirror report on the parent issue — the Maestro pauses that wave until the task is resolved.

For what a re-run of any given stage actually does — and what’s preserved vs. rewritten — see Re-running agents; this page only covers the failure-specific recovery paths below.

Retry correctness, by category

Two commands resume a failed task: re-issuing /execute (on the task or the parent feature, which re-dispatches the Developer once its guards clear) and /fix. They don’t behave identically — the table below is the delta on top of the per-stage re-run table: whether partial work survives, whether a duplicate PR/branch is possible, and whether the wave resumes on its own.

Category	Retry command	Partial work survives?	Duplicate PR/branch?	Wave resumes on its own?
merge-conflict	execute re-run	Yes (untouched)	No — the open PR already claims the task, so re-dispatch is skipped	No — the conflict is never touched; a wave-dispatch summary now lists the task under “Blocked — needs /fix” instead of the ambiguous “Skipped”
merge-conflict	/fix	Yes	No — reuses the open PR (matched by head branch)	Yes, once the retried merge succeeds — the merge event re-triggers the Maestro
no-changes	execute re-run	N/A — nothing was produced to preserve	No — no branch or PR was ever pushed	Yes — retried as a clean run
no-changes	/fix	N/A	No	Yes
max_turns	execute re-run (turns=<n> raises the budget)	Yes — resumes the preserved WIP: branch instead of cutting a new one	No — the same branch is reused, so the eventual PR isn’t a duplicate	Yes, once it completes and its PR merges
max_turns	/fix (same turn budget as the failed run)	Yes — always resumed the preserved branch	No — reuses the open PR if one already exists	Yes
scope-missing / parse	execute re-run	N/A — no branch or PR exists at this stage (Architect/Engineer, not Developer)	No	Yes — delegates back through the Engineer/Architect readiness chain
scope-missing / parse	/fix	Not applicable — /fix resumes a task branch; re-run /architect or /engineer instead	—	—
infra	execute re-run	Depends on when it hit: anything already pushed (even without a WIP: marker, since resumption matches by branch name, not commit message) is picked up by the same branch-resume guard	No	Yes
infra	/fix	Same — resumes whatever was pushed	No	Yes

Caution

Before this table’s max_turns row was true, re-issuing /execute on a task whose only trace was a preserved WIP: branch (no PR yet) silently cut a fresh branch from the base and orphaned the partial work — /fix was the only safe resume path. The Developer now resumes that branch either way, so for a turn-limit cutoff specifically, prefer /execute turns=<n> (or /run turns=<n>) — it resumes the same branch and raises the budget that caused the cutoff. /fix remains a valid resume path too, and still carries the failure context (the last 10 comments) into the retry, but leaves the turn budget unchanged.

Resuming with /fix

/fix

on the task issue. The Fix agent finds the newest existing task branch (including WIP: branches preserved on a max_turns cutoff), reads the failure context from the last 10 comments, and repairs on top of what’s there — reusing the open PR if one exists.

Tip

Comment what went wrong before running /fix — the agent reads recent comments as context. For a max_turns cutoff specifically, /execute turns=<n> (or /run turns=<n>) is usually the better call — same branch-resume behavior, plus the raised turn budget.

Merge conflicts

When auto-merge can’t resolve a task PR, you get a 🔀 report naming the PR and branch. Resolve it like any conflict (rebase or merge the target into the task branch, push), then either merge the PR yourself or run /fix — the next merge into the pipeline branch re-triggers the Maestro automatically.

Questions Mode

If the Engineer finds the design genuinely insufficient, it doesn’t guess — it posts up to 5 blocking questions and stops (the chain stops too). Answer them as comments and re-run /engineer: the revision context carries your answers to the planner.

The pipeline seems stuck

The Maestro advances on PR-merge events. If nothing is moving:

1. Check the issue’s last 🌊/⏳ comment — ⏳ means an earlier wave still has an open task.
2. Check the open task issues for ⚠️ reports (a failed task pauses its wave).
3. Re-issue /execute on the issue — the Maestro recomputes from visible state, and its duplicate-dispatch guards mean this never re-dispatches a task that already has a PR, nor (per the table above) orphans a task’s preserved max_turns work.

Denied runs

If nothing at all happened — no reaction, no status comment — the security gate denied the actor before any feedback. A denial message identifies the actor and command; the security block in autoducks.json controls who may trigger what.