> ## Documentation Index
> Fetch the complete documentation index at: https://smithers.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# triage-run

> Diagnose one failed or stuck Smithers run and propose a fix, rewind, retry, or escalation.

`triage-run` is an archived example, not installed by `init`: copy it from `examples/init-pack/` with its dependency closure, or ask `create-workflow` to build an equivalent.

`triage-run` takes a single run id, pulls that run's state and recent event log,
diagnoses the most likely root cause, and recommends the next move: fix,
rewind, retry, or escalate. Reach for it when a run fails or stalls: a grounded
read and a concrete command beat eyeballing logs.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
bunx smithers-orchestrator workflow run triage-run --input '{"targetRunId":"RUN_ID"}'
```

The input is `targetRunId`, not `runId`: the engine reserves `input.runId` for
a run's own id, so a workflow inspecting another run needs a distinct name.

## Stages

1. **gather**: deterministic (no agent); shells `inspect <targetRunId> --format json` and `events <targetRunId>`, returning `state`, the run-level `runError`, `failingNodes`, any `pendingApprovals` it's suspended on, the tail of `lastEvents`, an `ok` flag (false when inspect could not be read), and a one-line `summary`.
2. **diagnose**: an agent reads the evidence and names the most likely `rootCauseHypothesis`, with supporting `evidence` and a `confidence` level. Pending approvals are read as a stuck state, not a failure; recurring identical errors point at a persistent defect, one-off network resets at a transient one.
3. **recommend**: an agent proposes one `recommendedAction` (`fix` | `rewind` | `retry` | `escalate`), the `command` to run next, and a `rationale`. A run waiting on an approval is always escalated, never rewound or retried.

Every stage is read-only: it never mutates the run, so the recommended command is yours to run.

## Inputs

| Input         | Type   | Default                                      |
| ------------- | ------ | -------------------------------------------- |
| `targetRunId` | string | (required) the failed or stuck run to triage |

## Monitor it

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
bunx smithers-orchestrator workflow run triage-run --input '{"targetRunId":"RUN_ID"}' -d   # detach
bunx smithers-orchestrator ps                                                              # active / paused / recent
bunx smithers-orchestrator logs RUN_ID -f                                                  # follow events
bunx smithers-orchestrator output RUN_ID --node recommend                                  # read the recommendation
```