kaizen-codebase - SKILL.md Agent Skill

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)

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.
Apply the minimal change. Read the code before editing it; touch only what the change requires; respect any ADRs / CONTEXT.md.
Get the full test suite and lint/typecheck green.
/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.
/recommit into a clean, logical commit sequence.
/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.
/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.
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:

Remove the worktree and branch with git wt -d <type>/<slug> (leaves no cruft).
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.