Multi-perspective AI consultation. Invoke with /tzurot-council-mcp for major refactors (>500 lines), structured debugging after failed attempts, or when a technical decision has multiple viable approaches.

2026-07-267

tzurot-doc-audit

lbds137/tzurot

Documentation and auto-memory freshness audit. Invoke with /tzurot-doc-audit to review docs and Claude auto-memory for staleness, items in the wrong layer, and missing-tool drift.

2026-07-257

tzurot-review-response

lbds137/tzurot

PR review-response iteration: classify each finding by EDIT SHAPE (trivial → auto-apply as a test-gated fixup commit; semantic → ASK), check reviewer-vs-agent signal conflict, batch-present the four sections, cap at 3 automated rounds. Invoke with /tzurot-review-response the moment a claude-review or human reviewer posts findings on a PR — before applying anything.

2026-07-257

tzurot-bug-remediation

lbds137/tzurot

The recurring-bug remediation protocol: runtime evidence → root cause → exhaustive class sweep → seam-tier regression test → structural guard. Invoke with /tzurot-bug-remediation when a bug recurs, a "fixed" class regresses, the owner says a failure "keeps biting", OR at the FIRST fix of a path-specific UI/flow bug (create/edit/browse/view/delete) — to sweep sibling flows before declaring it fixed.

2026-07-207

tzurot-docs

lbds137/tzurot

Session workflow procedures. Invoke with /tzurot-docs for session start/end, CURRENT.md and backlog management.

2026-07-207

name	tzurot-arch-audit
description	Architecture health audit. Invoke with /tzurot-arch-audit to run static analysis, check boundaries, and assess code health.
lastUpdated	2026-06-17

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 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

Result	Meaning	Action
`0 new violations`	Clean	None
New `error` severity	Boundary broken	Fix now — move shared code to common-types or use API calls
New `warn` severity	Soft boundary	Track — add to backlog if pattern is spreading
Baseline count decreased	Progress	Run `pnpm depcruise:baseline` to lock in improvement

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:

Warning	Threshold	Action
File >400 lines	400 warn, 500 error	Fix now if >500 (ESLint blocks). Track if 400-500.
Package >3000 lines	3000	Track — consider splitting. Watch common-types especially.
Package >50 exports	50	Track — sign of bloated API surface.
Suppression cluster >20	20	Track — file may need refactoring instead of suppressing.

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:

Finding	Action
No justification suppressions	Fix now — add `-- reason` or fix the underlying issue
High count for a single rule	Track — may indicate a systemic issue needing refactoring
"pre-existing" dominates	Track — chip away during related changes
Single file with many supprs	Track — file may need refactoring instead of suppressing

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:

Finding	Action
Unused export in service code	Fix now — remove the export
Unused export in common-types	Verify not used at runtime (check all services). If truly unused, remove.
Unused dependency	Fix now — `pnpm remove <dep>` from the relevant package
Unlisted dependency	Fix now — `pnpm add <dep>` to the relevant package
False positive (runtime-only usage)	Accept — add to `knip.json` ignore

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/

Finding	Action
Cross-service duplication	Fix now — extract to common-types
Within-service duplication	Track — extract helper if >3 occurrences
Total >5%	Fix now — CI will fail
Test file duplication	Accept — tests are excluded from CPD

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

Finding	Action
"NEW gaps found"	Fix now — write tests, never add to `knownGaps`
Existing `knownGaps` items	Track — chip away at tech debt
Coverage below 80%	Fix now — Codecov blocks PRs

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

Pattern	What it suggests
One package dwarfs others	Extraction candidate — is it doing too much?
Package with 0 exports	Dead package or missing entry point
High import fan-in on one file	Potential god-module, consider splitting
common-types >50 exports	Bloat — extract domain-specific packages
Circular import patterns	Architectural coupling — may need interface extraction

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

Fix "Fix Now" items immediately

Update baselines to lock in improvements:

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

Add "Track" items to backlog/now.md (📥 Untriaged), then route per the granularity ladder
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