| name | audit-fix-loop |
| description | Canonical doctrine for scored iterative improvement, and the generic fallback for ad-hoc 'iteratively improve / audit and fix / grade and improve / hill-climb quality / score and fix' requests that don't map to a domain workflow. |
| user-invocable | false |
Announce: "Using audit-fix-loop to plan a scored iterative improvement loop."
What this skill is (and isn't)
/goal is the mechanism: it re-fires turns and uses a separate-model evaluator to gate exit on a condition it reads from the transcript. This skill is the doctrine that tells you how to set a loop up so /goal enforces the right thing โ /goal will just as happily enforce a wrong condition.
It is also the generic fallback. The domain workflows below are specialized, pre-wired instances of this same doctrine โ prefer them when one fits. Use this skill directly only for ad-hoc "improve " requests that don't map to any of them:
| Domain workflow | Use it instead whenโฆ |
|---|
| visual-verify | improving slides/charts/rendered output (Gemini vision, zero-blocking-defects gate) |
| bluebook-audit | correcting Bluebook citations in a DOCX |
| source-verify | verifying citations exist + quotes match sources |
| writing-verify / writing-revise | improving a prose draft |
| workflow-creator Mode 3 | hardening a skill/workflow (workflow-creator-verify substrate gate) |
## Iron Law 1 โ The auditor must not be the fixer
This is the one thing /goal cannot supply. /goal decides when to exit; it does not enforce that the score came from someone other than the fixer. If the agent that wrote the fix also grades it, you get rubber-stamping โ the fixer's opinion of its own work is worthless.
The audit must be structurally independent every iteration: a fresh subagent (no fixer context), a different model (e.g. Gemini), or a mechanical checker. If you ran an audit with the fixer's context, DELETE the result and re-run with a fresh auditor โ tainted findings are worse than none.
## Iron Law 2 โ Gate on the substrate, not on a bare score
Terminate on the deterministic/categorical substrate going clean + the 0-10 score going FLAT โ never on a bare "composite โฅ 9.5".
The substrate is the convergent signal: zero CRITICAL and zero HIGH findings outstanding (and, where the domain has them, mechanical gates pass / citations resolve / zero blocking defects). It monotonically converges and is what "done" actually means.
The 0-10 score is a noisy LLM proxy: it re-rolls ยฑ0.2 each run and regenerates fresh minor findings every pass, so it asymptotes (empirically ~9.0) and never stably crosses 9.5. Chasing it is a treadmill where every fix surfaces a new nit and the last half-point is only buyable by over-engineering the artifact โ which makes it worse. (See project_wc_mode3_asymptote.) Treat the score as an advisory thermometer and a flatness check, not the summit.
So the exit condition is: substrate clean AND score flat (within ยฑ0.2 of the prior turn, at/above your chosen floor) โ or the turn budget elapses. The threshold you pick in Step 1 is a floor the substrate must clear, not a bar to grind toward. For a pure-judgment scorer with no hard substrate (e.g. prose rhythm), gate on convergence/flat + zero blocking alone โ there is no threshold to chase.
## Iron Law 3 โ No `/goal` without a plan
A naive condition like "fix all issues" gives the evaluator nothing concrete to check. Before setting the /goal, identify: (1) the artifact, (2) the scoring surfaces, (3) how the audit stays independent, (4) the substrate gate + score floor. The condition MUST pin completion to external state the auditor writes โ .planning/SCORES.md (score trend + finding counts) โ so the evaluator reads the substrate and the flatness from the transcript, not from your say-so.
If you set a /goal without planning, run /goal clear, plan via Step 1, and set a new one. No patching a naive condition mid-flight.
The loop
PLAN (Step 1) โ /goal <substrate-gate condition pinned to .planning/SCORES.md>
โ
โโโบ each turn the evaluator re-fires:
AUDIT fresh independent auditor scores the artifact
โ findings โ .planning/AUDIT.md ; score + CRITICAL/HIGH counts โ .planning/SCORES.md
DECIDE substrate clean (0 CRITICAL/0 HIGH) AND score flat? โ end turn; evaluator marks done
substrate dirty, OR score still climbing run-to-run? โ FIX
FIX apply targeted fixes worst-severity-first (CRITICAL โ HIGH โ MEDIUM); do NOT self-assess
โ end turn immediately (the /goal refires for re-audit)
/goal owns the re-firing and the exit decision. You own AUDIT โ DECIDE โ FIX inside each turn. After fixing, do not pause to summarize or ask "should I continue?" โ end the turn so the goal refires. The evaluator decides when to stop, not you.
Step 1: Plan the loop
AskUserQuestion(questions=[
{"question": "What artifact are you improving?", "header": "Artifact", "multiSelect": false,
"options": [
{"label": "Writing draft", "description": "Document, essay, paper, or prose"},
{"label": "Skill or workflow", "description": "SKILL.md / workflow being hardened โ prefer workflow-creator Mode 3"},
{"label": "Visual output", "description": "Slides/charts/rendered docs โ use visual-verify instead"},
{"label": "Citations", "description": "Footnotes / quotes โ use bluebook-audit or source-verify instead"}]},
{"question": "Which scoring surfaces should the audit use?", "header": "Scorers", "multiSelect": true,
"options": [
{"label": "AI anti-patterns", "description": "12-category checklist for AI writing indicators"},
{"label": "Style guide", "description": "Legal / econ / Strunk & White"},
{"label": "Enforcement patterns", "description": "12 superpowers enforcement patterns (skills/workflows)"},
{"label": "Source verification", "description": "Citations vs bib + quotes vs sources โ use source-verify"}]}
])
Redirect to the domain workflow if the artifact is visual / citations / a skill โ they already implement this pattern, calibrated.
Derive the parameters:
| Parameter | How to derive |
|---|
| Audit method | Fresh subagent reads the scorer's rules (see table), then audits โ independence per Iron Law 1 |
| Fix method | Self-edit for small artifacts; parallel subagents for large ones |
| Turn budget | 10 default, encoded as Stop after N turns |
| Substrate gate | 0 CRITICAL / 0 HIGH (+ any domain mechanical/categorical gates) |
| Score floor | 9.5/10 default โ a floor the substrate must clear, NOT a bar to grind |
| Scorer | Audit method (independence mechanism) |
|---|
| AI anti-patterns | fresh subagent reads ../ai-anti-patterns/SKILL.md + refs, then audits |
| Style guide | fresh subagent reads the domain skill (writing-legal / -econ / -general), then audits |
| Enforcement patterns | fresh subagent reads references/enforcement-checklist.md, scores all 12 |
| Source verification | invoke Skill(skill="workflows:source-verify") โ mechanical bib grep + quote search |
When multiple scorers are selected, every iteration runs ALL of them and the substrate is the union of their CRITICAL/HIGH findings.
Step 2: Initialize state files
mkdir -p .planning
.planning/AUDIT.md (overwritten each iteration) โ findings table per scorer: # | Severity | Finding | Location | Suggestion (severities CRITICAL/HIGH/MEDIUM/LOW).
.planning/SCORES.md (append-only) โ one row per iteration so the evaluator can read both the substrate and the trend:
# Score History
| Iteration | Score | CRITICAL | HIGH | ฮ vs prior | Note |
|-----------|-------|----------|------|-----------|------|
| 1 | 6.5 | 3 | 2 | โ | baseline |
| 2 | 8.9 | 0 | 0 | +2.4 | substrate clean; not yet flat |
| 3 | 9.0 | 0 | 0 | +0.1 | substrate clean + flat โ done |
Step 3: Set the /goal
Pin the condition to the substrate (CRITICAL/HIGH counts) and score-flatness in .planning/SCORES.md:
/goal The artifact is substrate-clean โ zero CRITICAL and zero HIGH findings outstanding in
.planning/SCORES.md across the selected scorers โ AND its score has gone flat (within ยฑ0.2 of the
prior turn, at or above the floor). Audit with a fresh independent auditor, then fix worst-first,
each turn. Stop after 10 turns. Do NOT keep iterating to lift a flat score once substrate-clean.
The fresh-auditor prompt (Phase A, every turn):
Agent(prompt="""
You are an independent auditor with NO knowledge of any prior fixes.
Read the scoring rules: [SCORER SKILL PATH]
Then audit this artifact: [ARTIFACT PATH]
Output findings EXACTLY as: | # | Severity | Finding | Location | Suggestion |
Severities: CRITICAL, HIGH, MEDIUM, LOW. Be thorough โ a clean audit that misses issues is worse
than a harsh one. Do NOT soften findings. Do NOT say "overall good." Then give a 0-10 score.
""", subagent_type="general-purpose", run_in_background=false)
# Blocking: DECIDE -> FIX consumes this audit. A backgrounded auditor returns a completion
# notification, not findings.
Compile into .planning/AUDIT.md, append the row to .planning/SCORES.md, then DECIDE โ FIX โ end turn.
Loop Facts
- A CRITICAL caused by a measurement artifact still keeps the substrate dirty. Verify it against the real files, then either fix it or neutralize the artifact โ waiving it informally ("it's just an artifact") converts the gate back into the honor system, which is claiming the gate without checking it.
- A flat score below the floor with a clean substrate is the domain ceiling / judge noise, not a defect โ record the number as the honest reading and stop. Grinding a flat score toward 9.5 over-engineers the artifact and makes it worse (Iron Law 2).
