task-breakdown

name

task-breakdown

description

Group a session-metrics session's turns into higher-level SEMANTIC TASKS ("what was I actually trying to do") and render a Tasks companion page (*_tasks.html + *_tasks.md) with a worth-it / mixed / likely-waste verdict per task. Trigger when the user runs /task-breakdown, when session-metrics suggests a task breakdown after a JSON export, or when the user asks to "group my turns into tasks", "what tasks did this session cover", "which work was worth it vs wasted", or "break this session into tasks". Consumes the deterministic per-request breakdown (request_units) from a session-metrics JSON export — it never re-derives cost or token numbers. Args: $ARGUMENTS[0] = path to a session-metrics JSON export (optional; if omitted, generate one first).

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, , , , , , , , , , , . , tell the user to re-run session-metrics to regenerate the export (the per-request breakdown is a newer feature) and stop.

Guardrails

• Never invent or sum numbers. If you need a total, read it from the export or from the rendered *_tasks.md after --render-tasks runs.
• Don't touch the workflow companion (*_workflows.*) — the Tasks page is a separate, additional artifact.
• Honest framing: the deterministic dashboard section is "per-request breakdown"; only this skill's output is allowed to call groups "tasks", because only here did a human-level judgement decide the boundaries.