audit-vs-fix-discipline

Files (1)

• SKILL.md

SKILL.md (first lines)

<!-- Last updated: 2026-05-19T12:00+10:00 -->

# Audit vs fix discipline

**Audits produce findings. Fixes happen separately, on explicit user request.**

Violating the letter of this rule violates the spirit. "Just one quick fix while I'm here" is the failure mode this skill exists to prevent.

## Triggers — apply this skill when the user says

`audit`, `review`, `investigate`, `check`, `scan`, `look at`, `look over`, `go through`, `inspect`, `find issues in`, `what's wrong with`, `how's the X looking`, `is the X any good`, `tell me about the X`.

If the request contains BOTH a diagnostic verb AND an explicit fix verb (`audit and fix`, `review and clean up`, `find and fix`), the user has authorised fixes — discipline does not apply; proceed normally.

## The discipline

While in audit mode you MUST:

1. **Use read-only tools only.** Read, Grep, Glob, Bash for read-only commands. NO Edit, Write, or mutating Bash. Sub-agents you dispatch inherit this constraint — say so in the prompt.
2. **Produce tiered findings.** Every finding gets a severity label:
	- **P0** — broken behaviour, security, data loss, build/test failures.
	- **P1** — correctness risk, performance, missing types, dead code with side effects.
	- **P2** — style, naming, nits, harmless dead code.
3. **Cite `file:line` for every finding.** No findings without locations.
4. **Separate findings from suggestions.** Refactor proposals ("split this into 5 files") are a separate section labelled "Suggested follow-ups" — NOT mixed into findings.
5. **End with an explicit ask.** `Want me to fix any of these? Specify by number, severity tier, or "fix all P0".` Then stop.

## Calibration

A clean audit is a valid outcome. Empty tiers are signal — `P0: none` is fine, and you must NEVER manufacture findings to fill them. The primary failure mode of LLM reviewers is inventing issues to seem thorough; it erodes trust and wastes the user's time more than missing a real finding does.

**Confidence gate: ≥80% sure it's a real problem, or drop it.** If the only reason you're flagging something is "it might be an issue", that's the failure mode the user reads as "inventing issues". Speculation belongs in `Suggested follow-ups`, not in a tiered finding.

**Pre-report 4-question check.** Before adding any finding to a tier, answer:

1. Can I cite the exact `file:line`?
2. Can I describe the concrete failure mode (what input + state produces what wrong outcome)?
3. Have I read enough surrounding context (callers, imports, related tests) to be sure?
4. Is the severity defensible — P0 = broken/exploitable now, P1 = correctness/perf risk under realistic conditions, P2 = a nit a senior would mention casually?

If any answer is "no" → drop the finding or downgrade to a follow-up suggestion.

**Pre-filtered exclusion list — do NOT flag:**

- "Consider adding error handling" when the framework or callers already handle it
- "Magic numbers" for well-known constants (HTTP 200/404, port 80/443, 60 for seconds, 1024 for KiB)
- "Missing JSDoc / comments" on self-describing helpers
- "Function too long" for switch tables, test fixtures, or data-shape declarations
- "N+1 queries" on fixed-cardinality loops or with batching already in place
- "Math.random()" in non-cryptographic contexts
- "Null dereference" where TS narrowing or type guards exist
- Style preferences unless the project explicitly enforces them
- Issues a linter would already catch (out of audit scope unless asked)
- Speculative "this could be cleaner" without a concrete failure mode

Apply this exclusion list before running the 4-question check.

**Counterintuitive caveat (research):** elaborate review prompts INCREASE false positives. Don't enumerate every potential mismatch, don't ask for long rationales — that pressure biases toward over-criticism. Stay terse, gate hard, drop liberally.

## Forbidden during audit

- Editing any file. Even "obvious" typos.
- Running `git add`, `git commit`, or any state-changing git command.
- Bundling fixes into the audit report ("I've fixed the P0s and listed the rest…").
- Saying a finding is **"pre-existing"**, **"unrelated"**, **"out of scope"**, or **"not worth fixing"** as a way to skip it. Report it at the appropriate tier and let the user decide.

## Rationalisation table

| Excuse | Reality |
|---|---|
| "It's a one-line fix, faster to just do it." | The user can read a one-line fix from a finding. The cost is consistency, not keystrokes. |
| "Critical security bug — has to be fixed now." | Report it as P0 with the proposed fix in the body. User decides timing. |
| "Lint errors are pre-existing, not part of this audit." | If you see them, report them at P1. The user asked you to audit — that includes whatever you find. |
| "The user clearly meant to fix it." | If they meant fix, they'd say fix. Ambiguous prompts default to audit mode. |
| "I'll just fix the trivial ones and report the rest." | This is the most common violation. Don't. |
| "I'll batch the audit and the fixes into one response to save round-trips." | Round-trips are the point. The audit is a checkpoint for scope. |
| "The diff is small enough that the audit + fix is one logical change." | The audit is the deliverable. The fix is a separate deliverable. |
| "I should fill in P1/P2 to look thorough." | Empty tiers are valid signal. "P0: none" is a correct result. Manufactured findings erode trust. |
| "It might be an issue, I'll flag it just in case." | If you're <80% sure, drop it. Speculation belongs in Suggested follow-ups, not findings. |

## Red flags — STOP and re-anchor

- About to call `Edit` or `Write` during an audit.
- About to type "I've gone ahead and…" or "while I was at it…".
- About to call something "pre-existing" or "out of scope" without naming it.
- About to add a "Suggested split" or refactor proposal in the same list as the findings.
- About to skip the "Want me to fix any of these?" closer.
- About to add a finding because a tier "looks empty".
- About to flag something with "could be cleaner" / "might want to consider" but no concrete failure mode.

**Each of these means: STOP. Go back to findings-only mode.**

## Output template

```
## Audit: <scope> — <criteria>

### P0 (blocking)
- `path/to/file.ts:42` — <one-line finding>. <one-sentence why it matters>.

### P1 (quality / correctness risk)
- `path/to/file.ts:88` — ...

### P2 (nits)
- `path/to/file.ts:120` — ...

### Suggested follow-ups (not findings)
- Optional: bigger refactor ideas surfaced by the audit, clearly separated.

---
Want me to fix any of these? Specify by number, by tier ("fix all P0"), or by file.
```

If a tier is empty, say "P0: none" — don't omit the header. Empty headers are signal.

## When NOT to use

- User explicitly authorises fixes: "audit and fix", "find and clean up", "review and patch".
- User has set context like "we're in fix mode" earlier in the session.

From stuartshields/claude-setup, MIT.

More from stuartshields/claude-setup