# okstra-inspect facet — errors

Loaded lazily by the dispatch table in `SKILL.md` (core). Shared rules — Step 0 preflight, the standard task-key resolution rule (0/1/N), the no-task fallback, and Output Rules — live in the core file and still apply here.

## errors

Trigger phrases: "okstra errors", "error report", "error summary", "gather the errors", "clean up failure logs".

Aggregate a task's okstra-run error logs (`runs/*/logs/errors-*.jsonl`, lead-observed + worker-reported) into a timestamped markdown report and summarize it. This sub-command renders a **read-derived artifact** (a `.md` file) but never mutates task state (`task-manifest.json`, catalog, timeline).

### errors.1 — Resolve target

Accepted target forms (same as `cost`):

1. Full task-key: `<project-id>:<task-group>:<task-id>`.
2. Bare token (task-id or task-group) — resolve via the standard task-key resolution rule in `SKILL.md` (core).
3. Task root path.

If the user asks for an error report without naming a task, apply the core no-task fallback — never list only placeholder forms and ask back.

### errors.2 — Run the renderer

Use the CLI output as the source of truth:

```bash
okstra error-report <resolved-target> --project-root <projectRoot> --text
```

For a task-root path, run `okstra error-report <path>` directly. Do not parse the jsonl files by hand unless the CLI fails and the user explicitly asks for a manual fallback.

### errors.3 — Summarize output

Use the fixed text labels and report:

| Field | Source |
|---|---|
| Report file | `reportPath` (project-root-relative `.md`) |
| Total errors | `totals.errorCount` |
| Logs (runs) | `totals.runCount` |
| By errorType | `totals.byErrorType` (tool-failure / cli-failure / contract-violation) |
| By source | `totals.bySource` (lead-observed / worker-reported) |
| By phase | `byPhase[]` |
| By agent | `byAgent[]` |
| Parse-skipped lines | `parseSkipped` |

- If `reportPath` is empty AND `totals.errorCount == 0`: report `This task has no recorded error logs.` and do not claim a file was written.
- Otherwise show the `.md` path and offer to read it.
- If `parseSkipped > 0`, surface it (do not silently hide malformed lines).

### errors — Output template

```markdown
## okstra Error Report — <task-key>

- Report: `<reportPath-or-->`
- Total errors: <N> across <runCount> log(s)
- By type: <tool-failure: a, cli-failure: b, ...>
- By source: <lead-observed: x, worker-reported: y>

| Phase | Count |
|---|---:|
| implementation | 3 |

| Agent | Count |
|---|---:|
| codex-worker | 2 |

<If parseSkipped > 0: "⚠ Parse-skipped lines: <N>">
```