diagnose-objective

Files (6)

• SKILL.md
• evals.json · evals/
• trigger-evals.json · evals/
• failure-classes.md · references/
• procedure.md · references/
• objective-timeline.sh · scripts/

SKILL.md (first lines)

# diagnose-objective

Explain why an objective failed or stalled, from the files the orchestration already wrote.
Output is one report, `.dev-files/objectives/<id>/diagnosis.md`, ending in one next command.

Role contract: [`core/roles/debugger.md`](../../../core/roles/debugger.md). State model:
[`docs/engineering/architecture/orchestration-state-machine.md`](../../../docs/engineering/architecture/orchestration-state-machine.md).

## Why this skill exists

An objective leaves a complete paper trail — `objective.json`, one task file per task, one
handoff per finished task, a compaction snapshot, a rate-limit record — and every transition
is a file write. When it dies, the explanation is already on disk; what is missing is the
reading. Without this skill the reader is a human paging through JSON, or an orchestrator
that resumes by guessing and re-runs a task whose handoff exists (duplicating its commits).
The failure classes are known and finite (see
[`references/failure-classes.md`](references/failure-classes.md)); detecting them is
deterministic, so a script does it and the model explains it.

**Validation tier: 0.** This skill runs no project tests and changes no state. It reads,
and it writes exactly one file: `diagnosis.md`.

## Step 1 — locate the objective

In this order; stop at the first hit:

1. the argument (`/diagnose-objective auth-system`);
2. `$SUPERPOWERS_OBJECTIVE_ID`, when exported;
3. `bash $S active` (the objective the current branch names, else the most recently updated
   open one);
4. the most recently updated directory under `.dev-files/objectives/` — a *completed* or
   *abandoned* objective is still diagnosable.

```bash
S=skills/dev-workflow/_shared/scripts/objective-state.sh
bash $S list
bash $S path <id>          # .dev-files/objectives/<id>
```

No `.dev-files/objectives/` at all: say so and stop. There is nothing to diagnose without
state, and inventing a timeline from the transcript is the one thing this skill must not do.

## Step 2 — run the timeline script first

```bash
D=$(bash $S path <id>)
bash skills/dev-workflow/diagnose-objective/scripts/objective-timeline.sh "$D"
```

It prints one JSON document: `objective`, `tasks[]` (each merged with its handoff or
`handoff.present: false`), `timeline[]` sorted by time, `snapshots`, `git`, `findings[]`,
`first_cause` and `next_command`. It is deterministic and offline — the same files give the
same answer every time, which is what makes the report reviewable.

Where the `git` capability is present it also checks whether the integration branch is
behind a completed worker's branch and whether a task worktree is dirty; without git
(`git.available: false`) those two checks are skipped and the report says so under
Evidence rather than silently reporting "not behind".

`--markdown` renders the same facts as the report skeleton used in Step 4.

## Step 3 — read the evidence the findings name

Every finding carries `evidence[]`: paths relative to the objective directory (or to the repo
root for `.dev-files/compaction/latest.md` and `.dev-files/handoffs/rate-limit-*.json`).
Read those files — all of them, nothing else — and confirm or refute each finding against
[`references/failure-classes.md`](references/failure-classes.md), which gives per class what
the files must show, the usual real-world cause, and the next command.

Then read every handoff `summary`, `risks[]` and blocking `followups[]` in task order. The
script sees structure; the summaries say what the worker thought was happening, and a
`partial` whose summary names a missing dependency is a different diagnosis from one whose
summary names a flaky test.

Check `first_cause` with one question: *is this the earliest finding that the others follow
from?* The script picks the earliest high-severity finding by timestamp. If a later finding
is the real root (a `shared-branch` that only mattered once the second worker committed), say
so and promote it — the script's choice is evidence, not a verdict.

## Step 4 — write `diagnosis.md`

Write `.dev-files/objectives/<id>/diagnosis.md` with exactly these sections, in this order.
The full template with worked examples is in
[`references/procedure.md`](references/procedure.md).

```markdown
# Diagnosis: <id>
## What happened        — the timeline table, one row per event, as the script printed it
## First cause          — one paragraph: the class, the task, the evidence line, the mechanism
## All findings         — every finding, severity-tagged; "none" when the objective is clean
## Evidence             — the files read, one per line, so a reviewer can re-derive this
## Next command         — one command; what it will do; what to check after it
```

Rules for the report:

- **Prose explains; it never contradicts the files.** A `completed` handoff with an empty
  `validation[]` is "a claim with no evidence", not "probably fine, the summary says it ran".
- **One next command.** Resume with `/switch-dev handoff objective=<id> <task>` when work
  exists without a record; re-run with `/worker-dev <id> <task>` when a task has no handoff
  and nothing to save; decide and integrate with `/orchestrate-dev <id>` for everything that
  is a planning or integration problem. The mapping is fixed in
  [`references/failure-classes.md`](references/failure-classes.md).
- **Say what was not checked.** No git → no integration-lag check. No compaction snapshot →
  say none was found. Absent is a legitimate value; inferred is not.
- `diagnosis.md` is the only write. Overwriting an earlier diagnosis is fine; it is a report,
  not state.

## Step 5 — report

In chat: the first cause in two sentences, the next command, and the path to `diagnosis.md`.
Not the timeline — that is what the file is for.

## Hard rules

1. **Never change objective, task or handoff state.** Not `task-set`, not `set-status`, not a
   hand-written handoff "to unblock things". The next command names who changes state.
2. **Never re-run, re-plan or integrate.** This skill ends at a report. `/worker-dev`,
   `/orchestrate-dev` and `/switch-dev` do the rest, and only when the user runs them.

From Tamircohen28/tamirs-superpowers, MIT.

More from Tamircohen28/tamirs-superpowers