Current state
When a data source (GitHub PRs, Loki alerts, Linear issues) fails to fetch, the TUI displays a terse ! <name> unreachable message in the status bar. No information is provided about the cause: whether a credential is missing from hub.toml, a network timeout occurred, or an API returned a 401. Users cannot diagnose the failure from within hub and must look at external logs or guess which config field to check.
Ideal state
- Each workflow failure carries a categorised error reason (auth failure, network timeout, missing config field, API error with status code).
- The TUI exposes the failure detail — either inline on the failing row or in a diagnostics view accessible from the status bar.
- Where possible, the error message includes an actionable hint (e.g.
check github_token in hub.toml, loki endpoint returned 401 — verify loki_token).
- A valid config with no failures produces the same output as today (no regression).
Out of scope
- Automatic remediation of misconfiguration — a clear error message is the goal, not auto-fix.
- Surfacing internal stack traces — user-facing messages only.
Starting points
workflows/src/status.rs — where errors are currently collected and returned as opaque stringsui/tui/src/render/ — where status items and error states are renderedhub.toml.example — the credential fields users need to know to check
QA plan
- Set an invalid
github_token in hub.toml, start the TUI — expect a visible error identifying authentication as the cause, not just ! github prs unreachable.
- Remove the
loki_token field entirely, run hub status — expect a message indicating the field is missing, with a hint pointing to hub.toml.
- Use a valid config, run hub status — expect normal signal display with no errors shown (no regression).
- Restore the invalid token and press the detail key on the failing row — expect the full error reason to appear.
Done when
A workflow failure in the TUI identifies the failure category and provides at least one actionable diagnostic detail that tells the user what to check.
Current state
When a data source (GitHub PRs, Loki alerts, Linear issues) fails to fetch, the TUI displays a terse
! <name> unreachablemessage in the status bar. No information is provided about the cause: whether a credential is missing fromhub.toml, a network timeout occurred, or an API returned a 401. Users cannot diagnose the failure from within hub and must look at external logs or guess which config field to check.Ideal state
check github_token in hub.toml,loki endpoint returned 401 — verify loki_token).Out of scope
Starting points
workflows/src/status.rs— where errors are currently collected and returned as opaque stringsui/tui/src/render/— where status items and error states are renderedhub.toml.example— the credential fields users need to know to checkQA plan
github_tokeninhub.toml, start the TUI — expect a visible error identifying authentication as the cause, not just! github prs unreachable.loki_tokenfield entirely, run hub status — expect a message indicating the field is missing, with a hint pointing tohub.toml.Done when
A workflow failure in the TUI identifies the failure category and provides at least one actionable diagnostic detail that tells the user what to check.