/audit-fix

name: audit-fix
description: "Run audit, prioritize findings, auto-fix via quick tasks, test, and commit."
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Task, AskUserQuestion
argument-hint: "[--max N] [--severity high|medium|all] [--dry-run] [--from DATE] [--to DATE] [--today]"

**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.**

/pbr:audit-fix -- Autonomous Audit-to-Fix Pipeline

You are running the **audit-fix** skill. Your job is to run a session audit, parse findings, classify which are auto-fixable, and spawn executor agents to fix them one-by-one with atomic commits. The pipeline stops on the first test failure.

This skill **chains audit -> prioritize -> fix -> test -> commit** in a single command.

---

Step 0 -- Immediate Output

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

+--------------------------------------------------------------+
|  PLAN-BUILD-RUN > AUDIT-FIX                                  |
+--------------------------------------------------------------+

Then proceed to Step 1.

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 code changes** to executor subagents -- do NOT make fixes yourself
• Main context handles: argument parsing, audit orchestration, finding classification, executor dispatch, reporting
• Read only the audit report findings section, not full session details
• Target: main context stays under 25% utilization

---

Step 1 -- Parse Arguments

Parse `$ARGUMENTS` for:

| Argument | Default | Description | |----------|---------|-------------| | `--max N` | 5 | Maximum number of findings to fix | | `--severity LEVEL` | `medium` | Minimum severity threshold: `high` = Critical+High only, `medium` = +Medium, `all` = +Low | | `--dry-run` | false | List fixable findings without executing fixes | | `--from DATE` | Start of today | Passed through to audit agent | | `--to DATE` | Now | Passed through to audit agent | | `--today` | true (default) | Shorthand for today's audit window |

If no date arguments provided, default to `--today`.

Display:

Max fixes: {N}
Severity threshold: {level}
Mode: {dry-run or execute}

---

Step 2 -- Run Audit

Spawn a `Task(subagent_type: "pbr:audit")` to collect findings:

Task({
  subagent_type: "pbr:audit",
  prompt: "Run a full audit for this project.
    Date range: {from} to {to} (or --today)
    Mode: full

    Write the audit report to .planning/audits/ as usual.
    CRITICAL: Include a ## Consolidated Findings section with findings
    categorized by severity (Critical, High, Medium, Low).
    Each finding must have an ID (e.g., H1, M3), description, and evidence.

    Output: ## AUDIT COMPLETE when done."
})

After the audit agent completes, check for `## AUDIT COMPLETE`. If absent, warn and attempt to read any partial report.

Read the latest audit report from `.planning/audits/` (glob for the most recent `*-session-audit.md` or `*-consolidated-audit.md`).

---

Step 3 -- Parse Findings

Read the audit report's `## Consolidated Findings` section. Extract findings by severity:

• **Critical**: Workflow bypassed, hooks not firing, security issues
• **High**: State files not consulted, missing artifacts, broken paths
• **Medium**: Suboptimal flow, missing feedback, config drift
• **Low**: Minor ceremony issues, informational

Build a list of findings at or above the severity threshold (`--severity` flag).

---

Step 4 -- Classify Fixability

For each finding at or above the severity threshold, classify as:

• **auto-fixable**: Clear mechanical remediation exists. Examples:
• Missing fields in frontmatter
• Broken file paths or stale references
• Lint errors or formatting issues
• Config drift (value doesn't match expected)
• Uncommitted planning doc changes
• Missing command registrations
• Incorrect counts in test assertions

• **manual-only**: Requires human judgment. Examples:
• Architectural decisions needed
• User input or design choices required
• Ambiguous or context-dependent fixes
• Multi-system coordination needed
• Performance tuning with tradeoffs

Display a classification table:

Findings at severity >= {threshold}: {N}
Auto-fixable: {N}
Manual-only (skipped): {N}

Auto-fixable findings:
  {ID}: {description} [severity]
  ...

Manual-only findings (skipped):
  {ID}: {description} [severity] -- {reason}
  ...

If `--dry-run` flag is set: display the full classification table and STOP. Do not execute any fixes.

+--------------------------------------------------------------+
|  PLAN-BUILD-RUN > AUDIT-FIX DRY RUN COMPLETE                 |
+--------------------------------------------------------------+

{classification table above}

To execute fixes, run: /pbr:audit-fix --max {N}

---

Step 5 -- Execute Fixes

**Scope guard (CRITICAL):**

• Only fix findings with clear, mechanical remediation
• NEVER attempt fixes requiring architectural decisions
• NEVER attempt fixes requiring user input or design choices
• STOP on first test failure

For each auto-fixable finding (up to `--max`), ordered by severity (Critical first, then High, Medium, Low):

a. Display: `[{i}/{total}] Fixing {ID}: {description}`

b. Spawn `Task(subagent_type: "pbr:executor")` with a prompt describing the fix:

Task({
  subagent_type: "pbr:executor",
  prompt: "You are executor. Fix this audit finding.

    <files_to_read>
    CRITICAL: Read these files BEFORE any other action:
    1. CLAUDE.md -- project instructions
    </files_to_read>

    Finding ID: {ID}
    Severity: {severity}
    Description: {description}
    Evidence: {evidence from audit report}