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.

kaizen-codebase

NPX Install

Tags

SKILL.md Content