kaizen-codebase

name

kaizen-codebase

description

Run one autonomous codebase-improvement pass on the current repo. Self-discover the single highest-leverage, low-risk improvement (architecture, tech debt, dead code, test gaps, simplification) and either ship it end-to-end as a non-draft PR for /process-prs to review and verdict, or, when it needs human judgment, file one needs-triage issue. Does exactly one thing then stops, so it composes with /loop for recurring improvement (e.g. `/loop /kaizen-codebase` or `/loop 1d /kaizen-codebase`). The self-directed sibling of /implement-issues: same shipping discipline, but it finds its own work instead of grabbing a ready-for-agent issue. Use when the user wants to continuously or periodically improve a repository, asks to "improve the codebase", set up a recurring code-quality agent, or run one improvement iteration.

Kaizen codebase (one pass)

One bounded improvement per invocation, then stop. Compose with /loop for recurrence (/loop /kaizen-codebase, /loop 1d /kaizen-codebase). Never schedule yourself; /loop owns pacing.

The self-directed sibling of /implement-issues: same shipping discipline, but it discovers its own candidate instead of grabbing a ready-for-agent issue.

self-discovery  ->  kaizen-codebase  ->  process-prs
                    (non-draft PR)       (review + recommend-* verdict, you merge)
                         \-> needs-triage issue -> maintainer / triage (uncertain path)

Contract

• Exactly one outcome per pass: one non-draft PR, OR one needs-triage issue, OR a clean no-op.
• Confident + surgical → non-draft PR. Uncertain / needs a human call → needs-triage issue. Nothing worthwhile → exit. An empty pass is a success, not a failure; never manufacture churn to justify a run.
• Never merge, never force-push without --force-with-lease, never push to the base branch.

Rails

• Never merge. The PR is opened for review; merging stays the maintainer's hand (and /process-prs's verdict is a recommendation, not an action).
• Never ship a guess. If the candidate proves uncertain or cannot reach green mid-implementation, abort and escalate (§4), never open a speculative PR.
• The finalize gates are mandatory, not optional. /review-fix and /recommit run on every change before the PR opens, whatever its size, and /verify runs whenever the change is behavioral and a smoke is practical. "It's a one-line / test-only / obviously-correct change" is not grounds to skip /review-fix or /recommit, and a manual diff read is not a substitute for /review-fix. That rationalization is exactly how unreviewed AI-slop lands in a PR. Skipping a gate that applies is a process violation; if one genuinely cannot run, say so explicitly in the report rather than silently dropping it.
• Never touch clean-room / relicensing work. Self-discovery must skip any module under active clean-room or relicensing work, detected via whatever signal the repo uses (open relicensing issues/PRs, an ADR / CONTEXT.md marker, a path convention). Reading the prior implementation contaminates that work; this is a hard boundary, not a preference.
• Every issue comment starts with a disclaimer: > *This was generated by AI during a kaizen pass.*.

0. Preflight

• Abort if not a git repo.
• git fetch; identify the base branch (main/master); ensure the local base is current.
• Work happens in an isolated worktree, so a dirty main checkout is fine: don't abort on it and don't touch the user's WIP.
• Detect optional substrate, use what exists and skip what doesn't: CONTEXT.md, docs/adr/, triage labels, a GitHub remote. Repos like gdown/imgviz may have none of these, and that is fine.

1. Pick ONE candidate

• Read any ADRs + CONTEXT.md first so you don't re-litigate settled decisions.
• List open PRs and issues; skip anything already proposed or in flight.
• Skip any module under active clean-room / relicensing work (rail above).
• Explore broadly with subagents (architecture depth, tech debt, dead code, test gaps, simplification) to keep your context clean. Choose the single highest-leverage, lowest-risk candidate. Apply the deletion test and prefer surgical seams over sweeping rewrites.

2. Classify the candidate

File a needs-triage issue (do NOT write code) when ANY holds:

• needs a product or architecture decision with more than one reasonable answer
• large blast radius (public API, serialized/on-disk format, many call sites)
• contradicts or would amend an existing ADR
• cannot be proven correct by cheap or existing tests
• requirements are ambiguous or depend on intent only the maintainer knows
• the change is risky or hard to reverse

Otherwise ship a non-draft PR, but only when ALL hold: one cohesive surgical change, low-risk, reversible, and verifiable green (tests + lint) before/after.

When in doubt, escalate to an issue. Shipping an uncertain change unattended is the failure mode this skill exists to avoid.

3a. Ship it (confident path)

1. Claim it: create the conventional branch in an isolated worktree, branching from the fetched base so in-flight work never leaks into the diff: git wt <type>/<slug> origin/<base>, where <type> is the conventional-commit type for the change (refactor, fix, chore, test, perf, docs) and <slug> is derived from the change itself (there is no issue number). Work entirely in the worktree.
2. Apply the minimal change. Read the code before editing it; touch only what the change requires; respect any ADRs / CONTEXT.md.
3. Get the full test suite and lint/typecheck green.
4. /review-fix to a clean round (reviewers -> fixes -> re-verify; stop on a clean round or on oscillation). Invoke the skill; a hand review does not count.
5. /recommit into a clean, logical commit sequence.
6. /verify whenever the change is behavioral and a smoke is practical (the skill picks the method per project type). Skip it only when the change is non-behavioral (e.g. test-only or docs) or no smoke is practical, and note the reason in the report.
7. /make-pr: push and open a non-draft PR (the branch is already conventional, so no /make-branch rename is needed), assigned to yourself (--assignee @me), and no verdict label (/process-prs applies that during its independent review). /make-pr drafts PRs it opens autonomously by default, so pass an explicit ready (non-draft) request to override that; otherwise the PR lands as a draft and /process-prs's non-draft queue never picks it up.
8. If a load-bearing decision was made or a candidate was rejected for a reason a future pass would need, record it as an ADR (or in CONTEXT.md) so the loop doesn't repeat itself.

3b. Escalate (uncertain path)

• Ensure the needs-triage label exists (/setup-github-labels, or gh label create needs-triage if missing).
• Dedup against open issues, then open ONE issue: the candidate, why it needs a human, the options/tradeoffs, and the affected files. Assign the repo owner (--assignee @me) and apply needs-triage. The maintainer (or the interactive /triage skill) then decides ready-for-agent vs ready-for-human vs wontfix; kaizen only parks the unevaluated belief. (/process-issues does not re-pick needs-triage, so the escalation waits on a human, not the agent loop.)
• If there is no GitHub remote, append the candidate to a local docs/kaizen-codebase-backlog.md instead, and say so.

4. Abort mid-flight

If a confident-path candidate proves uncertain mid-implementation, or the work cannot reach green:

1. Remove the worktree and branch with git wt -d <type>/<slug> (leaves no cruft).
2. Fall back to §3b: file ONE needs-triage issue naming the specific blocker (the ambiguous requirement, the failing behavior, what a human must decide) and what the pass learned.

No PR. The aborted candidate re-enters the pipeline rather than dying silently.

Report

End with one line for /loop: the PR url, the needs-triage issue url, or "no high-leverage change this pass." If a finalize gate was skipped or could not run, note which and why alongside that line.

Composition

Shares the finalize discipline of /implement-issues (worktree, /review-fix, /recommit, /verify, non-draft PR) but sources its own work. Confident work becomes a non-draft PR that /process-prs reviews and verdicts; uncertain work becomes a needs-triage issue the maintainer (or /triage) evaluates, since /process-issues parks needs-triage and never re-picks it. Neither ever merges.