Audit Session Metrics

Audit Session-Metrics

Reads a session-metrics JSON export and produces a prioritised, plain-English audit of token-usage waste. It runs on the session's current model (it no longer pins one — a hard model pin capped the usable context at that model's window and broke invocation on long sessions). The work is mostly summarisation over a small disk-read export, so for a much cheaper run /model haiku before invoking. On the Anthropic API haiku is Haiku 5.5 (1M window, so long sessions fit; prompts over 100K tokens bill at its higher rate). On Bedrock, Google Cloud, Microsoft Foundry, and Claude Platform on AWS it is still Haiku 4.5 with a 200k window — short/early sessions only there.

Supports three JSON scopes auto-detected from digest.scope:

• session — single session (session_*.json) — per-turn analysis
• project — all sessions for one project (project_*.json) — per-session analysis
• instance — all projects (instance/*/index.json) — per-project analysis

Dispatch — how to route this invocation

First positional argument received: $ARGUMENTS[0] Second positional argument received: $ARGUMENTS[1]

Read $ARGUMENTS[0] and match by literal equality:

$ARGUMENTS[1] must be the path to a JSON export written by session-metrics. Accepted patterns:

• exports/session-metrics/session_<id8>_<ts>.json — session scope
• exports/session-metrics/project_<ts>.json — project scope
• exports/session-metrics/instance/<datedir>/index.json — instance scope

If $ARGUMENTS[1] is missing, empty, or the file does not exist, print:

Usage: /audit-session-metrics {quick|detailed} <path-to-session-metrics.json>

Accepted JSON types: session: exports/session-metrics/session_*.json project: exports/session-metrics/project_*.json instance: exports/session-metrics/instance/*/index.json

…and stop without further work.

Steps

1. Run the extract helper once with the input path:

   python3 scripts/audit-extract.py $ARGUMENTS[1] --mode $ARGUMENTS[0]

   The helper emits a single JSON digest to stdout. Read digest.scope from the output — it will be "session", "project", or "instance". Do not read the raw .jsonl, and do not re-derive numbers the digest already carries.

2. Scope routing — read the matching reference file:

   digest.scope	$ARGUMENTS[0]	Reference file
   session	quick	references/quick-audit.md
   session	detailed	references/detailed-audit.md
   project	quick	references/project-quick-audit.md
   project	detailed	references/project-detailed-audit.md
   instance	quick or detailed	references/instance-quick-audit.md

   Follow the playbook step-by-step. Do not improvise additional phases.

3. For detailed mode on session scope only, the playbook also asks you to read the user's config files (~/.claude/CLAUDE.md, ./CLAUDE.md, ~/.claude/settings.json, ./.claude/settings.json, ./.claudeignore). Each is capped at ≤500 lines — if a file is bigger, that itself is a finding.

4. Output contract — three artefacts. All playbooks specify the same three-artefact contract:

   • JSON sidecar at <project>/exports/session-metrics/audit_<id8>_<ts>_<mode>.json — structured findings (versioned schema, enum'd metrics).
   • Markdown copy at <project>/exports/session-metrics/audit_<id8>_<ts>_<mode>.md — same content rendered for humans.
   • Inline chat output — the markdown content printed in your reply.

   <id8> and <ts> come from digest.session_id_short and digest.ts_str (the helper parses the input filename and normalises all three filename patterns).

5. Write order. Populate the JSON object first using the digest values, write the JSON sidecar, render the markdown using the template in the playbook, write the markdown copy, then print the markdown inline (without the H1 heading — the chat client already shows context above the audit). Finish with two stderr-style lines on their own: [audit] saved → <json-path> [audit] saved → <md-path>

   IMPORTANT: Use the Write tool directly for steps 3 and 5. Do NOT generate a Python script (e.g. writing to /tmp/audit_synthesis.py and executing it) — this adds unnecessary failure modes (syntax errors, f-string escaping) and is never required. Build the JSON in the AI's own context; call Write. Render the markdown in context; call Write again.