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 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:
     Copy

     | 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

Audit Verification for implemented Status

BEFORE transitioning to implemented, verify ALL:

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