Tasks fail. Most failures are configuration or specification problems rather than anything mysterious, and they fall into a small number of shapes.
First, read where it stopped
The run shows which stage failed. That single fact narrows the cause more than anything else:
| Failed at | Almost always means |
|---|---|
| Before any code was written | Build or install command wrong for a clean workspace |
| While making the change | Genuinely hard work, or a missing dependency |
| Running tests | Test command wrong, or the suite needs a service |
| Verification | A blocking gate; check the findings |
| Review | Findings that could not be auto-fixed |
Failures before the change is written are configuration. See Build and test configuration.
It is not stuck, it is queued
A task in PENDING is not stuck. It is waiting for a free agent slot. Check
capacity before anything else — this is the
most common false alarm.
It is asking you something
NEEDS_HUMAN_REVIEW means the task hit a decision only you can make. It is not a
failure. Answer the question and it continues from where it paused.
Answer precisely. A vague answer produces another guess and another pause.
Running much longer than expected
Two usual causes:
A slow or hanging test suite. Coroid runs your suite; if it hangs in a clean workspace, the task waits. Reproduce by running the suite against a fresh clone.
A specification broad enough that the agent keeps finding more to do. The tell is a growing file list. Cancel, tighten the scope with an explicit out-of-scope line, and re-run. See Specifications.
Choosing what to do
In increasing cost:
- Answer — for
NEEDS_HUMAN_REVIEW. Cheapest, keeps all context. - Rework — the work is right but incomplete. Goes back to the developer agent with your findings and its context intact.
- Pause — you need to check something first. Frees the slot; resumable.
- Retry — for genuinely transient failures only. Retrying a configuration problem just reproduces it.
- Cancel and re-specify — the approach or the scope was wrong. Most expensive, and often the right call.
Failures that repeat across tasks
The same failure at the same stage on unrelated tasks is a project configuration problem, not a task problem. Stop re-running tasks and fix the configuration.