Audit Docs

---
name: audit-docs
description: >-
  Audit the project's docs/ briefs against the high bar — each document on its
  own (principle form, enforceability) and in combination (cross-document
  coherence, contradictions, brief-vs-data agreement). Runs the doctor
  (deterministic structural gate) first, then the advisory judgment review, and
  reports both. Load when you want to check the docs hold up — at onboarding,
  after a harness upgrade, or on request. The judgment half is advisory: it
  judges form, never philosophical direction.
compatibility:
  - claude-code
  - github-copilot
  - opencode
reads:
  - docs/prd.md
  - docs/system-design.md
  - docs/adr/
  - docs/ubiquitous-language.md
  - docs/testing-principles.md
  - docs/architecture-principles.md
  - docs/security-principles.md
metadata:
  version: "1.0"
  author: team
---

## What this audits

A full docs audit has two passes, and this skill runs both:

1. **Structure (deterministic, blocking).** The doctor checks that each brief is present and well-formed — roster, required sections, data slots, naming, and channel invariants. Pass/fail, model-free, the same verdict in CI.
2. **Judgment (advisory).** This review judges whether a structurally-valid brief can do its job: can an agent adopt these documents as convictions and enforce them consistently — each on its own, and in combination?

The two are deliberately separate engines (deterministic vs judgment); this skill is the one entry point that sequences them so a single request audits the docs **individually and against each other**.

One boundary is load-bearing: **the judgment pass judges form, never direction.** Whether the project's stances are wise is the project's call; whether they are stated so an agent can enforce them is the harness's call. The criteria below contain no philosophy terms — verifiable by grep.

## How to run the audit

1. **Run the doctor first.** From the project root:
   ```bash
   python3 scripts/doctor.py check
   ```
   Report its verdict. A structural failure (`FAIL <check>`) is a hard finding — surface it and stop the judgment pass if the brief is too incomplete to judge (a missing roster file cannot be reviewed). Otherwise continue.
2. **Run the judgment checks below** across the roster, individually (per file) and in combination (across files).
3. **Report both passes together** — the doctor's pass/fail line, then the judgment findings tagged as in *Findings format*. The structural verdict gates; the judgment findings advise.

The audit has three natural moments. The first is when the briefs are born, through `init` or `derive-briefs`. The second is after every harness upgrade, where `materialize` points here when a template section or paragraph moved. The third is whenever a reviewer raises a `clarify` against a brief during a slice. Briefs drift with every slice; an audit run only at adoption misses the drift.

## Checks

Walk each roster file:

1. **Principle form.** Each principle entry states the principle, why it holds, and how to apply it. A bare rule with no rationale is an orphan-rule finding: an agent cannot extend it to a case the rule does not name. Exception: a rule whose rationale is marked `Provenance: not recoverable` (`derive-briefs`) is finished — tag it `clarify` for the owner, never as missing rationale to reconstruct.
2. **Probe questions.** For each major section ask: can an agent reason from this text to a case the text does not cover? If not, name the gap as a finding.
3. **Enforceability.** A reviewer reading an entry can decide pass or fail. Unmeasurable qualifiers without supporting data are findings.
4. **Internal consistency.** No entry contradicts another in the same file.
5. **Cross-doc consistency.** No entry contradicts another roster file. Terms match the canonical spellings in `docs/ubiquitous-language.md`. Then the precedence probe: for each reviewer-facing rule, ask whether `docs/system-design.md` assigns the case the rule reads over. A rule that reads unconditionally where the design assigns the case is a precedence conflict, even when no sentence contradicts another. The design doc's assignment governs, and the finding asks the brief to name its scope. The recorded case is a testing brief's "could this be tested without the framework?" against an architecture brief that assigns request normalization to the web controller. Each read fine alone, and a reviewer blocked a correctly placed rule twice.
6. **Brief-data agreement.** Where a brief states a convention that project data (`scripts/layout.toml`, or the stack's `scripts/layout-defaults.toml` beneath it) also encodes operationally, the prose and the data must agree. The brief carries the principle; the data file carries the operational form.
7. **Kernel fit.** A brief specializes its discipline; it never replaces it. Express such a finding structurally — "this entry makes section X unenforceable" — never as a verdict on the stance itself.
8. **Abstraction level (prd.md, system-design.md).** The doctor caps each doc's word count and flags field-table headers; this pass catches what it cannot. In `system-design.md`, flag any paragraph that enumerates a type's fields, a config block's keys, or a function's parameters in prose. Apply the rename self-test (`document-writing` § Abstraction Level): if a source rename would silently falsify a paragraph, it sits at the wrong level. In `prd.md`, flag leaked mechanism: flag/exit-code tables, output layouts. Confirm each requirement reads as narrative prose with a tagged "Done when" bullet, not a re-stated structured contract. A doc near its budget with these patterns is the compaction signal (`doc-sync` § Compaction).

## Findings format

One finding per issue, tagged by routing action:

| Tag | Use |
|-----|-----|
| `autofix` | Style-only: writing standards, formatting. Offer the diff; apply only on consent. |
| `clarify` | A question the owning agent or the user must answer. |
| `escalate` | Structural problem needing a project decision: contradictions between briefs, an unenforceable core section. |

Style-only findings are autofix offers, never lectures. Every edit to a roster file routes through its owning agent as a consented diff — this review never writes project docs.

## Upgrade path

When the harness ships a new expectation, it arrives here as review feedback: the finding names the new expectation, includes the shipped default text, and offers to draft the project's own stance instead. The project chooses; the review records nothing on its behalf.