# Multi-architect audit - adversarial quality gate for a skill

The [checklist](checklist.md) is the self-review floor. This is the **high-confidence
gate**: a panel of N independent reviewers, each a *distinct lens*, reads the skill
against the rubric + ground truth, then a synthesizer dedups and rules. You **loop
fix → re-audit until it passes** (no blockers/majors). Run it before shipping a new
or substantially-changed skill, or whenever a skill must be trusted.

Use the [Workflow tool](scripts/audit-panel.js) to fan the panel out - it returns
`{remaining, clearsBar, verdict}`.

## The loop (run to convergence)
1. **Panel** - N agents, one lens each, read-only. Each returns specific findings
   (severity · file:location · problem · concrete fix). Empty if its lens is clean.
2. **Synthesize** - dedup overlaps; **drop false positives** (verify each against the
   real files/repo before keeping); classify blocker / major / minor / nit;
   `clearsBar = no blockers and no majors remain`.
3. **If not clean** - apply the do-now set (blockers + majors + cheap high-value
   minors), then run a **fresh** panel (see "Fresh each round") and repeat.
4. **Stop** when `clearsBar` is true. The later/nit list is optional polish.

## Rules that make it trustworthy
- **Fresh panel each round.** After a fix, re-run the panel anew so agents read the
  *current* files - do not reuse a prior run's cached results (they reflect the old
  state and will report fixed issues as open / miss regressions).
- **Verify before keeping.** Every finding must be confirmed against the actual file
  or repo. The synthesizer drops anything it can't reproduce. Prefer findings that
  cite a line and a reproduction.
- **Ground-truth, not vibes.** Give the panel the rubric ([SKILL.md](SKILL.md) +
  [checklist.md](checklist.md)), an exemplar skill, and the real source the skill
  describes (e.g. the iOS repo). Agents read; they don't assume.
- **Watch for regressions.** A fix can break something - the red-team lens and the
  fresh re-audit exist to catch it (e.g. a broadened check that now false-positives).
- **clearsBar gates the merge.** Don't merge with an open blocker/major.

## Lenses - pick the set for the task
One distinct lens per agent (+ a synthesizer). Two ready-made sets:

**General skill audit** - discovery · leanness · shape/layer · scripts · accuracy-vs-source · domain-correctness · wiring · boundaries · red-team → synthesis.

**Prompt-engineering audit** (when the concern is *prompt quality* - descriptions,
instructions, triggering):
1. **description-as-discovery** - what + when + trigger words + example; would it activate on a real task?
2. **disambiguation** - distinct from siblings; a reader can tell when to pick this vs a neighbor.
3. **trigger coverage** - the real user phrasings (and synonyms) are covered.
4. **instruction clarity** - steps are unambiguous, ordered, single-interpretation; no vague directives.
5. **degrees of freedom / layer fit** - reference=descriptive (no numbered procedure), workflow=spine, tool=thin-index; freedom matches the task.
6. **progressive disclosure / leanness** - SKILL.md is an index; detail bundled one level deep; no duplication.
7. **token efficiency** - every line is load-bearing; nothing restates what the model already knows.
8. **consistency** - terminology, naming, paths, cross-references, examples all agree.
9. **anti-patterns / misfire** - would the model over-apply it, skip a gate, hallucinate a path, or follow it into a wrong output?
10. **red-team** - adversarially try to make it not trigger, trigger wrongly, or produce broken output; hunt overclaims (says X, the script doesn't).

Scale the panel to risk: a quick check is ~3 lenses; a thorough gate is ~10.

## Scope of fixes per round
Fix **blockers + majors** always; fold in **cheap, high-value minors** while you're
in the file. Defer speculative nits and pre-existing/out-of-scope drift to the
"later" list (and `log()`/note them - don't silently drop coverage).