tq-dep-triage

name	tq-dep-triage
description	Rescue tq actions stuck pending forever because a completion dependency ended failed or cancelled. A blocked action is only released when every blocker reaches a successful terminal state, so a failed/cancelled blocker strands the dependent indefinitely. Use this whenever asked to triage blocked/stuck/stalled pending actions, find actions waiting on a dead dependency, audit blocked_by chains, or unblock the dispatch queue — including the scheduled "/tq:dep-triage" run.
context	fork
allowed-tools	Bash(tq action list*), Bash(tq action get*), Bash(tq task get*)

tq dependency triage

Completion dependencies gate dispatch: an action stays pending until every blocker reaches a successful terminal state (action=done, task=done/archived). By design there is no automatic escape — a blocker that ends failed or cancelled leaves the dependent stranded forever. This skill finds those dead ends and hands the user concrete, ready-to-run rescue commands. It does not mutate anything itself; the human decides.

What to do

Pull the pending actions and read their blocked_by:

tq action list --status pending

Each blocked_by entry has type, id, satisfied, blocker_status. The ones that matter are entries where the blocker has reached a non-success terminal state (blocker_status = failed or cancelled) — those will never flip to satisfied on their own, so the dependent is dead in the water. An unsatisfied blocker that is still pending/running/dispatched, or a task blocker still open, is just normal waiting — leave it alone.

For each stranded action, figure out the most useful recovery. Use judgment rather than a fixed recipe — the right move depends on whether the failed work still needs doing and whether it was already retried elsewhere:

• A failed blocker action may have been resumed, which creates a new action id; the original dep_id will never go done. Look for a resumed descendant by following metadata.parent_action_id from later actions back to the failed blocker (tq action get <id> / scan tq action list). If a live or done descendant exists, re-pointing the dependency at it is usually the cleanest fix.
• If the prerequisite work genuinely still needs to happen, reviving the original blocker (so it reaches done under the same id) keeps the dependency intact with no edits to the dependent.
• If the dependency is stale — the dependent no longer actually needs that prerequisite — dropping it is fine.
• If the dependent itself is now moot, retiring it clears the queue.

Surface the failed blocker's own result/reason (tq action get <id>) so the user understands why it died before choosing.

Output

Report only the genuinely stranded actions (skip normal waiting). For each, give: the blocked action (id + title), the failed/cancelled blocker (id + status + why it died), any resumed descendant you found, and the rescue options as copy-paste commands the user can run. Recommend the one you think fits, but present the alternatives and let the user choose — do not run them.

Rescue commands (fill in real ids):

# re-point to a resumed/replacement action
tq action update <blocked> --clear-deps --blocked-by-action <newid>

# revive the original blocker so it completes under the same id
tq action reset <failed_blocker>

# drop a dependency that is no longer needed
tq action update <blocked> --clear-deps

# retire a dependent that is now moot
tq action cancel <blocked>

If nothing is stranded, say so plainly — a clean queue is the expected steady state, not a finding to manufacture.