Code Hygiene

---
name: code-hygiene
description: "Codebase health analysis: dead code, test quality, duplicates, complexity, security, architecture mapping. Tool-first, structured storage, forge integration."
---

# Code Hygiene — Scan, Report, Integrate

Persistent codebase health analysis. Runs static tools, interprets output, stores structured findings, suggests forge tasks for cleanup.

## When to Use
- After shipping a feature (catch accumulated tech debt)
- Periodic hygiene (every 1-2 sprints)
- Before major refactoring (map current state first)
- Onboarding to unfamiliar codebase (architecture overview)
- User says "code hygiene", "tech debt", "почисти код", "найди мертвый код", "проверь тесты"

## Pipeline: SCAN → REPORT → INTEGRATE → SAVE

---

### Phase 1: SCAN

#### 1a. Project Detection
- `package.json` → TypeScript/JavaScript (primary, full tool support)
- `pyproject.toml`/`setup.py` → Python (semgrep + scc only)
- `go.mod` → Go (semgrep + scc only)
- `Cargo.toml` → Rust (semgrep + scc only)
- Report honestly: "Full analysis available for TS/JS. Limited to semgrep+scc for [language]."

#### 1b. Tool Detection
Check availability, report what's missing:
```
Global:   which tsc semgrep scc jq
Local:    grep devDependencies package.json for knip, jscpd, dependency-cruiser, stryker
Missing:  suggest `npm i -D knip jscpd dependency-cruiser` for full coverage
```

#### 1c. Tool Execution
Run available tools. ALL output goes to files first — NEVER read raw output into context.

**3-step pattern for every tool:**
1. **Redirect:** `<cmd> > .omc/hygiene/raw-<name>.json 2>&1`
2. **Summarize:** `jq '<path>[:50]' raw-<name>.json > <name>.json`
   - If jq unavailable: `Read raw-<name>.json` with `limit: 200`
   - tsc is plain text: `head -100 raw-types.txt > types.txt`
3. **Read:** Read `<name>.json` — NEVER read `raw-*` files into context

**Tools (run in parallel via background Bash):**

| Tool | Command | Output file | Summary jq path |
|------|---------|-------------|-----------------|
| tsc | `tsc --noEmit 2>&1 > raw-types.txt` | types.txt | `head -100` (plain text) |
| scc | `scc --by-file --format json src/ > raw-complexity.json` | complexity.json | `sort_by(.Complexity) \| reverse \| .[:50]` |
| semgrep | `semgrep scan --config auto --json . > raw-security.json` | security.json | `.results[:50]` |
| knip | `npx knip --reporter json > raw-dead-code.json` | dead-code.json | `.files[:50] + .exports[:50]` (if in devDeps) |
| jscpd | `npx jscpd src/ --reporters json -o /tmp/jscpd > raw-duplicates.json` | duplicates.json | `.duplicates[:50]` (if installed) |
| dep-cruiser | `npx dependency-cruiser src --include-only "^src" --output-type json > raw-dependencies.json` | dependencies.json | `.summary.violations[:50]` (if installed) |
| stryker | `npx stryker run --reporters json > raw-mutations.json` | mutations.json | `.files \| to_entries[:20]` (only with `--deep`) |

#### 1d. Adaptive Mode Decision
After SCAN completes, count source files analyzed:
```
source_files < 50   → INLINE mode (Claude interprets all tool outputs directly)
source_files >= 50  → AGENT mode (spawn focused agents per concern area)
```
User can override: `--inline` forces inline, `--agents` forces agents.

#### 1e. Incremental Mode
- If `.omc/hygiene/snapshot.json` exists → diff file hashes against current
- Coarse skip: if no `.ts/.js` files changed since last run → skip tsc
- knip, jscpd, dependency-cruiser ALWAYS run full project (need full graph context)
- No snapshot → full scan, save snapshot in SAVE phase

---

### Phase 2: REPORT

**INLINE mode** — Claude does all analysis directly:

#### 2a. Dead Code Analysis
- Read `dead-code.json` (knip output). If knip unavailable: grep for exports, cross-reference imports.
- Verify top-10 findings: Read the actual source file, grep for usages across codebase.
- Filter false positives: framework entrypoints, dynamic imports, barrel re-exports, test utilities.
- Each verified finding: cite file:line, explain why dead, estimate removal blast radius.

#### 2b. Test Quality Analysis
- Find test files: `Glob("**/*.test.{ts,tsx,js}", "**/*.spec.{ts,tsx,js}", "**/__tests__/**")`
- Read test files and classify each:
  - **Effective** — tests behavior, would catch regressions
  - **Weak** — happy path only, no edge cases
  - **Zombie** — no real assertions (`expect(true).toBe(true)`, empty test body)
  - **Broken** — `.skip`, `.todo`, or always-failing
  - **Coupled** — mocks everything, tests implementation details not behavior
- Cross-reference with `complexity.json`: high-complexity files with no tests = critical gap.
- Use `git blame` on `.skip` tests to find how long they've been disabled.

#### 2c. Architecture Overview
- From `dependencies.json`: extract module dependency graph, generate mermaid diagram.
- From `complexity.json`: identify hotspots (top-10 most complex files).
- From directory structure: identify module boundaries, entry points, shared utilities.
- Generate `architecture.md` with mermaid flowchart + complexity heatmap.

#### 2d. Drift Check
- Run `/docs-refresh --scan-only` — compose, don't duplicate.
- Fold drift findings into report as separate "Documentation Drift" section.

#### 2e. Severity Classification

| Severity | Criteria | Action |
|----------|----------|--------|
| **P0** | Type errors (tsc), security critical (semgrep high), broken tests | Fix this sprint |
| **P1** | Dead code (high confidence), unused deps, circular deps, complexity >25 | Plan fix |
| **P2** | Suspected dead code, duplicates >30 lines, complexity 15-25, weak tests | Backlog |
| **P3** | Minor duplicates, style issues, low-priority items | Nice to have |

#### 2f. Health Score
Weighted 0-100: types (25%) + dead code (20%) + tests (20%) + security (15%) + complexity (10%) + deps (10%).
Per-category: 100 = zero findings, 0 = critical issues. Deduct per finding by severity.

**AGENT mode** — spawn 3 focused agents sequentially:

1. **dead-code-hunter** (`agents/dead-code-hunter.md`, model: sonnet)
   - Input: `.omc/hygiene/dead-code.json` + project root path
   - Does: verifies findings, filters false positives, cites file:line
   - Output: verified dead code list with confidence ratings

2. **test-analyst** (`agents/test-analyst.md`, model: sonnet)
   - Input: `.omc/hygiene/complexity.json` + test file glob results
   - Does: reads test files, classifies quality, finds critical gaps
   - Output: test quality report with per-file classifications

3. **hygiene-synthesizer** (`agents/hygiene-synthesizer.md`, model: opus)
   - Input: all `.omc/hygiene/*.json` + agent outputs (1,2) + optional docs-refresh output
   - Does: builds unified report, generates architecture.md, calculates health score
   - Output: `report.md` + `architecture.md` + severity-classified findings

---

### Phase 3: INTEGRATE
- Present `report.md` to user with health score and finding counts.
- For each P0/P1 finding: suggest `/forge --spawn "refactor: [finding description]"`
- User approves/rejects forge task creation. Can `--park` them for later.

### Phase 4: SAVE
- Write all `.omc/hygiene/` files (see Storage Schema below).
- Save `snapshot.json` with current source file SHA-256 hashes.
- Delete `raw-*` files (keep with `--keep-raw` for debugging).
- If previous findings exist: diff and report delta ("Since last run: +2 P1, -3 P2 resolved").

---

## Storage Schema

```
.omc/hygiene/
├── _meta.json           # run metadata, health score, tool list
├── dead-code.json       # knip findings (summarized)
├── duplicates.json      # jscpd clone pairs
├── dependencies.json    # dependency-cruiser violations + graph
├── complexity.json      # scc per-file scores (top-50)
├── tests.json           # test quality classifications
├── security.json        # semgrep findings
├── types.json           # tsc errors (plain text, head -100)
├── architecture.md      # mermaid diagrams, module map, data flow
├── report.md            # human-readable triage (the deliverable)
└── snapshot.json        # SHA-256 per source file for incremental
```

All JSON files carry `_meta: { updated_at, tool, version }` for staleness tracking.

---

## Flags

```
/code-hygiene                    — full pipeline (adaptive mode)
/code-hygiene --module <path>    — scope to specific directory
/code-hygiene --deep             — include mutation testing (stryker, slow)
/code-hygiene --inline           — force inline mode (no agents)
/code-hygiene --agents           — force agent mode
/code-hygiene --keep-raw         — keep raw-* tool output files
```

## Safety
- NEVER auto-fix code. Report only. Fixes go through `/forge --spawn`.
- NEVER delete `.omc/hygiene/` files without user approval.
- If a tool fails: log the error, skip that analysis, note in report as "unavailable".
- On first run: full scan always. Incremental only after snapshot exists.