Menu
Architecture health audit. Invoke with /tzurot-arch-audit to run static analysis, check boundaries, and assess code health.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
Git workflow procedures. Invoke with /tzurot-git-workflow for commit, PR, and release procedures.
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.
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.
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.
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.
Session workflow procedures. Invoke with /tzurot-docs for session start/end, CURRENT.md and backlog management.
| 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 |
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.
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.
Work through each section that the quick scan flagged, or run all 7 periodically.
Tool: pnpm depcruise
What it catches:
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.
Tool: pnpm ops xray --summary
What it catches:
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
Tool: pnpm ops xray --suppressions
What it catches:
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
Tool: pnpm knip
What it catches:
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
Tool: pnpm cpd
What it catches:
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 */
Tool: pnpm ops test:audit
What it catches:
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.
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 |
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)
pnpm depcruise:baseline # If circular deps decreased
pnpm ops test:audit --update # If coverage gaps closed
backlog/now.md (📥 Untriaged), then route per the granularity ladderdocs: architecture audit YYYY-MM-DD or fix: address architecture audit findings.claude/rules/01-architecture.mddocs/reference/STATIC_ANALYSIS.md.github/baselines/test-coverage-baseline.json.dependency-cruiser.cjs.dependency-cruiser-baseline.jsonknip.json.jscpd.json