From 97a1585dbcab1b767c4e4e90ac31736a331d36ef Mon Sep 17 00:00:00 2001
From: Kjell Tore Guttormsen <ktg@humanize.no>
Date: Sun, 19 Apr 2026 22:47:16 +0200
Subject: [PATCH] feat(config-audit): add /config-audit tokens command (ranked
 hotspots + recommendations)

---
 plugins/config-audit/commands/tokens.md | 123 ++++++++++++++++++++++++
 1 file changed, 123 insertions(+)
 create mode 100644 plugins/config-audit/commands/tokens.md

diff --git a/plugins/config-audit/commands/tokens.md b/plugins/config-audit/commands/tokens.md
new file mode 100644
index 0000000..d156cac
--- /dev/null
+++ b/plugins/config-audit/commands/tokens.md
@@ -0,0 +1,123 @@
+---
+name: config-audit:tokens
+description: Show ranked token hotspots and Opus 4.7 pattern findings — what's costing the most per turn and how to reduce it
+argument-hint: "[path] [--global]"
+allowed-tools: Read, Bash
+model: sonnet
+---
+
+# Config-Audit: Token Hotspots
+
+Show the configuration sources that contribute the most tokens per turn, ranked by estimated tokens, with Opus 4.7-specific recommendations for reducing prompt-cache misses, schema bloat, and deep import chains.
+
+Complementary to `/config-audit whats-active`:
+- **`whats-active`** = inventory view (what loads).
+- **`tokens`** = action view (what to trim and why).
+
+## UX Rules (MANDATORY — from `.claude/rules/ux-rules.md`)
+
+1. **Never show raw JSON or stderr output.** Always use `--output-file` + `2>/dev/null`.
+2. **Narrate before acting.** Tell the user what you're about to do.
+3. **Read, don't dump.** Read the JSON file and render formatted tables.
+4. **End with context-sensitive next steps.**
+
+## Implementation
+
+### Step 1: Parse `$ARGUMENTS`
+
+Split `$ARGUMENTS` into a path and flags. Path is the first non-flag argument. Default to `.` (current working directory). Recognized flags:
+
+- `--global` — also include the user-level `~/.claude/` cascade
+- `--json` — emit raw JSON instead of rendered tables (power-user mode)
+
+### Step 2: Run the CLI silently
+
+Tell the user: **"Analysing token hotspots for `<path>`..."**
+
+```bash
+TMPFILE="/tmp/config-audit-tokens-$$.json"
+node ${CLAUDE_PLUGIN_ROOT}/scanners/token-hotspots-cli.mjs <path> --output-file "$TMPFILE" [--global] 2>/dev/null; echo $?
+```
+
+**Exit code handling:**
+- `0` → continue
+- `3` → tell user: "Couldn't analyse tokens. Check that the path exists and is a directory." Stop.
+
+### Step 3: If `--json` was requested, cat the file and stop
+
+```bash
+cat "$TMPFILE"
+```
+
+Do NOT render tables in JSON mode.
+
+### Step 4: Read JSON and render
+
+Use the Read tool on `$TMPFILE`. Extract:
+
+- `total_estimated_tokens` — top-line number
+- `hotspots[]` — top 10 ranked sources
+- `findings[]` — Opus 4.7 pattern findings (CA-TOK-001..004)
+- `counts` — severity breakdown
+
+Render as markdown:
+
+```markdown
+**Token hotspots for `<path>`** — ~{total_estimated_tokens} estimated tokens loaded per turn
+
+### Top hotspots (ranked by estimated tokens)
+
+| Rank | Source | Tokens | Recommendations |
+|------|--------|--------|-----------------|
+| {rank} | `{source}` | ~{estimated_tokens} | {recommendations joined as `· ` bullets} |
+
+### Opus 4.7 pattern findings
+
+{For each finding, render:}
+
+- **{id}** ({severity}) — {title}
+  - {description}
+  - **Fix:** {recommendation}
+
+### Severity summary
+
+| Severity | Count |
+|----------|-------|
+| critical | {counts.critical} |
+| high | {counts.high} |
+| medium | {counts.medium} |
+| low | {counts.low} |
+| info | {counts.info} |
+
+_Estimates assume ~4 chars/token (Claude ballpark). Real token count varies ±20%._
+```
+
+### Step 5: Cleanup and next steps
+
+```bash
+rm -f "$TMPFILE"
+```
+
+```markdown
+### What's next
+
+- **`/config-audit whats-active`** — full inventory of what loads (plugins, skills, MCP, hooks)
+- **`/config-audit posture`** — overall health scorecard (Token Efficiency is the 8th area)
+- **`/config-audit fix`** — auto-fix deterministic issues (where applicable)
+- See `knowledge/opus-4.7-patterns.md` for the full pattern catalogue (CA-TOK-001 … 004)
+```
+
+## Scope and limits
+
+- **Read-only.** Inspects config files; never writes.
+- **Single repo.** Scans one path per invocation.
+- **Structural only.** Hotspots are deterministic byte→token estimates from disk; runtime cache hit-rate is out of scope.
+- **Heuristic estimates.** ~4 chars/token for markdown, ~3.5 for JSON. Real counts vary ±20%.
+
+## Error handling
+
+| Condition | Action |
+|-----------|--------|
+| Exit code 3 | Tell user path is invalid, suggest checking path exists |
+| JSON parse fails | Tell user to re-run, mention as a bug to report |
+| Empty hotspots | Suggest adding a CLAUDE.md or running `/config-audit feature-gap` first |