Stats
Actions
Tags
From dev-skills
Continuous architectural simplification and correctness-by-construction — whole-system recon via parallel agents to find high-leverage opportunities to simplify-and-beautify a structure OR foreclose a whole defect-class by making an illegal state unrepresentable, at the module/layer/concept altitude; steelman each candidate against Chesterton's Fence, then file groomed design-issue(s) for every candidate that clears the gate — autonomously, labeled by validation (no build, no in-session approval gate). Use when invoked as `/kaikaku` (runs one iteration); use `/loop kaikaku` to run it as an autonomous loop. The architectural-altitude sibling of `/kaizen`. Project-agnostic; reads simplicity + beauty + correctness stance from CLAUDE.md and project memory.
How this skill is triggered — by the user, by Claude, or both
Slash command
/dev-skills:kaikakuThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Kaizen (改善) and kaikaku (改革) are the two halves of the lean-improvement vocabulary. Kaizen is *continuous incremental improvement* — many small, local, low-risk fixes; that's `/kaizen`. Kaikaku is *radical, transformative change* — rethinking a structure so a whole **class** dissolves. This is that loop, at architectural altitude.
Kaizen (改善) and kaikaku (改革) are the two halves of the lean-improvement vocabulary. Kaizen is continuous incremental improvement — many small, local, low-risk fixes; that's /kaizen. Kaikaku is radical, transformative change — rethinking a structure so a whole class dissolves. This is that loop, at architectural altitude.
The class that dissolves can be complexity (an over-built structure simplified away) or a defect-class (an illegal state made impossible to write — the poka-yoke / mistake-proofing move). Kaikaku owns both architectural cells: simplify-and-beautify and correctness-by-construction. They are one recon stream, not two skills — the unifying test is leverage (a whole class goes away), not whether the diff is net-shorter. A correctness foreclosure that adds a sum type or a constraint still clears the bar if it makes a class of bug unrepresentable. (If a finding is a single instance to fix, it's a /bughunt target; if it's a few lines to tidy, it's /kaizen. Kaikaku is the structural, whole-class altitude for either axis.)
You run one iteration: perform whole-system architectural reconnaissance, find the highest-leverage opportunity to simplify and beautify the architecture (or to foreclose a defect-class), steelman it against the possibility that the current shape is load-bearing — the complexity is earned, or the defect-class isn't actually reachable — and, if it survives — author and file a groomed design-issue for every candidate that clears the gate, then declare the outcome. Kaikaku does not build and does not stop for approval — it files autonomously: its deliverables are decision-ready proposals, not PRs, and a round routinely yields more than one. /loop kaikaku runs this on an autonomous (long-cadence) loop.
Kaikaku is a /loop-driven iteration, but it does not use the build-cycle skeleton — it grooms a proposal instead of building, so it has no branch / implement / /ship / merge. It owns its whole iteration and ends by declaring its LOOP-OUTCOME to /loop. This file owns:
LOOP-OUTCOME (filed / empty / gate_killed / blocked) that /loop paces on./kaizen and /bughunt plug a target-acquisition step into build-cycle's build spine and ship a PR every productive iteration. Kaikaku changes three things that ripple through the whole iteration:
| build loops (kaizen/bughunt) | kaikaku | |
|---|---|---|
| Altitude | lines, functions, single files | modules, layers, data models, seams, concepts |
| Deliverable | a merged PR | groomed design-issue(s), filed autonomously (the human/fleet builds them) |
| Detection | grep + pattern audit | comprehension — trace dependencies, map a concept's representations |
| Gate | "is this accidental complexity?" | "does the complexity survive a Chesterton's-Fence steelman?" |
| Cadence | one an hour | one a week — "nothing worth proposing" is the normal outcome |
If a finding could be fixed by extracting a helper or deleting a few lines, it's a /kaizen candidate, not a kaikaku one. Route it there and move on.
(The shared iteration invariants — one target at a time, no scope expansion, fail hard, quality-gate-beats-throughput — apply here too; see build-cycle. These are additional.)
/shovel-ready grooming model and the dispatch boundary). Do not open implementation PRs from this loop.CLAUDE.md (especially "Architecture", "Key invariants", "How to approach changes") and any project_* / feedback_* memory before recon. The project's named invariants and stated architecture are the highest-signal map of where complexity is earned vs accidental.Comprehend the architecture, don't grep it. Run a whole-system recon as parallel agents along architectural axes (axes, not subsystems — each agent sees cross-cutting patterns), then an adversarial steelman pass on the top candidates. Under ultracode, author this as a single Workflow (recon fan-out → rank → steelman pipeline); otherwise dispatch parallel Agent calls and run the steelman as a second round.
Read CLAUDE.md's Architecture + Key-invariants sections and the relevant project_* memory. Pass the load-bearing-complexity examples into every agent's prompt as Chesterton's-Fence calibration (e.g. for aios: the two-pool split, the credential-free workflow host, the surface-attenuation lattice, monotonic context). The agents must know what earned complexity looks like in this system before they propose removing any.
dict/Any where a pinned type belongs); validate-don't-parse boundaries (data crossing as a loose shape and re-checked ad-hoc at each use, so one path can skip the check); stale derived state (caches / denormalized columns / "echo" copies with nothing structurally tying them to their source). The fix proposes the chokepoint / type / constraint / parse-at-the-boundary / single-source generation that makes the bad state impossible to write — and it may add structure (a sum type, a smart constructor, a constraint) even when that isn't net-simpler, provided it dissolves a whole class (correctness leverage, not LOC). Recurring /kaizen or /bughunt patches of the same shape across N sites are a symptom — find the structural fix. (See the anti-guard gate in Phase 1.5: a foreclosure makes the state unrepresentable; a guard merely re-checks a state that stays writable — the latter is the belt-and-suspenders the project forbids, not a kaikaku candidate.)steelman_for_status_quo field per observation (the strongest honest case the current shape is load-bearing — for a correctness candidate, that the defect-class isn't actually reachable — grounded in the code).(architectural_leverage × confidence) ÷ (blast × risk); return the top 2–4; quality over quantity; an empty list is a valid honest result.title, locus, current_shape, radiated_complexity, proposed_shape, beauty_gains[], steelman_for_status_quo, blast_radius, migration_cost, risk, architectural_leverage, confidence — plus, for a correctness/defect-class candidate, reachability_evidence (live instance | historical drift | concrete future-edit path) and foreclosure_not_guard (the type/chokepoint/constraint that makes the illegal state unrepresentable, and why it passes the unaware-developer test rather than merely re-checking a still-writable state).Pass --model=<value> through to every agent if it was passed (see build-cycle flags); otherwise omit model: and inherit the session's model.
For the top ~5 ranked observations, spawn an adversarial fence-defender per candidate whose job is to prove the current shape is load-bearing: read the actual code, comments, docstrings, and any issue references at the locus to find why it exists. For a complexity candidate that means proving the complexity earns its keep. For a correctness candidate it means the inverse — proving the defect-class is not actually reachable (already prevented elsewhere, or an illegal state no real path produces), so the foreclosure would be unnecessary belt-and-suspenders. A correctness candidate therefore only survives if it carries reachability evidence: a live instance, historical drift (the invariant has already been violated and patched — git archaeology), or a concrete edit a plausible future change makes that introduces an instance. Each returns a verdict — load_bearing (kill: the complexity is earned, or the defect-class isn't reachable), partially_removable (narrow), or genuinely_removable (survives) — plus the strongest counter-argument, hidden migration costs, and a refined framing. Only candidates that survive their own steelman advance.
Apply the quality-gate principle (don't lower the bar to file something — non-productive is a normal, healthy outcome; see /loop's contract). Apply the gate to each surviving candidate independently and file every one that clears it. A candidate clears only if all are true:
genuinely_removable or partially_removable with a real simplification left after narrowing. load_bearing fails./kaizen candidate; fail the gate and route it there.epic-blast proposal is allowed (it's a design-issue, not a PR) but must say so./bughunt instance-fix at best). The test keys on where the check sits relative to the write path, not on the word "check": a build-time / CI drift-guard that asserts the single source generates all its consumers passes (the copies can no longer be authored independently); a runtime validator that ships even when wrong fails. A live bug found while proving the class is reachable is evidence for the issue, not something to fix in this loop.If nothing clears the gate: report what was found and why each was rejected (especially fence kills — those are valuable architectural confirmations that the complexity is earned), then declare LOOP-OUTCOME: gate_killed (a non-productive iteration; /loop handles idle/cadence). Filing a weak architectural issue is worse than filing none — it erodes trust in the queue.
This is kaikaku's whole build-equivalent — there is no branch/implement/ship/merge. The deliverables are groomed architectural design-issues — one per candidate that clears the gate, filed autonomously.
Structure the issue body as a steelmanned RFC:
path:concept).The deliverable's label depends on how the fence pass resolved, not a fixed default. Don't reflexively stamp every proposal needs-design:
shovel-ready (or the repo's build-queue label). It can enter the build queue; a human glance is welcome but not a gate.partially_removable with a genuine choice of shape, competing migrations, or a load-bearing concern you couldn't fully resolve). Label it needs-design and gate on human direction. Frame the open fork explicitly in the issue.The failure mode to avoid: labeling a verified, converged, standard-pattern change needs-design and parking it behind a human review it doesn't need. (Precedent: the first kaikaku run filed the JSONB-codec proposal needs-design, but its steelman had fully converged — the only open item was verifying the pool-scope assumption; once verified it was reclassified shovel-ready.)
Kaikaku files without stopping for in-session approval; it must be able to run unattended. For every candidate that clears Phase 1.5, file an issue (gh issue create) labeled by its own steelman outcome (see below). The steelman gate — fence + anti-guard + reachability, applied per candidate — is what makes unattended filing safe; the human reviews the filed issues on the tracker, like PRs. Don't present a draft for sign-off, don't pick one and discard the rest, and don't ask which to file: file them all, labeled. Before filing, dup-check the tracker (gh issue list --search) and record each filed target so the next recon excludes it. Report the filed URLs and the count.
End the iteration with the LOOP-OUTCOME line; /loop owns everything after.
filed — one or more design-issues were filed (Phase 4′; report the count and URLs). /loop treats it as productive and re-arms long (filed proposals await human review on the tracker; there's no fast-follow). This is the architectural cadence — nothing to do at 60s.gate_killed — recon found candidates but none survived the fence + gate (Phase 1.5). Non-productive; /loop idles. A fence-kill is a valuable confirmation that the complexity is earned — report it.empty — recon surfaced nothing at architectural altitude. Non-productive.blocked — a genuine inability to proceed (e.g. the issue tracker is unreachable). Kaikaku does not block for approval or to choose among candidates — it files autonomously and labels human-decision cases needs-design (see Escalation). blocked should be rare.Autonomous filing is the default — there is no approval mode to opt out of, so --auto is redundant (accepted as a harmless no-op for back-compat / /loop passthrough; it never meant "merge" — there is no merge). The loop flags (--once, --idle-count, --drain) are /loop's.
The per-candidate quality gate is the throttle — not a per-iteration cap, not a human approval step. File everything that clears it; withholding a validated candidate to avoid "filing too much" is the throw-away-work failure mode. But the bar is real and stays high: don't file a candidate that fails the fence / anti-guard / reachability test just to produce output, and never re-surface a pending or rejected target. If needs-design proposals genuinely pile up unreviewed, that's the human's cue to triage the tracker — not kaikaku's cue to stop surfacing validated structural problems.
(Additive to build-cycle's shared boundaries.)
/kaizen target — route it there.Kaikaku runs unattended, so it does not stop to ask the user. The cases that would once have been an in-session question become a label + explicit framing in the issue, for the human to resolve on the tracker:
partially_removable with a load-bearing core), or the proposal touches a public API / wire format / data model other systems depend on → file it needs-design, with the open fork / blast stated plainly in the Open-questions section. Don't decide it, and don't withhold it.The only genuine blocked is an inability to act at all (tracker unreachable, auth failure). When a candidate is uncertain, the move is file it needs-design — not ask. A labeled issue the human triages costs less than a stalled loop, and never throws away the work.
npx claudepluginhub eumemic/claude-plugins --plugin dev-skillsGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.