task-breakdown
This Claude Code skill groups individual API requests from a session-metrics export into semantic tasks that match user intent ("added auth," "debugged cache"), assigns verdicts, and prepares them for rendering with cost and token tallies. Use it after running session-metrics to transform raw request-level data into human-readable task summaries, delegating grouping and labeling to Claude while preserving all numerics from the export.
git clone --depth 1 https://github.com/centminmod/my-claude-code-setup /tmp/task-breakdown && cp -r /tmp/task-breakdown/.claude/skills/task-breakdown ~/.claude/skills/task-breakdownSKILL.md
# 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). 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 single-session
export).
4. **Label each task with a verdict**, using the deterministic waste signals as
evidence, NOT a guess:
- `worth_it` — the task reached its goal at reasonable cost; low
`risk_turn_count` / re-read churn relative to its size.
- `likely_waste` — high `risk_turn_count`, repeated `reread_path_count`,
many `cache_Use this agent for comprehensive codebase analysis, forensic examination, and detailed code mapping with optional Chain of Draft (CoD) methodology. Excels at locating specific functions, classes, and logic, security vulnerability analysis, pattern detection, architectural consistency verification, and creating navigable code reference documentation with exact line numbers. Examples: <example>Context: User needs to find authentication-related code in the project. user: "Where is the user authentication logic implemented?" assistant: "I'll use the code-searcher agent to locate authentication-related code in the codebase" <commentary>Since the user is asking about locating specific code, use the code-searcher agent to efficiently find and summarize authentication logic.</commentary></example> <example>Context: User wants to understand how a specific feature is implemented. user: "How does the license validation work in this system?" assistant: "Let me use the code-searcher agent to find and analyze the license validation implementation" <commentary>The user is asking about understanding specific functionality, so use the code-searcher agent to locate and summarize the relevant code.</commentary></example> <example>Context: User needs to find where a bug might be occurring. user: "I'm getting an error with the payment processing, can you help me find where that code is?" assistant: "I'll use the code-searcher agent to locate the payment processing code and identify potential issues" <commentary>Since the user needs to locate specific code related to an error, use the code-searcher agent to find and analyze the relevant files.</commentary></example> <example>Context: User requests comprehensive security analysis using Chain of Draft methodology. user: "Analyze the entire authentication system using CoD methodology for comprehensive security mapping" assistant: "I'll use the code-searcher agent with Chain of Draft mode for ultra-concise security analysis" <commentary>The user explicitly requests CoD methodology for comprehensive analysis, so use the code-searcher agent's Chain of Draft mode for efficient token usage.</commentary></example> <example>Context: User wants rapid codebase pattern analysis. user: "Use CoD to examine error handling patterns across the codebase" assistant: "I'll use the code-searcher agent in Chain of Draft mode to rapidly analyze error handling patterns" <commentary>Chain of Draft mode is ideal for rapid pattern analysis across large codebases with minimal token usage.</commentary></example>
Execute OpenAI Codex CLI (GPT-5.2) for code analysis. Use when you need Codex's GPT-5.2 perspective on code.
Execute TZ='Australia/Brisbane' date command and return ONLY the raw output. No formatting, headers, explanations, or parallel agents.
Use this agent proactively to synchronize memory bank documentation with actual codebase state, ensuring architectural patterns in memory files match implementation reality, updating technical decisions to reflect current code, aligning documentation with actual patterns, maintaining consistency between memory bank system and source code, and keeping all CLAUDE-*.md files accurately reflecting the current system state. Examples: <example>Context: Code has evolved beyond documentation. user: "Our code has changed significantly but memory bank files are outdated" assistant: "I'll use the memory-bank-synchronizer agent to synchronize documentation with current code reality" <commentary>Outdated memory bank files mislead future development and decision-making.</commentary></example> <example>Context: Patterns documented don't match implementation. user: "The patterns in CLAUDE-patterns.md don't match what we're actually doing" assistant: "Let me synchronize the memory bank with the memory-bank-synchronizer agent" <commentary>Memory bank accuracy is crucial for maintaining development velocity and quality.</commentary></example>
Use this agent when you need comprehensive UX/UI design guidance, including user experience optimization, premium interface design, scalable design systems, data visualization with Highcharts, or Tailwind CSS implementation. Examples: <example>Context: User is building a dashboard with complex data visualizations and wants to improve the user experience. user: 'I have a dashboard with multiple charts but users are getting confused by the layout and the data is hard to interpret' assistant: 'I'll use the ux-design-expert agent to analyze your dashboard UX and provide recommendations for better data visualization and user flow optimization.'</example> <example>Context: User wants to create a premium-looking component library for their product. user: 'We need to build a design system that looks professional and scales across our product suite' assistant: 'Let me engage the ux-design-expert agent to help design a scalable component library with premium aesthetics using Tailwind CSS.'</example> <example>Context: User is struggling with a complex multi-step user flow. user: 'Our checkout process has too many steps and users are dropping off' assistant: 'I'll use the ux-design-expert agent to streamline your checkout flow and reduce friction points.'</example>
Execute z.ai GLM 4.7 model via Claude Code CLI. Use when you need z.ai's GLM 4.7 perspective on code analysis.
Generate PNG images using AI (multiple models via OpenRouter including Gemini, FLUX.2, Riverflow, SeedDream, GPT-5 Image, GPT-5.4 Image 2, proxied through Cloudflare AI Gateway BYOK). Also analyze/describe existing images using multimodal AI vision. Use when user asks to "generate an image", "create a PNG", "make an icon", "make it transparent", "describe this image", "analyze this image", "what's in this image", "explain this image", or needs AI-generated visual assets for the project. Supports model selection via keywords (gemini, riverflow, flux2, seedream, gpt5, gpt5.4), configurable aspect ratios/resolutions, transparent backgrounds (-t), reference image editing (-r), image analysis (--analyze), and per-project cost tracking (--costs).
>