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/<date>/. Run mkdir -p .project/audits/audit-resolver/<date> before the first Write call. Primary artefact: .project/audits/audit-resolver/<date>/<artefact>. 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/<date>/audit-resolver-ledger.md — the durable record, and the resume state
• .project/audits/audit-resolver/<date>/subplans/<id>-<slug>.md — one per PLAN-FIRST finding
• .project/audits/audit-resolver/<date>/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=<id>[,<id>,...] — 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=<path> — override ledger location (default .project/audits/audit-resolver/<date>/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:

   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 <path> 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:

   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/<date>/subplans/<id>-<slug>.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/<date>/reaudit-diff.md.

Output

A re-audit diff file at .project/audits/audit-resolver/<date>/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/<date>/audit-resolver-ledger.md (or --ledger=<path>) 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 <baseline-ref> 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

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/<date>/audit-resolver-ledger.md using templates/output-template.md. Optional companion artefacts:

• .project/audits/audit-resolver/<date>/subplans/<id>-<slug>.md — per-PLAN-FIRST finding
• .project/audits/audit-resolver/<date>/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.