kaizen

name

kaizen

description

One iteration of accidental-complexity reduction — audit the codebase against craftsmanship principles via parallel agents, and file a groomed cleanup-issue for every candidate that clears the gate. Does NOT implement or ship — specialized dev processes pick up the filed issues. Use when invoked as `/kaizen` (runs one iteration); use `/loop kaizen` to run it as an autonomous loop. The instance/tidy-altitude sibling of `/kaikaku`. Project-agnostic; reads simplicity heuristics from CLAUDE.md and project memory.

/kaizen — one audit-and-file simplification iteration

You run one iteration: scour the codebase for accidental complexity and file a groomed cleanup-issue for every candidate that clears the gate — then declare the outcome. You do not implement the simplification or open a PR: kaizen is a find-and-file producer; the specialized dev processes (the shovel-ready queue / autodev / a human) implement the filed issues. /loop kaizen runs this on an autonomous loop.

This skill is a thin specialization over the shared file-cycle skeleton. Read dev-skills:file-cycle for the shared iteration machinery (labeling by validation, autonomous multi-output filing, dup-check, declaring the outcome). Looping — cadence, idle escalation, re-arming — is owned by /loop. This file owns:

• Phase 1 — target acquisition (parallel-agent codebase audit).
• Phase 1.5 — the kaizen-specific quality gate.
• Phase 4′ body — the cleanup-issue template file-cycle files.

(Altitude note: kaizen is the instance / few-lines-to-tidy altitude. A finding that dissolves a whole class by changing a structure is a /kaikaku candidate; a latent correctness defect is a /bughunt candidate. All three file — they differ only in altitude and gate.)

Specialization-specific invariants

(See file-cycle for the shared invariants — multi-output, autonomous filing, quality-gate-beats-throughput, label-don't-block. These are additional.)

• Accidental complexity only — defensive guards for model mistakes, fallbacks, retry loops that hide errors, multi-stage corrective pipelines, backwards-compat shims, near-duplicate code paths, state machines encoded across log scans. Don't propose rewriting legitimately complex domain logic that earns its lines.
• No new features, no behavior changes — kaizen is structural. If the audit surfaces a real bug, it's a /bughunt candidate, not a kaizen cleanup — note it and move on.
• Propose, don't implement — kaizen's deliverable is a decision-ready cleanup-issue, not a diff. Describe the target, the simpler form, and the expected shape of the change; the consumer makes it.
• Respect the project's stance — read CLAUDE.md and any feedback_* memories before picking. Project-specific anti-patterns weight your search heavily.

Phase 1 — Parallel-agent audit

Dispatch multiple agents in parallel (single message, multiple Agent tool calls) covering different dimensions of craftsmanship. Each agent returns ranked findings; you synthesize.

Read the simplicity stance first

Before launching agents, read CLAUDE.md (project root) and any feedback_* / project_* memory files about complexity, style, simplicity priorities. Pass the relevant excerpts into each agent's prompt so their findings are calibrated to this project's bar.

Dispatch agents

Pick 4–6 dimensions appropriate to the codebase. The standard set:

1. Project invariants — read CLAUDE.md's invariants/anti-patterns sections. Find code that maintains the same invariant differently across sites, or violates it subtly.
2. Structural duplication — search for near-twin function names (process_X + process_X_v2, defer_X + defer_retry_X), multi-site inlined state machines, copy-paste with slight variation.
3. File-size + smell-words — top-N largest files; grep for fallback, legacy, compat_, TODO, XXX, HACK, FIXME, workaround, recover, repair, reconcile. Each match is a candidate, not a verdict.
4. Broad excepts and error swallowing — except Exception: blocks that don't re-raise; symptom-suppression guards; "fail soft" handlers in places where "fail hard" is the project's stance.
5. Multi-stage corrective pipelines — modules whose docstrings advertise "replaces X + Y + Z with a single function". Sometimes load-bearing for crash recovery; sometimes a state machine fighting the architecture.
6. Craftsmanship principles — assess against: Clean (dead code, unclear purpose), Simple (over-engineering, clever solutions), Comprehensible (poor naming, high cognitive load), Well-Factored (mixed responsibilities, large functions), Single Responsibility (multi-purpose units), Testable (hard-to-test code, side effects), DRY (missed abstractions).

Each agent's prompt should include

• The relevant CLAUDE.md excerpts and feedback_* memory excerpts so calibration matches the project.
• A rubric: rank findings by (impact × confidence) ÷ blast-radius, return top 3–5.
• The instruction: "Don't fix anything; just identify and rank."
• A length cap (under 400 words per response) so synthesis stays manageable.
• A clear deliverable: ranked list with file:line references and a one-line rationale per finding.

Use subagent_type: general-purpose for the audit agents. They run parallel via a single message with multiple Agent tool calls. If invoked with --model=<value> (see file-cycle flags), include model: "<value>" on each Agent call so every audit subagent runs on the chosen Claude generation; otherwise omit model: and let them inherit the session's model.

Synthesize

Collect the ranked lists. Merge into a single global ranking — same target appearing across multiple agents amplifies its score. Rank by: cross-agent corroboration first (multiple dimensions flagging it = signal), then per-dimension severity, then blast radius (smaller wins ties).

Read each candidate's file in detail

Before filing, read the actual file (not just the agent's excerpt) for every candidate you intend to file. Confirm:

• Does this complexity earn its lines, or is it accidental?
• Is there a near-twin elsewhere that could be unified?
• Does the same logic appear inline in N call sites without a helper?
• Does CLAUDE.md explicitly forbid the pattern?

This read is what separates a filed cleanup-issue from a finder's guess — the consumer implements from your issue, so the analysis must be real.

If the audit produces no candidate at the depth applied, declare LOOP-OUTCOME: empty (file-cycle Phase 7) and end the iteration.

Phase 1.5 — Kaizen quality gate

Apply file-cycle's quality-gate principle, per candidate — kaizen is multi-output: every candidate that clears the gate is filed. A candidate clears only if all are true:

1. Unambiguously accidental. The complexity does NOT earn its lines on second read. "Maybe load-bearing for crash recovery" or "might be intentional, hard to tell" fails the gate.
2. Net deletion expected. A cleanup whose proposed change adds more lines than it removes is a yellow flag — it's probably an abstraction posing as a simplification. Borderline net-positive cases need explicit justification or they fail the gate.
3. Not contentious. If two equally-reasonable people would disagree on whether the code is better after the change, fail the gate. Kaizen files uncontroversial wins. (A contentious refactor is dropped, not filed with a hedge — that's the gate_killed path, or a /kaikaku candidate if it's really a structural call.)
4. Bounded blast radius. A simplification that touches > ~5 files OR crosses module boundaries fails the kaizen gate — that altitude is a /kaikaku candidate. Route it there and move on.

If a candidate is a clean simplification but has one genuine open sub-decision (a naming choice, a which-of-two-forms question), don't drop it and don't ask — file it needs-design with the fork stated (file-cycle Escalation). A contentious-whether-to-do-it-at-all candidate is different: that fails the gate.

If no candidate clears the gate: report what was found and why each was rejected, then declare LOOP-OUTCOME: gate_killed (the audit wasn't empty, but the iteration is non-productive — /loop treats it as an idle increment). Don't file a borderline cleanup just because the audit produced output.

Phase 4′ — The cleanup-issue (file-cycle files it)

For each candidate that clears Phase 1.5, author a cleanup-issue with the body below; file-cycle (Phase 4′) owns the labeling, dup-check, autonomous filing, and outcome declaration.

• Current shape — what the code does now, with the concrete loci (file:line), and the near-twin(s) / inline-repeats if any.
• The accidental complexity — precisely what's incidental (not domain-earned): the duplication, the dead path, the fallback, the mis-placed responsibility.
• Proposed simplification — the simpler form that does the same job (call the existing helper, delete the shim, collapse the twins, inline-then-remove). Concrete enough to implement from.
• Expected LOC delta — the net-deletion estimate (kaizen expects a negative). Flag and justify any net-positive.
• Blast radius — files touched, and the regression bar (existing tests must still pass; note any fossil tests to delete alongside).

Label

• A clean, uncontroversial cleanup with a concrete plan → the project's build-queue label (shovel-ready).
• A clean cleanup with one open sub-decision → needs-design, fork stated.

(See file-cycle Phase 4′ for the labeling rule and the file / dup-check / record / report steps.)

Specialization-specific boundaries

(Additive to file-cycle's shared boundaries.)

• Don't file a target the user has already rejected (a previously-closed issue within memory) — record filed/rejected targets so the next audit excludes them.
• Don't file a contentious refactor. Kaizen files present-tense, uncontroversial simplicity; a genuinely-arguable change fails the gate.
• Don't implement or open a PR. kaizen files; the consumer simplifies.
• Don't speculate on "future flexibility" in issue bodies.

Specialization-specific escalation

file-cycle's "label, don't block" governs — kaizen runs unattended and does not stop to ask. The cases that once were questions become labels:

• A candidate straddling real-vs-accidental complexity that you couldn't resolve on a close read → don't file it; it fails the "unambiguously accidental" gate (gate_killed). Kaizen does not file coin-flips.
• A clean cleanup with a genuine open sub-decision (naming, which form) → file needs-design, fork stated.

When in doubt about whether the complexity is earned, drop it — a wrong-target cleanup-issue teaches the consumer to distrust the queue.