Triage a Stuck Issue

An old issue is not automatically stuck. It may be waiting for a person, a dependency, a subtask, a required CI check, or available Worker capacity. Diagnose the current state and latest event before changing it.

Find the issue

Colony Cloud
Self-Host

The Inbox (/dashboard/inbox) surfaces issues and system conditions that need attention, including recurring failures. Use Pipeline for the complete state grid and open an issue to inspect its timeline, error details, workflow, and currently valid actions.

Run:

colony status --db

This reads pipeline state from Postgres and identifies old active work. Use colony status --db --watch for a live view. GitHub labels are useful for finding an issue, but the database is authoritative. For a specific failure, correlate the issue number with Mayor and Worker logs.

Diagnose before intervening

Check, in order:

The current database state and how long the issue has been there.
The latest pipeline event, issue comment, or deterministic-check output.
Worker and task-queue health.
Whether the state is intentionally waiting.

State or condition	What to verify	Normal resolution
`needs-clarification`	The analyzer’s questions and whether a new issue comment answered them	A human reply re-enters analysis
`dependency-blocked`	The recorded dependency is still incomplete	Colony unblocks it after the dependency completes
`waiting-for-subtasks`	All child issues and their merge state	The parent resumes after its dependency policy is satisfied
`human-review-ready`	A human review or merge is still pending	Review and merge, or send explicit feedback
`merge-pending`	Required checks, conflicts, approvals, and merge policy	Satisfy the missing merge condition or use a valid recovery action
`failure-blocked`	The block reason, last executor error, cost state, and any CI-repair activity	Fix the cause, then invoke a workflow-valid action
Active state with no task	Queue health, claim history, Worker health, and any dead letter	Restore capacity or recover the failed enqueue/transition

Do not clear a dependency by using /colony:skip-planning; that command changes planning behavior and is not a dependency override.

Choose the smallest valid intervention

Cloud shows only actions valid for the issue’s pinned workflow. On GitHub, the workflow still validates slash commands even if a command exists globally.

/colony:retry re-enqueues the current executable stage. An optional small, medium, or large argument overrides the retry tier.
/colony:feedback preserves the current implementation direction and sends concrete change guidance back to development where supported.
/colony:reanalyze reruns analysis from the workflow’s declared target.
/colony:reimplement closes and discards the current implementation and follows the workflow’s reimplementation route.
/colony:pause, /colony:resume, and /colony:cancel are operational controls.

See Slash Commands for syntax and state restrictions. If Colony does not acknowledge a command, check webhook delivery, app permissions, the command root, and Mayor health; a missing reaction alone does not identify the cause.

Verify recovery

Confirm a new timeline event or task was created.
Confirm the issue left its waiting or blocked state, or that its intended retry is now queued.
Watch the next executor result instead of issuing repeated commands.
If an unresolved dead letter remains, recover or acknowledge that record separately.

Reduce recurrence

Repeated clarification usually calls for clearer issue outcomes. Repeated deterministic failures call for accurate setup commands and review checks. Repeated review loops may indicate unclear requirements, stale conventions, or conflicting feedback. Repeated cost or turn exhaustion may justify a different complexity tier, model route, or issue scope—but increasing limits should follow diagnosis, not replace it.