/workflow-inspect

name: workflow-inspect
description: >
  Appends the cost half to a workflow-retro record: parses the feature
  session's Claude Code transcripts with a bundled read-only script
  (tokens per agent, wall-clock, handoff tax) and writes the result into
  the record's Cost section. Companion of /workflow-retro; run it while
  the transcripts still exist (they are pruned after Claude Code's
  retention window, ~30 days by default). Requires python3.
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/inspect.py *)

/workflow-inspect — Compute the Feature's Workflow Cost

Run this skill after `/workflow-retro` has recorded a feature's outcome, and within the transcript retention window. It fills the record's pending `## Cost` section with numbers computed from the raw session transcripts: tokens and wall-clock per sub-agent, the sub-agents' share of the total, and the handoff tax (files the planner read that the main agent re-read). Together the two halves say what each workflow step cost *and* caught — the evidence base for tuning the workflow (see *Evolving the System* in the AI Workflow plugin's own documentation).

**Ground rules:**

• **Numbers come from the script, verbatim.** Never estimate, adjust, or

fill in a figure the script did not print. If the script fails or its output carries warnings, surface them to the user as-is (Rule 2 in `AGENTS.md` applies to the script like any other command).

• **The only mutation is the log file.** Replacing the `## Cost` section of

the chosen record(s) — after the user confirms — is the only write this skill performs. Never commit anything; `.workflow-log/` stays local.

• The bundled script (`inspect.py`, in this skill's directory) is

**read-only**: it parses transcripts and prints markdown to stdout.

Step 1 — Pick the record(s)

Resolve the log directory exactly as `/workflow-retro` does: `.workflow-log/` under the main worktree (parent of `git rev-parse --path-format=absolute --git-common-dir`). List the records whose `## Cost` section is still pending. One pending record → proceed with it; several → ask which to inspect (offering "all" — each is one script run). None → report that every record is already inspected and stop.

Step 2 — Gather the session IDs

Read the record's `Sessions:` line. If it is `unknown`, or Step 3 finds no transcript for any listed ID, the cost is unrecoverable once transcripts are pruned — with the user's confirmation, close the section honestly with `unavailable — transcripts pruned or session IDs unknown` instead of leaving `pending` forever.

Step 3 — Run the inspector

One command, from the repository root:

python3 ${CLAUDE_SKILL_DIR}/inspect.py <session-id> [<session-id> …]

It locates each session's transcript by a **global search** of `~/.claude/projects/` (transcripts are filed under the session's *launch* directory, which for worktree-launched sessions is not the worktree — never derive the directory from a path), resolves every sub-agent transcript via its spawn `toolUseId`, deduplicates records shared by resumed sessions, and prints a complete `## Cost` section. It fails soft: what it cannot parse or find becomes a warning line inside that output, and the numbers are then lower bounds.

Step 4 — Reconcile

Before writing, act on what the output says:

• A warning that sub-agent transcripts belong to **sessions not listed in

the record** means the feature spanned more sessions than the retro knew about (resumed sessions carry history over). Offer to add those IDs to the record's `Sessions:` line and re-run the script once with the full list.

• If the cost data contradicts the record's outcome half (e.g. more

sub-agent runs than the Steps table's review rounds), point the discrepancy out to the user — the outcome sections are theirs to amend; do not edit them yourself.

Step 5 — Confirm and write

Show the user the script's output. On confirmation, replace the record's entire `## Cost` section (heading included) with it, leaving every other section untouched, and report the file path. If the user declines, leave the record as it was.