c3-audit

lagz0ne's avatarfrom lagz0ne

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

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 24, 2025
[Architecture Design]

When & Why to Use This Skill

The c3-audit skill is a specialized tool designed to maintain the integrity and quality of system architecture documentation. It automates the verification of C3 methodology compliance, ensuring that documentation layers—Context, Container, and Component—adhere to strict structural rules. By detecting 'documentation drift,' it identifies discrepancies between the codebase and its description, while also providing a rigorous framework for managing Architecture Decision Record (ADR) lifecycles and status enforcement.

Use Cases

  • Methodology Compliance: Automatically verify if architectural docs follow C3 layer rules, structural patterns, and diagram standards after significant design updates.
  • Implementation Drift Detection: Perform periodic health checks to compare the codebase against documentation, identifying undocumented components or outdated technology descriptions.
  • ADR Lifecycle Management: Enforce the transition of Architecture Decision Records from 'accepted' to 'implemented' by verifying that all specified code and doc changes have been completed.
  • Design-to-Plan Coherence: Audit the alignment between ADRs and implementation plans before developer handoff to ensure all architectural decisions are mapped to actionable tasks.
  • Container-Level Auditing: Conduct focused audits on specific system containers to ensure pattern compliance and technology stack consistency.
namec3-audit
descriptionUse 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.

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