task-breakdown

# Task Breakdown

Turns a session's **per-request breakdown** (the deterministic `request_units`
emitted by session-metrics) into **semantic tasks** the user actually thinks
in — "added auth", "debugged the cache miss" — and labels each with a verdict.
You do the one thing deterministic code can't: decide which requests belong to
the same task. The script does everything else (cost, turns, tokens, waste
signals, the themed page).

**Model.** This skill runs on your session's current model. It no longer pins
one (a hard `model:` pin ran the inline turn on that model, dragging the whole
conversation into that model's context window — on a long session that
overflowed and broke invocation). The grouping + verdict work is
judgement-heavy, so it wants a capable model; for a cheaper run that's still
strong enough, `/model sonnet` before invoking. Don't drop to Haiku — the
semantic verdicts need the headroom.

**Division of labour — do not blur it:**
- **The export owns the numbers.** Every cost / turn / token / waste figure
  comes from `request_units` in the JSON export. You MUST NOT sum money or
  invent figures — `--render-tasks` recomputes all totals from the export.
- **You own the grouping + labels only.** You assign each `request_unit_id` to
  a task, write a short title, a verdict, and a one-line rationale.

## Inputs

`$ARGUMENTS[0]` (optional) = path to a session-metrics JSON export, e.g.
`exports/session-metrics/session_<id8>_<ts>.json` (session scope is the primary
target; `project_*.json` also works — units carry a `session_id`). The export
must contain a `request_units` array.

If `$ARGUMENTS[0]` is missing, first generate a session export by invoking the
**session-metrics** skill (or run its script) for the session of interest with
`--output json html`, then use the written `session_*.json` path.

## Steps

1. **Locate the export and the renderer.**
   - Export: `$ARGUMENTS[0]`, or the JSON you just generated.
   - Renderer: the sibling **session-metrics** skill's script. Resolve its
     path (it ships in the same plugin):
     - plugin install: `../session-metrics/scripts/session-metrics.py`
     - dev repo: `.claude/skills/session-metrics/scripts/session-metrics.py`
     Use whichever exists (glob if unsure).

2. **Prepare the worksheet + skeleton (preferred — you are an editor, not an
   author).** Run `--prepare-tasks` on the export: it prints a compact
   one-line-per-request worksheet to stdout and writes a *renderable* candidate
   `<stem>_grouping.json` next to the export, with deterministic clustering,
   seeded titles, and suggested verdicts already filled in.

   ```
   python3 <renderer> --prepare-tasks <export.json>
   ```

   The worksheet is your single source of grouping signals — **do not re-probe
   the JSON with `jq`/`Read`.** Each row shows the unit's candidate cluster
   (`cl`), turns, cost, tokens, `risk/reread/cbreak`, idle gap, snippet, and top
   tools; `[cont]` marks an agent-completion continuation and `[blank]` a
   no-prompt unit (both pre-attached to the preceding cluster). On a **large
   session (>120 request units)** the worksheet prints a bounded per-*cluster*
   summary instead of per-unit rows (so stdout never overflows the prompt) — the
   written skeleton still covers every unit, so treat it as your authoritative
   surface and edit it (merge/split/rename) rather than reconstructing the full
   per-unit list inline. Then **edit** the skeleton per steps 3–5 below rather
   than writing it from scratch:
   rename each seeded title (and drop its `_auto_title` field once named),
   merge/split clusters where the worksheet warrants, write one-line rationales,
   and fill any blank verdict the skeleton left for your judgment. Skip to
   step 6 (render) when done.

   *(Fallback — manual authoring.)* If you are not using `--prepare-tasks`, load
   the export JSON and read `request_units` directly. Each unit has: `unit_id`
   (`"<session_id>:<anchor_index>"`), `prompt_snippet`, `prompt_text`,
   `turn_count`, `combined_cost_usd`, `total_tokens`, `tool_histogram`,
   `risk_turn_count`, `reread_path_count`, `cache_break_count`,
   `wall_clock_seconds`, `idle_gap_before_seconds`, `slash_command`,
   `spawned_subagents`, `workflow_run_ids`, `multi_intent_possible`.
   **If `request_units` is absent**, tell the user to re-run session-metrics to
   regenerate the export (the per-request breakdown is a newer feature) and stop.

3. **Group into semantic tasks.** Read the units in order and cluster
   consecutive requests that pursue the same goal into one task. Signals, in
   priority order:
   - **Topical/lexical continuity** of `prompt_snippet`/`prompt_text` (same
     feature, file, bug, or subject) — the PRIMARY signal.
   - **Shared `tool_histogram` / file targets** across adjacent requests.
   - **Slash command / skill** starts (`slash_command`, a `/debug`,
     `/feature-dev`, etc.) often begin a task.
   - **Idle gaps** (`idle_gap_before_seconds`) — a WEAK, confirming-only hint.
     A long gap supports a split you already suspect topically; never split on
     a gap alone (lunch breaks, overnight continuations).
   - A unit flagged `multi_intent_possible` may belong to two tasks — note it,
     but keep the unit whole (it cannot be divided).
   Most sessions yield a handful of tasks. Don't over-segment ("now fix the
   test" is usually the SAME task as the feature it follows), and don't
   under-segment (one giant "misc" task is useless).
   **At large scale** (many dozens of units, e.g. a project-scope export):
   group at **session granularity** — one titled task per coherent
   session-goal — rather than attempting per-unit segmentation. **Never emit a
   single untitled catch-all task that swallows everything**: the renderer's
   collapse guard flags a blank-titled task covering the bulk of requests, and
   it is a useless grouping anyway. If you cannot segment meaningfully, that is
   a signal the input is too coarse for this skill (prefer a