메뉴
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.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| 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"} |
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.
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
/subsystem-audit
/subsystem-audit --fix
/subsystem-audit --doc analytics-design
/loop 10m /subsystem-audit --fix
After the audit, print:
Subsystem Audit Report
═══════════════════════════════════════════
Canonical source: specs/original-system-design.md
Design docs: 15
PRDs: 9
tx doc sync: 24/24 passed
Check Status
─────────────────────────────────
1. Subsystem coverage ✓ 0 gaps
2. Interfaces ✓ 0 missing
3. YAML schema ✓ 0 violations
4. Duplication ✓ clean
5. Self-containment ✓ complete
6. Canonical drift ✓ no drift
7. Dependency graph ✓ valid DAG (5 layers)
8. tx doc sync ✓ 24/24
Build Order (for task decomposition):
L0: overview, temporal-workflows, tenancy-model
L1: assets, billing, notifications, scraping, social-platform, webhooks
L2: ai-generation, analytics, content-pipeline
L3: knowledge-base, rendering-architecture
L4: experiments-design
specs/original-system-design.md, fix the design doc.tx doc sync validation.Long-running (multi-hour) adversarial hunt for P0/P1/P2 bugs across the codebase. Mixes codebase observation, mechanical linting, real test + telemetry verification, and parallel skeptic sub-agents that must REFUTE each candidate before it is accepted. Fixes verified bugs on a branch off main with surgical per-bug commits, re-runs gates, and writes a dated report to the Desktop. Never pushes or merges. Use when you want a deep, autonomous bug-finding-and-fixing pass.
Diagnose and durably eliminate flaky/intermittent test failures (passes locally but fails CI, rotates between tests, red only under load). Reproduce under contention, instrument the real state instead of guessing, root-cause by signal not duration, fix at the source, validate multi-run. Use when a test is flaky, CI is intermittently red, or fixing one flake unmasks others.
Safely prune dead local branches, git worktrees, and remote branches in this repo. Use when asked to "prune dead branches", "clean up worktrees", "delete merged branches", "tidy up git", or after a batch of PRs has merged. Knows this repo merges via squash, so it verifies death by PR state, not just git ancestry.
Reduce test-suite wall-clock (dev + CI) without losing coverage or telemetry. Measure the phase breakdown first, then apply proven levers (parallelize turbo, narrow imports vs barrels, lazy-load heavy graphs, pool/worker config, DB pool sizing) and capture the before/after delta. Use when tests are slow, CI time is high, or to set/check a perf baseline. Composes with the read-only test-perf and test-census skills.
Census the repo's tests by TYPE, not by name. Classifies every tracked test file via content heuristics into unit / integration / react-component / e2e (plus a separate db pgTAP count), in precedence order so buckets are mutually exclusive. Use when the user asks "what kinds of tests do we have", "how many component vs integration tests", "what's our e2e coverage", or wants a per-area test-type breakdown.
Snapshot test-suite timings in this repo. Runs the unit and/or integration suites (or a single integration project) and reports wall-clock time, Vitest's own phase breakdown (transform/setup/import/tests/environment), and the slowest test files. Use when the user asks "how slow are the tests", "where does the test time go", wants a perf baseline, or wants to check the suite hasn't regressed.