Architecture Audit Procedure

Invoke with /tzurot-arch-audit to audit codebase architecture and health.

Run this periodically (before PRs, start of session, after major changes) to catch boundary violations, dead code, duplication, and coverage gaps.

Standards live in .claude/rules/01-architecture.md. Rationale in docs/reference/STATIC_ANALYSIS.md. This skill is the verification procedure.

Quick Scan

Fast triage (~30 seconds). Run frequently — before PRs or at session start.

pnpm ops xray --summary          # Package health warnings
pnpm ops xray --suppressions     # Suppression audit (tech debt)
pnpm depcruise                   # Boundary violations vs baseline
pnpm ops test:audit              # Coverage ratchet status (drift-detected)
pnpm ops cpd:check               # Duplication ratchet status (drift-detected)
pnpm ops guard:proposal-links    # Proposal-doc orphan check
pnpm ops guard:audit-tool-docs   # Audit-tool WHY.md bidirectional check

If all green (no new warnings, violations, gaps, or guard failures): stop here.

If cpd:check or test:audit reports drift (mentions configHash): the tool's measurement-affecting config changed since the baseline was captured. Run pnpm ops cpd:update-baseline (or pnpm ops test:audit --update) to refresh; verify the diff isn't masking a real regression before committing the refreshed baseline. See [docs/reference/audit-enforcement.md](../../../docs/reference/audit-enforcement.md) for the drift contract. Guard tools (guard:*) don't have baselines and don't emit configHash errors — they hard-fail directly on findings.

If anything flags: proceed to the relevant Deep Dive section below.

Deep Dive

Work through each section that the quick scan flagged, or run all 7 periodically.

1. Service Boundaries

Tool: pnpm depcruise

What it catches:

• Prisma imports in bot-client (error)
• Cross-service direct imports (error)
• Circular dependency chains (error)
• ai-worker importing Discord.js directly (warn)

Interpreting results:

pnpm depcruise                # Shows NEW violations beyond baseline
pnpm depcruise:baseline       # Update baseline after fixing violations

Current baseline: 54 circular dependency violations (pre-existing). New circular deps beyond baseline are flagged.

Reference: .dependency-cruiser.cjs for rule definitions, .dependency-cruiser-baseline.json for known violations.

2. Package Health

Tool: pnpm ops xray --summary

What it catches:

• Files approaching or exceeding 400/500 line limits
• Packages exceeding 3000 total lines or 50+ exports
• ESLint suppression clusters (>20 suppressions in one file)

Interpreting results:

Deeper investigation:

pnpm ops xray <package-name>            # Full declarations for one package
pnpm ops xray --include-private         # Include non-exported declarations

3. Suppression Audit

Tool: pnpm ops xray --suppressions

What it catches:

• Lint/type suppressions without justification comments
• Rules suppressed most frequently (potential systemic issues)
• Packages with highest suppression density
• "pre-existing" tech debt vs intentional suppressions

Interpreting results:

Single package audit:

pnpm ops xray bot-client --suppressions   # Audit one package

4. Dead Code

Tool: pnpm knip

What it catches:

• Unused exported functions, types, constants
• Files not imported by any entry point
• Dependencies in package.json not used in code
• Unlisted dependencies (used but not declared)

Interpreting results:

Auto-fix (review diff before committing):

pnpm knip:fix    # Removes unused exports

5. Code Duplication

Tool: pnpm cpd

What it catches:

• Copy-pasted code blocks across files
• Total duplication percentage vs 5% threshold

Interpreting results:

pnpm cpd              # Console output
pnpm cpd:report       # HTML report in reports/jscpd/

Suppressing intentional duplication:

/* jscpd:ignore-start */
// Reason: <explain why duplication is intentional>
/* jscpd:ignore-end */

6. Test Coverage

Tool: pnpm ops test:audit

What it catches:

• New API schemas without corresponding tests
• New Prisma services without test coverage
• Coverage gaps below 80% threshold

Interpreting results:

pnpm ops test:audit              # Check current state vs baseline
pnpm ops test:audit --update     # Update baseline after closing gaps

Baseline file: .github/baselines/test-coverage-baseline.json

Critical rule: Never add new code to knownGaps. That baseline is for pre-existing tech debt only.

7. Full Structure Review

Tool: pnpm ops xray --format md

When: Periodically (monthly or after major feature work), not every session.

What to look for:

pnpm ops xray --format md              # Full markdown report
pnpm ops xray --format md --imports    # Include import analysis
pnpm ops xray --summary --output f     # Write summary to file for diffing

Findings Template

Use this format to report audit results:

## Architecture Audit — YYYY-MM-DD

### Metrics

| Metric           | Current | Baseline | Trend |
| ---------------- | ------- | -------- | ----- |
| Circular deps    | NN      | 54       | +/-N  |
| CPD %            | N.N%    | 5% max   | +/-N  |
| Knip findings    | NN      | —        | —     |
| Coverage gaps    | NN      | NN       | +/-N  |
| Files >400 lines | NN      | —        | —     |

### Fix Now

- [ ] Item (tool that flagged it)

### Track (add to backlog)

- [ ] Item (current value → target)

### Accepted (reviewed, intentional)

- Item (reason)

After Audit

1. Fix "Fix Now" items immediately
2. Update baselines to lock in improvements:

``bash pnpm depcruise:baseline # If circular deps decreased pnpm ops test:audit --update # If coverage gaps closed ``

1. Add "Track" items to backlog/now.md (📥 Untriaged), then route per the granularity ladder
2. Commit: docs: architecture audit YYYY-MM-DD or fix: address architecture audit findings

References

• Architecture rules: .claude/rules/01-architecture.md
• Static analysis rationale: docs/reference/STATIC_ANALYSIS.md
• Test coverage baseline: .github/baselines/test-coverage-baseline.json
• Dependency cruiser config: .dependency-cruiser.cjs
• Dependency cruiser baseline: .dependency-cruiser-baseline.json
• Knip config: knip.json
• CPD config: .jscpd.json