Tasks fail. Most failures stem from configuration or specification issues rather than anything mysterious, and they fall into a few common patterns.
First, check where it stopped.
The run reveals which stage failed. This single detail narrows down the cause more than anything else:
| Failed at | Almost always indicates |
|---|---|
| Before any code was written | The build or install command is incorrect for a clean workspace. |
| While making the change | Genuinely hard work, or a missing dependency. |
| Running tests | The test command is wrong, or the test suite requires a service. |
| Verification | A blocking gate; check the Findings. |
| Review | Findings that could not be fixed automatically. |
Failures before the change is written relate to 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 taking any action — this is the most common false alarm.
It is asking you for input.
NEEDS_HUMAN_REVIEW means the task has reached a decision point that only you can resolve. It is not a failure. Answer the question and it will continue from where it paused.
Answer precisely. A vague answer leads to 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 order of cost:
- Answer — for
NEEDS_HUMAN_REVIEW. Cheapest option; keeps all context. - Rework — the work is correct but incomplete. It goes back to the developer agent with your Findings and its context intact.
- Pause — you need to check something first. This frees up the slot; the task can be resumed later.
- Retry — for genuinely transient failures only. Retrying a configuration problem simply repeats it.
- Cancel and re-specify — the approach or the scope was wrong. This is the most expensive option, yet often the right choice.
Failures that repeat across tasks
The same failure at the same stage on unrelated tasks indicates a project configuration problem, not a task issue. Stop re-running tasks and fix the configuration.