# Multi-architect audit

The checklist is what one author catches alone. The audit adds a panel of independent, read-only reviewers, each looking through one lens, and a synthesizer that turns their output into a decision. New skills and substantial changes go through it before merge.

## The loop

1. **Panel.** Every lens reviews the skill and returns findings, each with a severity, a `file:location`, the problem and a concrete fix. A clean lens returns an empty list.
2. **Synthesis.** One agent merges duplicates, opens the real files to discard false positives, classifies the rest as blocker, major, minor or nit, and sets `clearsBar` to true only when no blocker and no major is left.
3. **Fix.** If the bar is not cleared, apply the do-now set and start a **new** panel.
4. **Stop** once `clearsBar` is true. Remaining nits are optional polish.

### What to fix in a round

- Always: every blocker and every major.
- Also, when cheap and clearly valuable: minors.
- Later, on a written list: speculative nits and drift that was already there or sits outside this change. Record them; never drop them silently.

## Rules that keep the result trustworthy

- **Fresh panel every round.** Cached results describe the files as they were; a resumed run audits the old version.
- **Verify before keeping.** Each finding is checked against the file before it counts. Prefer findings that cite a line and a way to reproduce.
- **Give the panel ground truth:** the rubric (skill-creator SKILL.md plus checklist.md), an exemplar skill of the same layer, and the actual source the skill describes.
- **Watch the fixes.** A fix can break something else. The red-team lens and the fresh re-audit are there to catch that.
- **`clearsBar` gates the merge.**

## Lens sets

Scale the panel to the risk: about three lenses for a quick check, about ten for a full gate.

### General

discovery, leanness, shape and layer, scripts, accuracy against the source, domain correctness, wiring, boundaries, red team, then synthesis.

### Prompt engineering (the script's default ten)

| Lens | Asks |
|---|---|
| discovery | Does the description alone get the skill loaded? |
| disambiguation | Could it be confused with a sibling? |
| triggers | Which real phrasings and synonyms are missing? |
| clarity | Is every instruction unambiguous and actionable? |
| layer | Does the degree of freedom fit the declared layer? |
| leanness | Is SKILL.md an index with detail one level down? |
| tokens | Which lines fail the cut test? |
| consistency | Do terms, names, paths, cross-references and examples agree? |
| misfire | Where would it over-apply, skip its gate, invent a path, or produce the wrong output? |
| redteam | Make it fail to trigger, trigger wrongly, or break its output; find prose that claims what the script does not do. |

## Running it with the script

`scripts/audit-panel.js` is a Workflow-tool template (workflow name `skill-audit-panel`, phases Audit and Synthesis). It takes no arguments; edit its config block first:

| Constant | Set to |
|---|---|
| `TARGET` | absolute paths of the SKILL.md and each bundled file and script |
| `RUBRIC` | path to skill-creator's SKILL.md plus checklist.md |
| `EXEMPLAR` | a known-good skill of the same layer |
| `GROUND_TRUTH` | the real source the skill documents, with the key facts to check |
| `LENSES` | label and brief pairs; defaults to the ten above |

It runs one agent per lens in parallel (labelled `audit:<lens>`), tags each finding with its lens, and hands them all to a `synthesis` agent. The result is `{ remaining, clearsBar, verdict }`: the surviving findings with the lenses that raised them, the gate boolean, and a one-paragraph verdict.

After applying fixes, launch it again as a new run. Do not resume the old one; resumed agents return cached results.