subsystem-audit

name	subsystem-audit
description	Audit all design docs against the canonical system design for coverage, drift, duplication, interfaces, YAML schema, self-containment, and dependency graph validity. Use when adding new subsystems, verifying spec quality, or preparing for task decomposition.
argument-hint	[--fix] [--doc <name>]
metadata	{"short-description":"Audit design docs against canonical source of truth"}

Subsystem Design Doc Audit

Audit all design docs at specs/design/ against the canonical source of truth at specs/original-system-design.md. Identifies gaps, drift, duplication, missing interfaces, invalid YAML, broken dependencies, and incomplete specs. Optionally fixes issues in-place.

Canonical source: specs/original-system-design.md is the single source of truth. When there is a conflict between a design doc and the canonical source, the canonical source wins.

Workflow State Machine

START
  │
  ▼
┌─────────────────────────────────────────────────────┐
│ Step 0: READ CANONICAL SOURCE                        │
│                                                      │
│ Read specs/original-system-design.md section 3       │
│ (Subsystems) to get the authoritative list of 17     │
│ subsystems. Also check for unlisted subsystems       │
│ (e.g. Knowledge Base at /v1/knowledge/).             │
│                                                      │
│ If --doc <name> is provided, audit only that doc.    │
│ Otherwise audit all 15 design docs.                  │
└─────────────────────────────────────────────────────┘
  │
  ▼
┌─────────────────────────────────────────────────────┐
│ Step 1: SUBSYSTEM COVERAGE                           │
│                                                      │
│ Map each of the 17 subsystems to a design doc.       │
│ Report any subsystem without a dedicated doc.        │
│                                                      │
│ Current mapping (15 docs → 17+1 subsystems):         │
│  tenancy-model    → #1 Auth, #2 Org/Team             │
│  billing-pricing  → #3 Billing, #4 Credit            │
│  notifications    → #5 Notifications                 │
│  webhooks         → #6 Webhooks                      │
│  assets           → #7 Assets, #8 Uploader, #9 Ret. │
│  social-platform  → #10 OAuth, #11 Publisher         │
│  analytics        → #12 Analytics                    │
│  ai-generation    → #13 AI Generation                │
│  prompt-bandit    → #14 Experiments                  │
│  temporal-wf      → #15 Workflows                    │
│  rendering-arch   → Campaigns + Rendering            │
│  content-pipeline → Content lifecycle                │
│  knowledge-base   → Knowledge Base (unlisted)        │
│  scraping         → Trend Discovery (deferred)       │
│  overview         → Cross-cutting                    │
│                                                      │
│ ├─ GAP FOUND → If --fix, create new design doc       │
│ │              using the design-doc skill pattern     │
│ └─ ALL COVERED → Continue                            │
└─────────────────────────────────────────────────────┘
  │
  ▼
┌─────────────────────────────────────────────────────┐
│ Step 2: INTERFACES CHECK                             │
│                                                      │
│ Grep for `_No interfaces defined yet._` across all   │
│ design docs.                                         │
│                                                      │
│ ├─ FOUND → If --fix, write Effect-style interfaces:  │
│ │   - Read packages/core/src/domains/ for patterns   │
│ │   - Context.Tag ports, services, layers            │
│ │   - Repository ports with ListParams/PaginatedResult│
│ │   - Application services with CoreError            │
│ │   - Middleware (if applicable)                      │
│ │   - API route contracts                            │
│ └─ NONE → Continue                                   │
└─────────────────────────────────────────────────────┘
  │
  ▼
┌─────────────────────────────────────────────────────┐
│ Step 3: YAML SCHEMA VALIDATION                       │
│                                                      │
│ Check all invariants/failure_modes/verification       │
│ YAML blocks for correct tx schema:                   │
│                                                      │
│ invariants:                                          │
│   - id: INV-XXX-NNN     # ^INV-[A-Z0-9-]+$          │
│     statement: "..."                                 │
│     severity: critical|high|medium|low               │
│     verified_by: [REQ-XXX-NNN]  # minItems(1)       │
│                                                      │
│ failure_modes:                                       │
│   - condition: "..."                                 │
│     impact: "..."                                    │
│     handling: "..."                                  │
│                                                      │
│ verification:                                        │
│   - requirement_id: REQ-XXX-NNN  # ^REQ-[A-Z0-9-]+$ │
│     test_type: unit|integration|e2e|property|manual  │
│     target: "..."                                    │
│                                                      │
│ WRONG field names to catch:                          │
│   invariants: description→statement, no verified_by  │
│   failure_modes: trigger→condition, mitigation→handling│
│   verification: id→requirement_id, type→test_type,   │
│                 description→target, VER-→REQ-        │
│                                                      │
│ ├─ ISSUES → If --fix, rewrite with correct fields    │
│ └─ CLEAN → Continue                                  │
└─────────────────────────────────────────────────────┘
  │
  ▼
┌─────────────────────────────────────────────────────┐
│ Step 4: DUPLICATION AUDIT                            │
│                                                      │
│ Check for content duplicated across docs.            │
│ Each subsystem doc should own its content — no       │
│ copy-paste between docs. Cross-cutting concerns      │
│ belong in overview-design.md only.                   │
│                                                      │
│ Check for:                                           │
│  - Same DB table schema in multiple docs             │
│  - Same Effect port defined in multiple docs         │
│  - Identical paragraphs copy-pasted                  │
│  - Same ASCII diagrams repeated                      │
│                                                      │
│ Ownership rules:                                     │
│  agent_threads/messages → ai-generation-design       │
│  credit_ledger/usage_records → billing-pricing       │
│  team_media_assets → assets-design                   │
│  social_accounts → social-platform-design            │
│  campaigns → rendering-architecture-design           │
│  content items/assets/posts → content-pipeline       │
│  post_performance → analytics-design                 │
│  knowledge/diffs → knowledge-base-design             │
│                                                      │
│ ├─ DUPES → If --fix, keep in owner doc, replace      │
│ │          duplicate with cross-reference:            │
│ │          "See [x-design](x-design.md) for Y."      │
│ └─ CLEAN → Continue                                  │
└─────────────────────────────────────────────────────┘
  │
  ▼
┌─────────────────────────────────────────────────────┐
│ Step 5: SELF-CONTAINMENT CHECK                       │
│                                                      │
│ Each design doc must have these H1 sections:         │
│  - Summary                                           │
│  - Architecture (enough detail to implement from)    │
│  - Data Model (tables this subsystem OWNS)           │
│  - Interfaces (Effect ports + services + API routes) │
│  - Invariants (non-empty YAML)                       │
│  - Failure Modes (non-empty YAML)                    │
│  - Verification (non-empty YAML)                     │
│                                                      │
│ ├─ INCOMPLETE → If --fix, add missing sections       │
│ └─ COMPLETE → Continue                               │
└─────────────────────────────────────────────────────┘
  │
  ▼
┌─────────────────────────────────────────────────────┐
│ Step 6: CANONICAL DRIFT CHECK                        │
│                                                      │
│ For each design doc, read its corresponding section  │
│ from specs/original-system-design.md.                │
│                                                      │
│ Section mapping:                                     │
│  §1  → tenancy-model-design                         │
│  §2  → assets-design                                │
│  §4  → content-pipeline-design                      │
│  §5  → rendering-architecture-design                │
│  §6  → social-platform-integration-design            │
│  §9  → billing-and-pricing-design                   │
│  §10 → analytics-design                             │
│  §11 → scraping-and-trend-discovery-design           │
│  §13 → temporal-workflows-design                    │
│  §3,7,8,12,14-20 → overview-design                  │
│                                                      │
│ Report:                                              │
│  MISSING — canonical has it, design doc doesn't      │
│  CONTRADICTION — design doc disagrees with canonical │
│  OK — content matches                                │
│                                                      │
│ ├─ DRIFT → If --fix, add missing content / fix       │
│ │          contradictions (canonical wins)            │
│ └─ ALIGNED → Continue                                │
└─────────────────────────────────────────────────────┘
  │
  ▼
┌─────────────────────────────────────────────────────┐
│ Step 7: DEPENDENCY GRAPH VALIDATION                  │
│                                                      │
│ Read `depends_on` from all doc frontmatter.          │
│ Build the full dependency graph.                     │
│                                                      │
│ Validate:                                            │
│  - No circular dependencies                          │
│  - Graph forms a clean DAG                           │
│  - depends_on reflects BUILD ORDER                   │
│  - Every doc that uses tables/ports from another     │
│    subsystem lists it in depends_on                  │
│                                                      │
│ Print topological sort (build order):                │
│                                                      │
│  Layer 0: overview, temporal-workflows, tenancy-model│
│  Layer 1: assets, billing, notifications, scraping,  │
│           social-platform, webhooks                  │
│  Layer 2: ai-generation, analytics, content-pipeline │
│  Layer 3: knowledge-base, rendering-architecture     │
│  Layer 4: experiments-design                   │
│                                                      │
│ ├─ ISSUES → If --fix, update depends_on              │
│ └─ VALID DAG → Continue                              │
└─────────────────────────────────────────────────────┘
  │
  ▼
┌─────────────────────────────────────────────────────┐
│ Step 8: SYNC                                         │
│                                                      │
│ source ~/.zshrc >/dev/null 2>&1; eval 'tx doc sync'  │
│                                                      │
│ ├─ ALL SYNCED → Print summary report                 │
│ └─ ERRORS → Fix and re-sync                         │
└─────────────────────────────────────────────────────┘
  │
  ▼
DONE — Print summary table