# v0.5.0 Issue Breakdown

This breaks the `v0.5.0` observability release into issue-sized slices that can
be executed independently but still land in a coherent order.

## 1. Step timeline persistence
**Outcome:** each workflow run records per-step lifecycle data.

### Acceptance criteria
- Persist step start/end timestamps, durations, and terminal outcomes.
- Preserve timeline continuity across resume/retry paths.
- Keep schema backward-compatible for existing run history consumers.

## 2. Failure attribution model
**Outcome:** operators get a stable cause category, not just a raw error blob.

### Acceptance criteria
- Define and document a first-pass failure taxonomy.
- Map known failures into categories with fallback to `unknown`.
- Include a concise human-readable failure hint in summaries.

## 3. `tt runs` detailed inspection
**Outcome:** one command can explain an individual run.

### Acceptance criteria
- Add a detailed single-run view in text and JSON.
- Show ordered steps, durations, statuses, failure category, and failure message.
- Link the failing step back to the responsible agent when applicable.

## 4. Status and watch observability pass
**Outcome:** live views show stage progress, not just coarse health.

### Acceptance criteria
- Show current workflow stage and the latest terminal failure.
- Keep output readable in narrow terminals.
- Do not regress existing health-state classification behavior.

## 5. Local API run-history surfaces
**Outcome:** dashboards and external tools can query structured run data.

### Acceptance criteria
- Expose read endpoints for run summary, run detail, and recent events.
- Define stable response shapes and idempotent semantics.
- Cover basic happy-path and missing-run cases in tests.

## 6. Local web dashboard
**Outcome:** `observe.dashboard` and `observe.port` power a first usable local web dashboard.

### Acceptance criteria
- Remove the "parsed but not acted on" state for observe config.
- Ship a minimal browser-based local dashboard behind the config.
- Show current agent state, recent runs, and latest failures from first-class data.
- Keep the implementation local-first and optional.

## 7. Operator debugging docs
**Outcome:** the workflow for diagnosing failures is documented, not tribal.

### Acceptance criteria
- Document the operator loop from failed run to root-cause inspection.
- Include examples for provider, policy, and tool failures.
- Link from the README and planning docs.

## Suggested landing order
1. Step timeline persistence
2. Failure attribution model
3. `tt runs` detailed inspection
4. Local API run-history surfaces
5. Status and watch observability pass
6. Observe config activation
7. Operator debugging docs
