/audit

name: audit
description: "Review past Claude Code sessions for PBR workflow compliance and UX quality."
allowed-tools: Read, Write, Bash, Glob, Grep, Task, AskUserQuestion
argument-hint: "[--from DATE] [--to DATE] [--today] [--mode compliance|ux|full] [--preset minimal|standard|comprehensive] [--dimension ID...] [--skip ID...] [--only ID...]"

**STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes tokens. Begin executing Step 0 immediately.**

Step 0 — Immediate Output

**Before ANY tool calls**, display this banner:

╔══════════════════════════════════════════════════════════════╗
║  PLAN-BUILD-RUN ► SESSION AUDIT                              ║
╚══════════════════════════════════════════════════════════════╝

Then proceed to Step 1.

/pbr:audit — Session Compliance & UX Review

You are running the **audit** skill. Your job is to analyze past Claude Code session logs for this project, checking PBR workflow compliance (STATE.md updates, hook firing, commit format, skill usage) and user experience quality (flow choice, friction, unmet expectations). You produce a comprehensive report document.

This skill uses **parallel Task() delegation** to analyze multiple sessions simultaneously, keeping main context lean.

---

Context Budget

Reference: `skills/shared/context-budget.md` for the universal orchestrator rules. Reference: `skills/shared/agent-type-resolution.md` for agent type fallback when spawning Task() subagents.

Additionally for this skill:

• **Delegate ALL session analysis** to audit subagents — do NOT read JSONL files in main context
• Main context handles: argument parsing, session discovery, agent orchestration, report synthesis
• Target: main context stays under 20% utilization

---

Step 1 — Parse Arguments

Parse `$ARGUMENTS` for:

| Argument | Default | Description | |----------|---------|-------------| | `--from DATE` | Start of today | Start of audit window (ISO date or natural language) | | `--to DATE` | Now | End of audit window | | `--today` | false | Shorthand for `--from` start of today `--to` now | | `--mode MODE` | `full` | `compliance` = workflow only, `ux` = user experience only, `full` = both | | `--preset PRESET` | config.json audit.preset | Override audit preset (minimal/standard/comprehensive) | | `--dimension ID` | (none) | Add specific dimension(s) to the active set. Accepts code (SI-01) or slug (skill-template-refs). Repeatable. | | `--skip ID` | (none) | Remove specific dimension(s) from the active set. Accepts code or slug. Repeatable. | | `--only ID` | (none) | Run ONLY these dimensions, ignoring preset/categories. Accepts code or slug. Repeatable. |

**Natural language parsing**: Accept formats like:

• `--today` or just `today`
• `--from 2026-02-21` or `--from "yesterday"`
• `--from "3 days ago"` or `--from "last monday"`
• A bare date like `02/21` implies `--from 02/21 --to 02/21` (full day)
• A bare `3` implies last 3 days

If no arguments provided, default to `--today --mode full`.

Display the parsed time range to the user:

Audit window: {from} → {to}
Mode: {mode}

---

Step 1b — Resolve Dimensions

Load the project's `config.json` audit section. Build `cliFlags` from parsed arguments:

const cliFlags = {
  preset: parsedArgs.preset,       // string or undefined
  dimension: parsedArgs.dimension, // array of ID/slug strings or undefined
  skip: parsedArgs.skip,           // array of ID/slug strings or undefined
  only: parsedArgs.only,           // array of ID/slug strings or undefined
};

Call `audit-dimensions.js` `resolveDimensions(config, cliFlags)` to compute the active dimension set.

Display the resolution summary:

Preset: {preset} ({N} base dimensions)
Active dimensions: {N} ({breakdown by category, e.g., "SI: 15, IH: 10, EF: 7, WC: 12"})

If `--dimension` or `--skip` was used, also display:

Adjustments: +{added} -{removed}

Store the resolved dimension list for use in Step 4.

---

Step 2 — Discover Session Logs

Session JSONL files live at:

~/.claude/projects/{encoded-project-path}/*.jsonl

Where `{encoded-project-path}` encodes the project directory path (e.g., `D:\Repos\plan-build-run` → `D--Repos-plan-build-run`).

**CRITICAL**: Determine the correct encoded path for the current project by listing `~/.claude/projects/` and finding the directory that matches.

Use Bash to find sessions in the audit window:

find ~/.claude/projects/{encoded-path}/ -name "*.jsonl" -maxdepth 1 \
  -newermt "{from_datetime}" ! -newermt "{to_datetime}" | sort

**CRITICAL — Exclude Current Session**: Before proceeding, determine the current session ID:

1. The current session's JSONL file is the most recently modified `.jsonl` in the project directory that is actively being written to (i.e., THIS session) 2. Identify it by checking which session file has been modified within the last 60 seconds: `find ~/.claude/projects/{encoded-path}/ -name "*.jsonl" -maxdepth 1 -mmin -1 2>/dev/null` 3. Remove the current session from the discovered sessions list 4. Display: `Excluding current session {id} from analysis (self-referential)` 5. If no sessions remain after exclusion, show the "no sessions found" error

For each session file found, also check for subagent logs:

ls ~/.claude/projects/{encoded-path}/{session-id}/subagents/*.jsonl 2>/dev/null

Display discovery results:

Found {N} sessions in audit window:
  {session-id-1} ({size}, {date})
  {session-id-2} ({size}, {date})
  ...

If no sessions found, display an error and exit:

╔══════════════════════════════════════════════════════════════╗
║  ERROR                                                       ║
╚══════════════════════════════════════════════════════════════╝

No session logs found between {from} and {to}.
Check: ~/.claude/projects/{encoded-path}/

---