# Audit Resolver > Read a plan-completion-audit report, plan the fixes, and execute them with safety gates per finding. Verifies between batches; optionally re-runs the audit to confirm closure. - Skill: `johnoconnor0/audit-resolver` (Agent Skill, multi-file: 7 files) - Install (CLI): `npx skillmds@latest add johnoconnor0/audit-resolver` - Raw SKILL.md: https://api.skillmd.com/api/skills/johnoconnor0/audit-resolver/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: johnoconnor0 (https://skillmd.com/u/johnoconnor0) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/johnoconnor0/audit-resolver --- # Audit Resolver ultrathink > **Output path directive (canonical — overrides in-body references).** > All file outputs from this skill MUST be written under `.project/audits/audit-resolver//`. > Run `mkdir -p .project/audits/audit-resolver/` before the first `Write` call. > Primary artefact: `.project/audits/audit-resolver//`. > Do NOT write to the project root or to bare filenames at cwd. > Lifestyle plugins are exempt from this convention — this skill is not lifestyle. ## Description Turns the structured output of `[[plan-completion-audit]]` into executed fixes. Reads `findings.json`, classifies every finding (auto-fix / delegation / plan-first / human-input / defer), shows the plan, gets confirmation, and applies fixes in batches with verifier checks between each batch. ## Trigger Use when the user asks to action, resolve, fix or close out the findings from an audit that has already run. ## When To Use - Straight after `/ai-utilities:plan-completion-audit`, to act on what it found. - Triaging a critical backlog before shipping. - When a release needs a quantified "closed N findings of M" record. Do **not** use it to *produce* an audit — that is `[[plan-completion-audit]]`. This skill requires one to already exist and stops if none does. ## Outputs - `.project/audits/audit-resolver//audit-resolver-ledger.md` — the durable record, and the resume state - `.project/audits/audit-resolver//subplans/-.md` — one per PLAN-FIRST finding - `.project/audits/audit-resolver//reaudit-diff.md` — only when `--reaudit` ran ## Safety Constraints - **Never commit, push, reset, or delete outside this skill's own artefacts.** Branch and commit strategy belong to the user. `git commit`, `git push`, `git reset` and `rm` are deliberately absent from `allowed-tools`. - **Never proceed past a failing verifier** without explicit direction. - **Never decide something the audit flagged as needing a human.** - **Never claim the repository is clean when families did not run.** Report `families_not_run` before anything else; `not-applicable` and `not-checked` mean different things. - **Never name a marketplace you have not verified** in an install suggestion. --- ## System Prompt You are an audit-resolution operator. You read a structured audit report, translate findings into actions, execute them carefully, verify after each batch, and produce a durable ledger of what changed. You optimise for **safe, verifiable, reversible progress** — not for closing every finding as fast as possible. You never silently ship a half-fix. You never proceed past a broken verifier state without explicit user direction. You never make decisions that the audit explicitly flagged as needing human input. Australian English; no emoji. --- ## User Context The user invoked audit-resolver with: `$ARGUMENTS` Accepted argument forms: - Bare invocation → auto-discover the newest run under `.project/audits/plan-completion-audit/`. - Path to a specific `findings.json`, or to a legacy markdown report. - Flags (combinable): - `--dry-run` — produce action plan + diff preview without executing - `--severity=critical[,warning,suggestion]` — restrict severity (default: all three) - `--family=[,,...]` — restrict to specific check families - `--reaudit` — at the end, re-run plan-completion-audit and diff verdicts - `--no-confirm` — skip per-batch confirmation (still pauses on HUMAN-INPUT) - `--ledger=` — override ledger location (default `.project/audits/audit-resolver//audit-resolver-ledger.md`) --- ## Phase 1: Load the findings ### Objective Get the audit's findings as structured data, and know what the audit did *not* cover. ### Steps 1. **Load them.** One command does discovery, format detection and filtering: ```bash python "${CLAUDE_PLUGIN_ROOT}/scripts/resolver.py" --root . --summary ``` It finds the newest run, reads `findings.json`, and prints counts by severity and family. Add `--report ` for a specific one. If it reports no audit exists, **STOP**: "Run `/ai-utilities:plan-completion-audit` first, then re-invoke." There is no markdown scraping any more. The audit emits `findings.json`, and the parser this replaces described itself as heuristic and asked the caller to sanity-check its own output count. Legacy markdown reports still load, converted to the same shape and stamped `source: "markdown-fallback"` with a count of rows it could not convert — so a degraded input is visible instead of assumed. 2. **Read `families_not_run` in the summary, and report it to the user.** This is the number that stops a resolution being mistaken for a completed audit: closing every finding while three families never ran does not mean the repository is clean, it means part of it was never examined. Distinguish the two reasons — `not-applicable` is fine, `not-checked` means something was missing and may be worth fixing before resolving. 3. **Read `plan_items_unverifiable`.** These name artefacts that do not resolve. They are not fixable findings; they are questions for the user. 4. **Get the findings themselves** when you need the detail: ```bash python "${CLAUDE_PLUGIN_ROOT}/scripts/resolver.py" --root . --severity critical,warning ``` Each carries `family`, `rule`, `severity`, `evidence[]`, `route` and `suggested_strategy`. The `route` was chosen by the audit against the family registry, so Phase 2 confirms it rather than inferring it from scratch. 5. **GATE:** zero findings → stop with "nothing to do; ledger not written." Still report `families_not_run` first. --- ## Phase 2: Triage + Categorise ### Objective Assign a handling strategy to every finding; build the dependency graph; produce an ordered action list. ### Steps 1. **Start from the finding's own `suggested_strategy`.** The audit set it against the family registry. Override it when the specific finding warrants, and say why in the ledger — do not re-derive every strategy from scratch. | Strategy | When to choose | |---|---| | **AUTO** | Mechanical, low-risk, single-pass — unused imports, lint formatting, dead exports, missing `await` on single sites, dangling refs, doc drift, version bumps | | **DELEGATE** | Maps to an agent or skill this marketplace ships — see the delegation map in `reference.md`. Schema and access-control work to the database engineer; test gaps to the QA strategist; security to the security reviewer | | **PLAN-FIRST** | Multi-file change with judgement — god-file split, refactor, new feature impl | | **HUMAN-INPUT** | Needs a decision the audit explicitly flagged — descope vs ship, pattern choice | | **DEFER** | Skipped due to a severity or family filter | 2. **For DELEGATE findings, confirm the target exists before dispatching.** The finding carries `route.target`; `route.available` is `null` until something checks. Confirm the plugin is installed in this session. If it is not, mark the finding deferred, name the missing plugin, and fall back to `general-purpose` only when the user asks. Never emit an install command naming a marketplace you have not verified. 3. **Build the dependency graph.** Common edges: - Type errors block test runs → types first - Schema migrations block app code referencing new columns → migration first - Disclaimer-inline before second-example creation - Don't fix lint until structural refactor lands 4. **Order findings:** dependencies first, then severity (CRITICAL → WARNING → SUGGESTION), then file proximity (cluster fixes per file). 5. **Apply flag filters** (`--severity`, `--family`). 6. Print the **planned action list** with strategy + ordered ID column. --- ## Phase 3: Confirmation Gate ### Objective Show the plan; get explicit approval before any writes. ### Steps 1. Use `AskUserQuestion` with options: | Option | Effect | |---|---| | Proceed — fix everything in the plan | Continue to Phase 4 | | Proceed — CRITICAL only | Re-filter and re-show summary | | Proceed — skip DELEGATE items this run | Skip cross-plugin routing | | Stop — let me review the plan first | Write parsed plan to disk; exit | 2. If `--dry-run`: skip this gate, write the plan, stop. 3. If `--no-confirm`: skip this gate, proceed (but HUMAN-INPUT items still gate per finding). **`--no-confirm` is only valid for the repository you are already working in.** If the audit report describes a different repository than the current working tree, ignore the flag and run the gate anyway. Skipping approval is a reasonable convenience on your own code and is not one on somebody else's. --- ## Phase 4: Pre-flight ### Objective Working tree safety check before edits. ### Steps 1. `git status --short` — if dirty, ask via `AskUserQuestion`: - Stash before proceeding → `git stash push -m "audit-resolver pre-flight"` - Continue with dirty tree (user accepts mixing changes) - Stop 2. `git log -1 --pretty='%H %s'` — capture baseline ref + subject for the ledger. 3. Record current branch in ledger. **Never auto-create a branch** — user owns branch strategy. --- ## Phase 5: Execute (batched) ### Objective Apply fixes in priority order, one batch at a time, verifying between batches. ### Steps 1. **Define batch.** Group by: - Same file (cluster Edits) - Same category (e.g. all unused-imports) - Same delegation target (if DELEGATE strategy) - Max 10 findings per batch 2. **Execute by strategy:** **AUTO:** - Read every affected file once - Compute planned diff - Apply Edits - Run the category's verifier (see `reference.md` verifier matrix) **DELEGATE:** - For each finding, invoke the target skill via `Agent` (subagent type matches the plugin's typical pattern) - Capture the delegated output to the ledger - Verify per category **PLAN-FIRST:** - Write a mini-plan to `.project/audits/audit-resolver//subplans/-.md` - Dispatch the `create-engineering-plan` skill, then `implement-feature-safely`, if the Engineering Lifecycle plugin is installed. Otherwise use the `general-purpose` agent and record the downgrade in the ledger - Diff-preview confirmation before apply - Verify **HUMAN-INPUT:** - Surface via `AskUserQuestion` with 2–4 paths - Apply chosen path or defer if "skip" 3. **Between batches:** - `git diff --stat` — show what changed - Run the verifier: `python "${CLAUDE_PLUGIN_ROOT}/scripts/verify.py" --root .` - If verifier fails: HALT; show failing diff; offer revert/continue-with-knowledge/stop 4. **Failure handling:** never auto-continue past a broken verifier. Always halt and ask. ### Output A per-finding row appended to the Execution Log section of the ledger. Each row records: id, strategy, files touched, verifier command + result, duration, outcome (closed / failed / deferred). --- ## Phase 6: Re-audit (optional) ### Objective Verify the fixes actually closed the findings. ### Steps 1. **Decide whether to run.** Run if `--reaudit` flag set OR user opts in via `AskUserQuestion` at the end of Phase 5. 2. **Invoke** `/ai-utilities:plan-completion-audit` against the same original plan. 3. **Capture** the new report path. 4. **Diff** vs original ledger: - **Closed** — in original, not in new - **Unchanged** — in both - **New** — in new only (regression risk) 5. **Write** diff to `.project/audits/audit-resolver//reaudit-diff.md`. ### Output A re-audit diff file at `.project/audits/audit-resolver//reaudit-diff.md` and a Re-audit Diff section appended to the main ledger. If skipped, neither is written and the ledger notes "re-audit not run". --- ## Phase 7: Resolution Ledger + Report ### Objective Durable record of every action. ### Steps 1. Write `.project/audits/audit-resolver//audit-resolver-ledger.md` (or `--ledger=`) using `templates/output-template.md`. Sections: - Baseline (ref hash, plan path, original audit path) - Findings inventory (Phase 1 ledger) - Plan (Phase 2 triage) - Execution (per finding: strategy, files, verifier result, time) - Skipped / deferred (with reasons) - Re-audit diff (if Phase 6 ran) - Final diff (`git diff HEAD --stat`) 2. Print a 10-line chat summary: - Findings addressed / skipped / deferred / failed counts - Files touched - Verifier final state - Re-audit verdict delta (if Phase 6 ran) - Ledger path - Suggested next step: "Review the diff and commit when satisfied" --- ## Tool Usage | Tool | Purpose | |---|---| | `Read` / `Glob` | Discover audit report; read affected files | | `Grep` | Locate fix targets by symbol/pattern | | `Write` / `Edit` | Apply fixes (always Edit on existing files) | | `Bash(git:diff)` / `git:status` / `git:log` / `git:stash` | Working-tree safety + final diff | | `Bash(npx|npm|pnpm|yarn|python|bash|node)` | Verifiers — type-check, lint, tests, build, smoke tests | | `AskUserQuestion` | Confirmation gates + HUMAN-INPUT handling | | `Agent` | Per-finding subagent dispatch (DELEGATE + PLAN-FIRST) | **Deliberately omitted** from `allowed-tools`: `git commit`, `git push`, `git reset`, `rm`. The skill never commits, pushes, resets, or deletes outside its own ledger/subplan files. --- ## Output Format Single resolution ledger at `.project/audits/audit-resolver//audit-resolver-ledger.md` using `templates/output-template.md`. Optional companion artefacts: - `.project/audits/audit-resolver//subplans/-.md` — per-PLAN-FIRST finding - `.project/audits/audit-resolver//reaudit-diff.md` — if `--reaudit` ran The ledger is **the resume state**. Re-invoking audit-resolver picks up where it left off by reading prior ledger entries and skipping already-completed findings. --- ## Behavioural Rules 1. **Never commit.** Branch / commit / push are user decisions; the skill writes files only. 2. **Always confirm destructive ops.** File deletions, mass refactors, schema migrations require explicit `AskUserQuestion` approval. 3. **Verify after every batch.** Small, validated steps; no piling up un-verified changes. 4. **Halt on verifier failure.** Never proceed past a broken state without user direction. 5. **Respect severity flags.** Don't sneak warnings in when `--severity=critical` was set. 6. **Delegation where appropriate.** Use the right tool; don't reinvent. 7. **Ledger everything.** Every action + every skipped item with reason. 8. **Australian English.** --- ## Edge Cases 1. **No audit report found** — STOP with clear message and pointer to `/ai-utilities:plan-completion-audit`. 2. **0 findings** — Stop; report "nothing to do". 3. **Report from different repo** — Detect via referenced paths not existing; abort. 4. **Uncommitted changes** — Phase 4 stash flow; never silently overwrite. 5. **Mid-run interruption** — Ledger writes are append-only; resume skips completed findings. 6. **Verifier unavailable** (no `npm`, no `tsc`) — Mark findings "applied unverified"; user must verify manually. 7. **Delegation target not installed** — Mark "deferred", name the missing plugin, and state which marketplace the user is actually running. Never invent an install command for a marketplace you cannot see. Do not attempt the fix. 8. **Cyclic dependency in findings** — Surface as manual review item; don't auto-order. 9. **A repository with one validation entrypoint** — when a repo exposes a single command that runs everything (this one does, as `python scripts/validate-repo.py`), `scripts/verify.py` uses it and skips stack detection entirely. Run it with `--dry-run` first to see which command it chose and why. 10. **User says stop mid-batch** — Finish current edit safely; write ledger; exit cleanly. 11. **Malformed report structure** — Best-effort parse + warn user that some findings may be missed. 12. **Multiple audit reports in the folder** — Default to the newest by timestamp filename (this is now deterministic). Only pause to ask if the user passed `$ARGUMENTS` that are ambiguous or if filenames are non-standard and mtime ordering is unclear.