config-audit/commands/fix.md

name	description	argument-hint	allowed-tools	model
config-audit:fix	Auto-fix deterministic configuration issues with backup and verification	[path] [--dry-run]	Read, Write, Glob, Grep, Bash, AskUserQuestion	sonnet

Config-Audit: Fix

Auto-fix deterministic configuration issues. Scans, plans fixes, backs up originals, applies changes, and verifies results.

Arguments

• $ARGUMENTS may contain:
  • A target path (default: current working directory)
  • --dry-run: Show fix plan without applying
  • --global: Include user-scope config (~/.claude) in the scan and the fix run
  • --raw: Pass-through to scanners; produces v5.0.0 verbatim envelope (bypasses the humanizer) for byte-stable diff tooling

--global must be passed to every step below. The scan that builds the table and the scan that plans the fixes are two different runs; if only one of them sees the user scope, the plan and the table describe different config.

Implementation

Step 1: Greet and scan

Tell the user:

## Config-Audit Fix

Scanning for auto-fixable issues...

Parse flags and run scanners silently. Default mode emits humanized JSON — each finding carries userImpactCategory, userActionLanguage, and relevanceContext alongside the v5.0.0 fields:

RAW_FLAG=""
if echo "$ARGUMENTS" | grep -q -- "--raw"; then RAW_FLAG="--raw"; fi
# Set to --global when the user asked for global scope, otherwise leave empty.
# A placeholder in square brackets does not start with a dash, so the arg loop
# would take it as the scan/fix TARGET instead of a flag.
GLOBAL_FLAG=""
node ${CLAUDE_PLUGIN_ROOT}/scanners/scan-orchestrator.mjs <path> --output-file /tmp/config-audit-fix-scan.json $GLOBAL_FLAG $RAW_FLAG 2>/dev/null; echo $?

Exit code 3 → tell user: "Scanner error. Try /config-audit posture to check your configuration."

Step 2: Plan fixes

Run fix planner silently. The fix-cli emits humanized prose to stderr in default mode and v5.0.0-shape JSON to stdout when --json is set; we use --json here for structured data and let the humanizer-aware rendering layer (this command's prose output below) supply the plain-language wording from the scan envelope above:

# Re-assign here: each fenced block is its own Bash call, so the value
# set in Step 1 is empty by the time this block runs.
GLOBAL_FLAG=""          # --global when the user asked for global scope
node ${CLAUDE_PLUGIN_ROOT}/scanners/fix-cli.mjs <path> $GLOBAL_FLAG --output-file /tmp/config-audit-fix-plan.json 2>/dev/null; echo $?

Exit codes: 0 = plan produced, 2 = one or more fixes failed (apply step only), 3 = argument or tool error. On 3, show the stderr message — an unknown flag is rejected by design, not silently ignored.

Read /tmp/config-audit-fix-plan.json using the Read tool. Cross-reference each fix-plan entry against the humanized scan envelope (/tmp/config-audit-fix-scan.json) by finding ID to recover the humanized title/description/recommendation plus userImpactCategory/userActionLanguage for grouping.

Step 3: Present fix plan

Show what will be fixed and what needs manual attention. Group by userActionLanguage so the urgency phrasing stays consistent with the rest of the toolchain:

### Fix Plan

**Auto-fixable ({N} issues), grouped by impact:**

{For each userActionLanguage bucket in priority order — "Fix this now" → "Fix soon" → "Fix when convenient" → "Optional cleanup" → "FYI":}

#### {userActionLanguage}

| # | ID | Issue | File |
|---|-----|-------|------|
| 1 | {id} | {humanized title} | {file} |

**Manual ({M} issues — require human judgment), grouped by impact:**

{Same userActionLanguage grouping. Render humanized title and recommendation verbatim — the humanizer already produced plain-language strings, do not paraphrase.}

| # | ID | Issue | Recommendation |
|---|-----|-------|----------------|
| 1 | {id} | {humanized title} | {humanized recommendation} |

Step 4: Confirm with user

If not --dry-run, ask for confirmation:

AskUserQuestion:
  question: "Apply {N} auto-fixes? A backup is created first — you can roll back anytime."
  options:
    - "Yes, apply fixes"
    - "Show dry-run only"
    - "Cancel"

Step 5: Apply fixes

If confirmed, apply:

# Re-assign here: each fenced block is its own Bash call, so the value
# set in Step 1 is empty by the time this block runs.
GLOBAL_FLAG=""          # --global when the user asked for global scope
node ${CLAUDE_PLUGIN_ROOT}/scanners/fix-cli.mjs <path> --apply $GLOBAL_FLAG --output-file /tmp/config-audit-fix-applied.json 2>/dev/null; echo $?

Read /tmp/config-audit-fix-applied.json with the Read tool to get applied/failed counts and the backup ID. Exit code 2 means at least one fix failed — report it; failed[] carries the reason per fix.

Step 6: Show results

Run a quick posture check to measure improvement:

node ${CLAUDE_PLUGIN_ROOT}/scanners/posture.mjs <path> --json --output-file /tmp/config-audit-fix-posture-$$.json 2>/dev/null

Present results:

### Results

**{applied} fixed** | {failed} failed | Backup created

{If grade improved:}
Score impact: {old_grade} ({old_score}) → {new_grade} ({new_score}) — **+{delta} points**

{If failed > 0:}
{failed} fix(es) couldn't be applied — run `/config-audit plan` for alternative approaches.

**Rollback:** If anything looks wrong, run `/config-audit rollback {backup-id}` to restore.

Step 7: Manual findings

If manual findings exist:

### Needs manual attention

These {M} issues require human judgment:

1. **{title}** ({id}) — {recommendation}
2. ...

Run `/config-audit plan` to get a step-by-step guide for addressing these.

Safety

• Backup is mandatory — every fix creates a backup first, including file renames (the source file is backed up before the rename, so rollback can restore it at its original path)
• Dry-run by default — user must confirm before changes
• Verify after fix — re-scans in the same scope the fix run used, so a --global run is verified against user scope too
• Rollback always available — /config-audit rollback <backup-id>
• A failed fix is reported, never swallowed — exit 2 plus a failed[] entry