c3-audit

name	c3-audit
description	Use when verifying C3 documentation quality - checks methodology compliance (layer rules, structure, diagrams) and implementation conformance (docs vs code drift)

C3 Audit

Overview

Verify C3 documentation from two angles:

1. Methodology Compliance - Do docs follow C3 layer rules?
2. Implementation Conformance - Do docs match code reality?

Announce: "I'm using the c3-audit skill to audit documentation."

Audit Modes

Mode	Purpose	When
Methodology	Verify layer rules	After doc changes
Full	All docs vs code	Periodic health check
ADR	Verify ADR implemented	After ADR work
ADR-Plan	ADR ↔ Plan coherence	Before handoff
Container	Single container audit	After container changes
Quick	Inventory check only	Fast sanity check

Mode 0: Methodology Audit

Phase 1: Load Layer Rules

Load rules from references/layer-audit-rules.md (or layer skill defaults).

Phase 2: Structure Check

Verify IDs, paths, frontmatter per references/v3-structure.md.

Phase 3: Layer Content Audit

For each doc, verify content matches layer rules:

• Context: Has container inventory, protocols. NO component lists.
• Container: Has component inventory, tech stack. NO step-by-step algorithms.
• Component: Has flow, dependencies. NO sibling relationships.

Phase 4: Diagram Audit

Verify diagram types appropriate per layer (see references/layer-audit-rules.md).

Phase 5: Contract Chain

Check for orphans (undocumented) and phantoms (documented but missing).

Phase 6: Load Layer Skills

Load c3-context-design, c3-container-design, c3-component-design for suggestion generation.

Phase 7: Generate Report

Use template from references/audit-report-templates.md.

Mode 1: Full Audit

1. Load all C3 docs (inventory)
2. Explore codebase (Task tool, Explore agent)
3. Compare: inventory drift, technology drift, structure drift, protocol drift
4. Generate drift report

Mode 2: ADR Audit

1. Load ADR, extract Changes Across Layers + Verification Checklist
2. Verify each doc change was made
3. Verify code matches (use verification items)
4. Update Audit Record in ADR file:
   • Append row to "Audit Runs" table:

     | YYYY-MM-DD | [layers checked] | PASS/FAIL | [drift found or "None"] |
     

   • If PASS: Update "Lifecycle" table row for Implemented
5. If all pass: transition status to implemented, rebuild TOC

---

📋 ADR STATUS ENFORCEMENT (MANDATORY)

This applies to Mode 2 (ADR Audit) and any audit that touches ADRs.

Status Workflow

proposed → accepted → implemented
                   ↘ superseded
                   ↘ deprecated

Status Transition Rules

Transition	Requirement	Who
proposed → accepted	Design reviewed, approach approved	Human decision
accepted → implemented	All doc changes made, code matches, verification passes	Audit verifies
Any → superseded	New ADR replaces this one (link required)	Human decision
Any → deprecated	Decision no longer relevant	Human decision

Audit Verification for implemented Status

BEFORE transitioning to implemented, verify ALL:

Check	How to Verify
All "Changes Across Layers" made	Each doc modified as specified
Verification checklist passes	Each item checked and passes
Code matches docs	Implementation conforms to documented changes
Implementation Plan complete	All Code Changes done, Acceptance Criteria met

TOC Filtering

Only status: implemented ADRs appear in TOC.

After transitioning to implemented:

# Rebuild TOC using build-toc.sh from plugin
./build-toc.sh

Red Flags - STOP and Fix

🚩 ADR with implemented status but verification items unchecked 🚩 ADR in TOC but status is proposed or accepted 🚩 superseded ADR without link to replacement 🚩 Missing status field in frontmatter 🚩 Skipping accepted (going straight from proposed to implemented)

Audit Checklist for ADR Status

• ADR has status field in frontmatter
• Status is valid (proposed, accepted, implemented, superseded, deprecated)
• If implemented: all verifications pass
• If superseded: links to replacement ADR
• TOC only includes implemented ADRs

Mode 3: ADR-Plan Coherence

1. Extract ADR sections + Implementation Plan
2. Verify: Layer Changes → Code Changes (all mapped)
3. Verify: Verifications → Acceptance Criteria (all mapped)
4. Check for orphans, vague locations, untestable criteria

Mode 4: Container Audit

Focus on single container: technology match, component coverage, pattern compliance.

Mode 5: Quick Audit

# Inventory counts only
grep -c "| c3-[0-9]" .c3/README.md
ls -d .c3/c3-[0-9]-*/ 2>/dev/null | wc -l

Checklist

See references/audit-report-templates.md for full checklists per mode.

Related

• references/layer-audit-rules.md - Layer compliance rules
• references/audit-report-templates.md - Report formats
• references/v3-structure.md - ID/path patterns