Skill: hydroculator/cathedral-audit (version 1.0.0)

--- name: cathedral-audit description: Run a full spec-code audit on the Cathedral codebase. Use after build waves, major refactors, or when spec-code drift is suspected. Produces forward audit (specs→code), reverse audit (code→specs), bug report, and prioritized fix plan. Drives execution of fixes through CC sessions. --- # Cathedral Audit A structured process for measuring and closing spec-code drift in the Cathedral C# codebase. ## When to Run - After a build wave (multiple features/refactors landed) - Before starting a new major feature (establish baseline) - When spec-code drift is suspected - Periodically as a health check (not on a calendar — trigger on events) ## Process Overview ``` 1. Forward Audit (specs → code) 2. Reverse Audit (code → specs) 3. Consolidation & Prioritization 4. Execution 5. Verification ``` ## Step 1: Forward Audit (Specs → Code) For each spec in `kitty-specs/`, compare what the spec says against what the code does. **Output per spec:** One of: - ✅ **Conformant** — code matches spec - ⚠️ **Divergent** — code exists but differs from spec - ❌ **Missing** — spec describes something not built **Deliverable:** `kitty-specs/000-project-context/spec-audit-YYYY-MM-DD.md` Use parallel CC agents (one per spec batch) for speed if memory allows. **On memory-constrained hosts (e.g., WSL2), run sequentially — two concurrent CC sessions will OOM.** Provide each agent read-only access. ## Step 2: Reverse Audit (Code → Specs) Scan all `.cs` files in `src/Cathedral.Core/` and `src/Cathedral.TestHarness/`. For each file/subsystem, determine: - Is it covered by a spec? - Does it match what the spec says? - Is it dead/orphaned code? **Output sections:** 1. **Executive Summary** — counts with delta from previous audit 2. **Unspecced Code** — files/subsystems with no spec coverage 3. **Architectural Divergences** — code takes a fundamentally different path than spec 4. **Code Exceeding Spec** — code has features the spec doesn't document 5. **Dead/Orphaned Code** — files with no callers or references 6. **Bugs Discovered** — runtime, data, or logic bugs found during review 7. **Comparison with Previous Audit** — what improved, what remains **Deliverable:** `kitty-specs/000-project-context/reverse-audit-YYYY-MM-DD.md` Use parallel CC agents (group files by directory/subsystem) for speed if memory allows. **Run sequentially on memory-constrained hosts.** ## Step 3: Consolidation & Prioritization Merge findings from both audits into a prioritized action plan: | Priority | Category | Criteria | |----------|----------|----------| | **P0** | Bug fixes | Runtime impact — broken endpoints, data corruption, crashes | | **P1** | Dead code removal | Safe deletes that reduce confusion and LOC | | **P2** | Data quality fixes | Dropped data, wrong defaults, double-logging | | **P3** | Spec coverage | Write new specs for unspecced code (no code changes) | | **P4** | Spec accuracy | Update existing specs to document code-exceeding-spec features | | **P5** | Mechanical refactors | Renames, wiring, entity-scoping completion | | **P6** | Architectural gaps | V2 features where code diverges from spec by design (defer) | **Rules:** - Bugs always get their own section with severity ratings - "Code exceeding spec" = spec update, not code change - Architectural divergences that are intentionally deferred (V2 work) go to P6 and are documented but not actioned - Each priority level should be achievable in a single CC session **Deliverable:** Recommendations section in the reverse audit report. ## Step 4: Execution Execute fixes by priority tier (P0 first, P6 last or deferred). **Per priority tier:** 1. **Log intent** to `memory/YYYY-MM-DD.md` — tier name, CC session name, what's being attempted 2. Write a task briefing for CC (see `references/cc-task-template.md`) 3. Launch CC session: `cat /tmp/task.md | claude -p --allowedTools 'Edit,Write,Read,Bash'` 4. Set up monitoring cron (every 5 min) 5. When CC completes: **log results** to daily memory — files changed, what was done, any issues 6. **Verify build before committing** — `dotnet build` must pass 7. If CC gets killed (OOM): check `git diff --stat`, verify build manually, fix any issues, log the incident 8. Commit with descriptive message referencing the priority tier 9. **Log commit hash** to daily memory **Hard rules:** - ⚠️ **ALWAYS verify `dotnet build` passes before committing.** No exceptions. CC may get OOM-killed mid-build-check. - ⚠️ **ALWAYS log to daily memory file at every step.** Log intent before launch, results after completion, commit hash after commit. If the session dies, the log survives for recovery. - One commit per priority tier (or logical grouping) **Logging template for daily memory:** ```markdown ## [Priority Tier Name] - CC session: [name] (launched ~HH:MM CST) - Task: [brief description] - Status: [RUNNING | ✅ COMPLETE | ❌ FAILED | ⚠️ KILLED] - Files changed: [count] - Key actions: [what was done] - Issues: [any problems encountered] - Committed as [hash] ``` ## Step 5: Verification After all tiers are complete, optionally run a quick re-audit to measure improvement: - Compare counts: unspecced, divergent, dead code, bugs - Verify delta matches expectations - Document remaining gaps and whether they're P6/deferred or newly discovered **Deliverable:** Updated audit files with comparison section. ## Logging Every audit produces a complete trail in `memory/YYYY-MM-DD.md`: - **Audit launch** — which audits are being run, baseline reference - **Audit results** — summary counts, key findings - **Each priority tier** — intent, CC session, results, issues, commit hash - **Final summary** — total commits, total lines changed, what's resolved vs deferred This is non-negotiable. The Feb 17-18 amnesia incident proved that unlogged work is lost work. Log-then-act: write what you're about to do BEFORE doing it, then update with results. ## Baseline Tracking Always compare against the previous audit. Store audits as: ``` kitty-specs/000-project-context/ spec-audit-YYYY-MM-DD.md (forward) reverse-audit-YYYY-MM-DD.md (reverse) ``` The executive summary table with deltas is the key metric: ```markdown | Category | Previous | Current | Delta | |----------|----------|---------|-------| | Unspecced Code | 38 | 24 | -14 | | Divergences | 12 | 7 | -5 | | Dead Code | 14 | 8 | -6 | | Bugs | 0 | 8 | +8 | | Conformant | ~60 | ~120 | +60 | ``` ## CC Task Briefing Template See `references/cc-task-template.md` for the standard format for CC task briefings.

path: references/cc-task-template.md
content: # CC Task Briefing Template

Use this format when writing task briefings for Claude Code sessions.

```markdown
# Task: [Short title]

[1-2 sentence context: what audit finding this addresses and why]

## Items

### 1. [Item name]
- File(s): `path/to/file.cs`
- Problem: [What's wrong]
- Fix: [What to do]

### 2. [Item name]
...

## Constraints
- Verify with `dotnet build` after all changes
- Grep for references before any deletion
- NO architectural changes unless explicitly stated
- Report what you did for each item
```

## Guidelines

- **Be specific.** File paths, method names, property names. CC works best with exact targets.
- **State the problem AND the fix.** Don't make CC figure out the solution — you already know it from the audit.
- **Group by theme.** One briefing per priority tier, not per item.
- **Include constraints.** Always include `dotnet build` verification. Add "grep before delete" for removal tasks.
- **Scope appropriately.** Each briefing should be completable in one CC session (5-20 min). If it's bigger, split it.
- **No ambiguity on code changes vs spec changes.** Explicitly state "NO code changes" for spec-only tasks, or "spec updates only" etc.


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)