kaizen-codebase

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Kaizen codebase (one pass)

Kaizen代码库（单次操作）

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)

每次调用仅执行一项有限的改进，然后停止。可与

/loop

组合实现重复执行（

/loop /kaizen-codebase

、

/loop 1d /kaizen-codebase

）。请勿自行安排执行节奏；

/loop

负责控制执行频率。

它是

/implement-issues

的自主式姊妹技能：遵循相同的交付规范，但会自行发现改进候选项，而非抓取标记为

ready-for-agent

的工单。

自主发现  ->  kaizen-codebase  ->  process-prs
              (非草稿PR)           (审核 + recommend-* 结论，由你合并)
                   \-> needs-triage工单 -> 维护者 / 分流处理（路径不确定）

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.

每次操作仅产生一种结果：一个非草稿PR，或一个
```
needs-triage
```
工单，或无操作结束。
有把握且精准的修改→非草稿PR。不确定/需要人工决策→
needs-triage
工单。无有价值的改进→退出。无操作的执行是成功的，而非失败；绝不能为了凑数而制造无意义的变更。
绝不合并代码，绝不使用
```
--force-with-lease
```
以外的强制推送，绝不推送到基础分支。

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.*

绝不合并。 PR仅用于提交审核；合并操作由维护者负责（
```
/process-prs
```
的结论仅为建议，而非执行操作）。
绝不提交猜测性修改。 如果候选改进项存在不确定性，或在实现过程中无法通过测试，应中止操作并升级处理（第4节），绝不能提交推测性PR。
最终检查环节是强制要求，而非可选。 在PR提交前，无论变更大小，都必须运行
```
/review-fix
```
和
```
/recommit
```
；如果变更涉及行为逻辑且可进行快速验证，则必须运行
```
/verify
```
。“这只是一行代码/仅修改测试/显然正确的变更”不能成为跳过
```
/review-fix
```
或
```
/recommit
```
的理由，人工查看差异也不能替代
```
/review-fix
```
。这种合理化正是未经审核的AI垃圾代码进入PR的原因。跳过适用的检查环节属于流程违规；如果确实无法运行某个检查，应在报告中明确说明原因，而非悄悄跳过。
绝不触碰clean-room/重许可相关工作。 自主发现过程必须跳过任何正在进行clean-room或重许可工作的模块，可通过仓库中的信号识别（如已打开的重许可工单/PR、ADR或
```
CONTEXT.md
```
标记、路径约定）。参考现有实现会污染这类工作；这是硬性边界，而非偏好。
每个工单评论开头必须包含免责声明：
```
> *This was generated by AI during a kaizen pass.*
```

0. Preflight

0. 预检查

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.

如果不是git仓库，中止操作。
执行
```
git fetch
```
；识别基础分支（
```
main
```
/
```
master
```
）；确保本地基础分支是最新的。
操作在独立的工作树中进行，因此主分支的本地检出有未提交内容也无妨：无需因此中止操作，也不要触碰用户的在做工作（WIP）。
检测可选的辅助文件，使用已存在的文件，跳过不存在的：
```
CONTEXT.md
```
、
```
docs/adr/
```
、分流标签、GitHub远程仓库。像gdown/imgviz这类仓库可能没有这些文件，这是正常的。

1. Pick ONE candidate

1. 选择一个候选改进项

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.

首先阅读所有ADR和
```
CONTEXT.md
```
，避免重复讨论已确定的决策。
列出所有已打开的PR和工单；跳过任何已提出或正在处理的内容。
跳过任何正在进行clean-room/重许可工作的模块（见上述规则）。
通过子代理进行全面探索（架构深度、技术债务、死代码、测试缺口、简化优化），保持认知清晰。选择单个最高价值、最低风险的候选改进项。应用删除测试，优先选择精准的修改而非大范围重写。

2. Classify the candidate

2. 分类候选改进项

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.

当满足以下任一条件时，提交一个**

needs-triage

工单**（请勿编写代码）：

需要产品或架构决策，且存在多个合理选项
影响范围大（公共API、序列化/磁盘存储格式、多个调用点）
与现有ADR矛盾或需要修改现有ADR
无法通过低成本或现有测试证明正确性
需求模糊，或依赖只有维护者才知道的意图
变更存在风险或难以回滚

否则提交一个非草稿PR，但必须同时满足以下所有条件：单一连贯的精准变更、低风险、可回滚、修改前后测试+代码检查均通过（绿色状态）。

如有疑问，升级为工单。提交不确定的无人值守变更是本技能旨在避免的失败模式。

3a. Ship it (confident path)

3a. 交付变更（有把握路径）

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.

认领任务： 在独立工作树中创建符合规范的分支，基于拉取的基础分支创建，确保正在进行的工作不会泄露到差异中：
```
git wt <type>/<slug> origin/<base>
```
，其中
```
<type>
```
是变更的规范提交类型（
```
refactor
```
、
```
fix
```
、
```
chore
```
、
```
test
```
、
```
perf
```
、
```
docs
```
），
```
<slug>
```
由变更内容衍生（无工单号）。完全在工作树中进行操作。
应用最小化变更。编辑前先阅读代码；仅修改变更所需的部分；遵守所有ADR/
```
CONTEXT.md
```
的要求。
确保完整测试套件和代码检查/类型检查均通过（绿色状态）。
运行
```
/review-fix
```
直到完成一轮干净的审核（审核→修复→重新验证；直到审核通过或出现循环时停止）。必须调用该技能；人工审核不算数。
运行
```
/recommit
```
生成清晰、逻辑连贯的提交序列。
如果变更涉及行为逻辑且可进行快速验证，则运行
```
/verify
```
（该技能会根据项目类型选择验证方法）。仅当变更不涉及行为逻辑（如仅修改测试或文档）或无法进行快速验证时才可跳过，并在报告中说明原因。
运行
```
/make-pr
```
：推送分支并打开一个非草稿PR（分支已符合规范，无需运行
```
/make-branch
```
重命名），指定自己为负责人（
```
--assignee @me
```
），且不添加结论标签（
```
/process-prs
```
会在独立审核时添加该标签）。
```
/make-pr
```
默认会将自主打开的PR设为草稿，因此需要传递明确的就绪（非草稿）请求来覆盖默认设置；否则PR会以草稿形式提交，
```
/process-prs
```
的非草稿队列永远不会处理它。
如果做出了关键决策，或因未来操作需要注意的原因拒绝了某个候选项，请将其记录为ADR（或写入
```
CONTEXT.md
```
），避免循环执行时重复处理。

3b. Escalate (uncertain path)

3b. 升级处理（不确定路径）

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.

确保

needs-triage

标签存在（运行

/setup-github-labels

，如果不存在则运行

gh label create needs-triage

）。

与已打开的工单去重，然后打开一个工单：说明候选改进项、需要人工介入的原因、可选方案/权衡点以及受影响的文件。指定仓库所有者为负责人（
```
--assignee @me
```
）并添加
```
needs-triage
```
标签。维护者（或交互式
```
/triage
```
技能）会决定标记为
```
ready-for-agent
```
、
```
ready-for-human
```
还是
```
wontfix
```
；kaizen仅将未评估的改进项暂存。（
```
/process-issues
```
不会重新处理
```
needs-triage
```
工单，因此升级后的工单需等待人工处理，而非由代理循环处理。）
如果没有GitHub远程仓库，将候选改进项追加到本地的
```
docs/kaizen-codebase-backlog.md
```
中，并在报告中说明。

4. Abort mid-flight

4. 中途中止

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.

如果原本有把握的候选改进项在实现过程中出现不确定性，或工作无法通过测试：

使用
```
git wt -d <type>/<slug>
```
删除工作树和分支（不留下任何残留）。
回到第3b节：提交一个
```
needs-triage
```
工单，说明具体的阻塞点（模糊的需求、失败的行为、需要人工决策的内容）以及本次操作所学到的信息。

不要提交PR。中止的候选改进项会重新进入处理流程，而非无声消失。

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.

结尾添加一行供

/loop

使用的内容：PR链接、

needs-triage

工单链接，或“本次操作无高价值变更”。如果跳过了某个最终检查环节或无法运行该环节，请在该行旁边注明具体环节和原因。

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.

与

/implement-issues

遵循相同的最终检查规范（工作树、

/review-fix

、

/recommit

、

/verify

、非草稿PR），但自行寻找工作内容。有把握的工作会成为非草稿PR，由

/process-prs

审核并给出结论；不确定的工作会成为

needs-triage

工单，由维护者（或

/triage

技能）评估，因为

/process-issues

会暂存

needs-triage

工单且不会重新处理。两者都不会执行合并操作。