Kaizen

Usage

/core-skills:kaizen [further user instructions]

Goal

Step back from individual changes and assess the whole system. Surface 3-5 high-value findings that would otherwise accumulate silently.

Exclude explicitly experimental or scratch areas (e.g. an experimental/ directory).

How It Works

Spawn one subagent per dimension in parallel, then reconcile their findings into a single prioritised report.

Step 1: Spawn Investigators

Launch one background Agent per dimension. Use model: "opus" for each. Each agent should:

• Read CLAUDE.md for project rules and conventions
• Investigate its dimension thoroughly
• Return findings (if any) with evidence

Dimensions:

1. Domain correctness drift — Read CLAUDE.md for domain-specific correctness rules. Check whether recent code follows them. Look for new patterns that should be guarded but aren't yet covered by existing rules or architecture tests. If you find one, recommend adding a rule or test.
2. Convention drift — Read CLAUDE.md. Sample recent code across packages/modules. Look for: same concept implemented different ways, domain terminology inconsistency (grep for synonyms), CLAUDE.md rule violations, AI-generated patterns (over-engineering, defensive try/except on infallible code, generic naming, unnecessary abstractions). Quantify: "N of M sampled files follow the convention" is more useful than "some files don't follow it."
3. Architecture and design health — Use /core-skills:software-design (red flags checklist), /core-skills:ddd (module naming, bounded contexts), /core-skills:clean-code (structural coupling smells), and /core-skills:goos (adapter wrapping, listening-to-the-tests diagnostics) as review lenses when relevant. Check dependency direction: any new imports that violate the intended DAG? Verify that testing/ subpackages also respect the DAG — fakes and helpers must not invert dependencies that production code enforces. Modules that have grown large or taken on multiple responsibilities? Change coupling: files that always change together across module boundaries (use git log --name-only)? Whether current module boundaries still make sense?
4. Test suite health — Any new skipped tests? Unexpectedly slow tests? Assertion-free tests (AST scan or grep)? Source modules without test files? Core logic missing edge case tests? Tests that test mocks instead of behaviour?
5. Task hygiene — Scan the project's task store (e.g. a tasks/ directory; skip this dimension if the project has none): stale tasks (status != done/rejected, no activity 90+ days), status lies (in-dev but no recent commits), epic consistency (subtask statuses match epic table), reference integrity (file paths and symbols still exist), duplicates, bloat (>20 drafts). Also check commit SHAs referenced in task files: verify each is reachable on a branch (git branch --contains <sha>) — dangling SHAs mean the task file wasn't updated after a squash/rebase and should be rewritten to point at the surviving commit(s).
6. Documentation health — CLAUDE.md accuracy (extract commands, verify they work, cross-reference identifiers). Architecture test currency. Decision records for recent architectural changes. Doc-code drift (compare last-modified dates, verify identifiers still exist).
7. Dependency health — Known vulnerabilities (CVEs). Version staleness (flag major version lag). Archived or unmaintained direct dependencies (no commits in 12+ months). Flag but don't prescribe — dependency decisions need human judgment.
8. Dead artifacts — Modules with no imports (grep/AST). TODO/FIXME/HACK comments older than 6 months (git blame). Stale branches. Test files for code that no longer exists.

Step 2: Reconcile

After all agents complete, collect their findings. First drop any that are already settled — captured in the task pipeline (a task file, including status: later, or a backlog one-liner) or recorded in a decisions doc (e.g. docs/decisions.md § Accepted / Won't-Fix) with an unfired revisit trigger (see Anti-Patterns). Then prioritise what remains by:

• Severity — what's the worst that happens if ignored?
• Change frequency — is this in code that changes often?
• Domain criticality — is this on the critical path of the system?

Keep findings that score high on at least two. Cap at 5 findings total. Overflow to "Below threshold."

Output Format

### Verdict

[One sentence: overall health direction.]

### Findings

[Up to 5 findings, each with evidence and a concrete action.]

### Below threshold

[Uncertain or lower-priority findings.]

### CLAUDE.md feedback

[Any findings that suggest a new rule or a stale existing rule.]

Anti-Patterns

• Flagging things already caught by the project's check command
• Style preferences not in CLAUDE.md
• Reporting the same finding repeatedly without escalation or acceptance
• Flagging an issue already captured anywhere in the task pipeline — a backlog one-liner (an unborn later task) or a task file (especially status: later). Capture is acknowledgement: it's parked, not a fresh finding. Re-surface only with new evidence that severity changed, and then as an escalation on the existing item.
• Re-raising something settled in the project's decisions doc as accepted / won't-fix — a deliberate not-to-do; only re-open if its stated revisit trigger has fired.
• Vague concerns without specific evidence