canon-audit

/canon-audit

Audit the canon itself. Every other canon consumer in this family treats the flagged docs as authoritative — get-context loads and enforces them, codebase-review --lens canon-drift audits reality against them. This skill points the telescope the other way: are the canonical artifacts complete, correct, and sufficient for what the product is trying to do? Two mutually-consistent docs can both be wrong, and a canon can be perfectly aligned while silently missing the requirement that matters.

This skill is repo-agnostic. It uses the same manifest as /get-context (docs/context/canonical.yaml) and inherits that skill's loading discipline and contradiction/staleness definitions. A repo with no manifest has no canon to audit — say so and end.

Run order with codebase-review: when both are planned, run /canon-audit first and resolve the Critical/High findings — auditing conformance to a flawed canon aligns the code with the flaw.

Usage

/canon-audit                       # full audit, all dimensions
/canon-audit --dimension <key>     # one dimension (requirements | architecture | security | design | manifest)

Procedure

Step 0 — Load

1. Read .claude/repo-conventions.yaml (backlog root, templates, registers) — verify load-bearing keys against the tree rather than trusting them.
2. Load the canon exactly as /get-context does: read the manifest, load every flagged doc, expanding globs — full set, no sampling. Override the hard-stop: contradictions that would stop get-context are collected as Critical findings and the audit continues; this run's job is to enumerate everything in one pass.
3. Gather the audit context: the repo's dispositions registers (RAID/risk registers, ADR deviation tables, tech-debt backlog entries), a high-level code inventory (what's actually built), and the prior canon-audit report if one exists (docs/reviews/*-canon-audit.md).

Step 1 — Audit dimensions

Fan out one agent per dimension (Workflow tool when available, Agent tool otherwise). Each agent gets the loaded canon, the registers, code-read access, and its charter below. The charters are floors, not ceilings — every agent is explicitly licensed to surface risks and gaps outside its listed checks.

requirements — completeness of intent

• Requirements, scope, NFRs, or acceptance criteria that should exist for the current phase but don't — silent scope the product story implies (tenancy, compliance, retention/erasure, degraded states, observability, failure modes) with no canonical home.
• Intent stated but untestable: goals with no acceptance criteria, success claims with no metric, "honest data states" promised nowhere specified.
• Capabilities the product docs imply that the architecture and phase plan never account for — and the reverse: architectural machinery serving no stated requirement.
• Working-draft awareness: respect docs' own binding rules (a self-declared draft binds less than an accepted ADR); judge each artifact at its declared authority.

architecture — correctness and coherence

• Is the target architecture the right one for the stated product intent and scale — not merely internally consistent? Name the load-bearing assumptions and stress-test each.
• Internal coherence: target vs phased views converge or quietly diverge; decisions of record vs architecture visuals; sequencing that builds toward the target vs away from it.
• The canon's own deviation/exception tables: is any self-declared open gap actually undermining a committed milestone? Are deviations accumulating where a decision is being avoided?
• Decisions smuggled past the repo's decision discipline: contract/schema/technology choices appearing in lower-authority docs (or nowhere) that the decision framework says require a record.
• Choices justified only by effort/simplicity where a best-practice option was neither taken nor surfaced as an explicit decision — for security/authz/contract choices, Critical.

security — sufficiency, not just presence

Structure this audit around the canon's own declared risks and control ladders — then judge whether they are sufficient and true:

• For every control the security docs claim, verify its status in the real code, CI config, and test suites — never from doc badges. A claimed-but-absent control is a top finding; a control resting on reviewer vigilance where a mechanical gate is claimed is the same finding in slow motion.
• Coverage of the actual data flows: ingestion/derived lanes, runtime-created objects, staging/scratch surfaces, logs and caches, retention/erasure paths — do the declared controls reach all of them, or only the surfaces that existed when the doc was written?
• If the repo has an agentic/LLM surface: prompt-injection paths (untrusted input → prompt assembly → tool invocation), tool/grant blast radius, output-trust/provenance, egress gating — and whether any v-current-load-bearing injection control lacks both a binding decision record and a mechanical gate.
• Risk classes the canon doesn't mention at all: supply chain, CI/runner trust, tenant-config tampering, observability leakage. Rank what you judge the top risks; don't limit to the canon's list.

design — surfaces vs requirements

• Do the canonical mockups/design system under-serve the requirements: missing states (empty/error/loading/degraded), missing flows, accessibility gaps?
• Mockup ↔ design-system divergence that signals an unmade decision vs allowed per-client variation (respect the manifest's per-client keying — clients may differ from each other, never from the shared canon).
• Promised-but-unspecified visual/editorial commitments (provenance marks, data-state honesty, voice) with no implementable definition.

manifest — hygiene of the canon set itself

This skill owns manifest curation (the canon-drift lens only spot-checks it):

• Flagged entries resolving to no file; globs matching zero files; stub/empty canon.
• Unflagged canon: docs that plainly carry decision authority (new ADRs, a threat model, a phase plan) absent from the manifest — the canon-gating stack silently weakens as these accumulate.
• Precedence defects: missing categories, unranked entries, ordering that no longer matches the docs' own authority claims.
• Stale manifest commentary (entries described as "working draft" that have since hardened, superseded artifacts still flagged).

Step 2 — Verify

Adversarial verification, refute-stance, by agents independent of the finding's author — every Critical/High finding, sampled Medium:

• A "gap" that is actually built, or actually captured as an explicit open question / register row, is not a gap — verify against code and the registers before it survives. (A captured open question is the system working; report it only if its priority is wrong.)
• A "wrong decision" finding must engage the decision's recorded rationale, not just disagree with the outcome.
• Hedged claims: resolve or tag UNVERIFIED.

Step 3 — Open questions and spikes

From the verified findings, extract the highest-leverage unknowns: rank by how much downstream work each unblocks or de-risks. For each, recommend the concrete next step — a spike (time-boxed, with the question it must answer), a decision to force (with the options and the recommendation), or a sibling artifact to author. The repo's decision discipline applies: the spike is the bridge from unsure to elaborated — never recommend "decide during implementation."

Step 4 — Report

Write docs/reviews/YYYY-MM-DD-canon-audit.md (a flat dated file, deliberately distinct from codebase-review's dated folders — the two coexist in docs/reviews/ without collision, and Step 0's prior-report glob docs/reviews/*-canon-audit.md depends on this naming; don't normalize it into the folder convention):

# Canon Audit — YYYY-MM-DD

## Verdict
<one paragraph: is the canon fit to plan against right now? The 2-3 findings that most change what happens next.>

## Findings (Critical / High / Medium)
| ID | Dimension | Artifact §section | What's missing or wrong | Why it matters | Recommended fix or spike | Verified |
|----|-----------|-------------------|-------------------------|----------------|--------------------------|----------|

## Contradictions found while loading
<the items get-context would have hard-stopped on, in its 3-part format (what conflicts / verification / recommended fix)>

## Open questions & recommended spikes (ranked)
| # | Unknown | What it blocks/risks | Recommended step |
|---|---------|----------------------|------------------|

## Known & correctly captured
<gaps already held as explicit open questions / register rows — listed so they aren't re-raised as discoveries>

## Coverage
<canon docs audited per dimension; anything not assessed and why>

Then, for findings whose fix is actionable work (a spike, a missing artifact), offer proposal-only stubs in the repo's tech-debt/backlog convention — same altitude rules as everywhere else: intent + open questions, no invented detail.

Hard rules

1. Findings only. Never edit the canon docs, the manifest, or code — changing the canon is the user's decision, made on the report.
2. No auto-resolution of contradictions. Inherited from get-context: precedence informs the recommendation; the user decides.
3. Open-ended by design. The dimension charters are floors. An auditor that only answers the listed questions has under-delivered — the standing instruction to every agent is "what else is wrong that nobody asked about?"
4. Uncertainty is an open question, never invented detail. If the audit can't establish whether something is a gap, it reports the question, not a guess.
5. Verify before asserting. Every "missing/wrong" claim is checked against code, git, and the registers. Unverifiable claims are tagged, not asserted.