merge-ready

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Merge ready

可合并状态准备

Drive the current work to the point where the only remaining step is Ben's own review and merge. The deliverable is a pushed branch with a clean

pnpm ci:check

, checkpoint commits along the way, and an open PR with a high-level description plus review instructions.

Never merge the PR. Ben always reviews last.

将当前工作推进至仅需Ben自行审核和合并的阶段。交付成果为已推送的分支（需通过

pnpm ci:check

检查）、过程中的checkpoint提交，以及一份包含高层级描述和审核指南的已开启PR。

切勿合并PR。Ben始终进行最终审核。

0. Figure out the starting point

0. 明确起始点

This skill composes with feature work — it is not only a review pass:

Invoked alongside a build request ("build X, make it merge-ready"): implement the feature/fix first, committing as you go, then continue below. The review phases cover all changes on the branch vs
```
origin/main
```
, not just the last edit.
Invoked on existing work ("make this branch merge-ready"): start directly at step 1. The scope is
```
git diff origin/main...HEAD
```
plus anything uncommitted.

此流程可与功能开发配合使用——它并非仅作为审核环节：

随构建请求触发（“构建X并使其可合并”）：先实现功能/修复，边开发边提交，再继续执行以下步骤。审核阶段覆盖分支相对于
```
origin/main
```
的所有变更，而非仅最后一次编辑。
针对已有工作触发（“将此分支设为可合并状态”）：直接从步骤1开始。范围为
```
git diff origin/main...HEAD
```
的内容加上所有未提交的变更。

1. Sync with main

1. 与主分支同步

```
git fetch origin main
```
. If the branch is behind, merge
```
origin/main
```
in and resolve conflicts (favor main's version for code this branch didn't intentionally change).
Checkpoint: commit the merge before starting review, so conflict resolution is auditable separately from review fixes.

执行
```
git fetch origin main
```
。若分支落后于主分支，合并
```
origin/main
```
并解决冲突（对于此分支未有意修改的代码，优先采用主分支版本）。
Checkpoint： 在开始审核前提交合并结果，使冲突解决过程可单独追溯，与审核修复区分开。

2. Multi-axis subagent review

2. 多维度子代理审核

Spawn independent review subagents in parallel, one per axis, each given repo access and the complete branch scope:

committed changes:
```
git diff origin/main...HEAD
```
staged changes:
```
git diff --cached
```
unstaged changes:
```
git diff
```
untracked files:
```
git status --short
```
, followed by reading every in-scope untracked file

Do not let an uncommitted or newly created file escape review merely because it is absent from

origin/main...HEAD

Unnecessary complexity — thin wrappers, needless indirection, single-use abstractions, defensive guards for impossible states, dead config. This codebase deliberately stays simple.
Security — authz on new endpoints (org/project scoping), SSRF, injection, secrets handling, anything user-input-shaped reaching D1/R2/external APIs.
Billing & metering — ways a user could trigger DataForSEO/provider spend without being metered, charged-but-failed paths, retry/loop amplification, endpoints with unexpectedly high per-call user cost. Credits are billed via Autumn; uncounted spend is a revenue leak.
Library & project idioms — TanStack (Router/Query/Start) used idiomatically; patterns match how the rest of the codebase already does it (shared application/provider error boundaries, db/schema conventions, existing component patterns). Flag novel patterns where an established one exists.
Vibe-coded cruft — leftover scaffolding, stale comments narrating the edit history, console.logs, TODO-without-owner, copy-pasted near-duplicates, files/exports nothing uses.

Each reviewer returns findings with file:line, severity (

blocker

should-fix

nitpick

), and a one-line rationale. Tell reviewers explicitly: this is an early-stage product — do not chase theoretical edge cases; mark anything debatable as

nitpick

并行生成独立的审核子代理，每个子代理对应一个维度，均授予仓库访问权限并覆盖分支的完整范围：

已提交变更：
```
git diff origin/main...HEAD
```
暂存变更：
```
git diff --cached
```
未暂存变更：
```
git diff
```
未追踪文件：
```
git status --short
```
，随后读取所有范围内的未追踪文件

切勿因未提交或新创建的文件未出现在

origin/main...HEAD

中，就使其逃过审核。

不必要的复杂度——冗余包装、无意义的间接层、单次使用的抽象、针对不可能状态的防御性判断、无用配置。此代码库刻意保持简洁。
安全性——新端点的授权（组织/项目范围）、SSRF、注入攻击、密钥处理、任何用户输入类数据流向D1/R2/外部API的情况。
计费与计量——用户可能触发DataForSEO/服务商费用但未被计量的途径、已收费但执行失败的流程、重试/循环导致的费用放大、单次调用用户成本异常高的端点。费用通过Autumn结算，未统计的支出属于收入流失。
库与项目惯例——TanStack（Router/Query/Start）的使用符合惯例；模式与代码库其余部分的现有方式一致（共享应用/提供者错误边界、数据库/schema约定、现有组件模式）。若存在既定模式却使用了新模式，需标记出来。
风格冗余内容——残留的脚手架代码、叙述编辑历史的过时注释、console.log、无责任人的TODO、复制粘贴的近似重复代码、无任何引用的文件/导出。

每个审核子代理返回的结果需包含文件:行号、严重程度（

blocker

should-fix

nitpick

）以及一行理由。需明确告知审核子代理：这是早期阶段的产品——无需纠结理论上的边缘情况；任何有争议的内容标记为

nitpick

。

3. Verify findings — never blindly accept

3. 验证审核结果——切勿盲目接受

For each

blocker

and

should-fix

finding, spawn verification subagents (in parallel) that adversarially check the finding against the actual code and verdict APPLY / APPLY-MODIFIED / REJECT with reasoning. Drop rejected findings. Nitpicks don't need verification — they're reported, not necessarily fixed.

对于每个

blocker

和

should-fix

级别的结果，并行生成验证子代理，以反向验证的方式检查结果是否符合实际代码，并给出APPLY / APPLY-MODIFIED / REJECT的结论及理由。剔除被拒绝的结果。Nitpick级别的结果无需验证——仅需上报，不一定要修复。

Preserve review learnings

保留审核经验

After verification, route durable learnings without forcing every review to change policy:

If an APPLY or APPLY-MODIFIED finding reveals a recurring or high-risk repository invariant that existing
```
.greptile/
```
context and CI do not capture, use
```
maintain-greptile-rules
```
and apply its promotion bar.
Keep one-off bugs as code fixes and regression tests. Put deterministic mechanical checks in CI or lint instead of Greptile.
When a small tooling, documentation, or workflow frustration occurs, use
```
papercuts
```
to append it to
```
.agents/PAPERCUTS.md
```
; do not derail merge-ready work to fix it.

验证完成后，留存可复用的经验，但无需强制每次审核都更改规则：

若APPLY或APPLY-MODIFIED级别的结果揭示了现有
```
.greptile/
```
上下文和CI未覆盖的、反复出现或高风险的仓库规范，使用
```
maintain-greptile-rules
```
并遵循其升级标准。
将一次性漏洞作为代码修复和回归测试处理。将确定性的机械检查纳入CI或lint，而非Greptile。
若遇到小的工具、文档或工作流程问题，使用
```
papercuts
```
将其追加至
```
.agents/PAPERCUTS.md
```
；切勿为修复此类问题而中断可合并状态的准备工作。

4. Fix, check, loop

4. 修复、检查、循环

Apply verified
```
blocker
```
/
```
should-fix
```
fixes. Apply nitpicks only when trivial and clearly right; otherwise list them in the PR for Ben to judge.
Checkpoint: commit fixes in logical groups (e.g. one commit per axis or per concern) so the fix history is reviewable on its own.
Run
```
pnpm ci:check
```
(prettier, knip, tsc, oxlint). Fix failures and re-run until clean. If a fix was substantial (not formatting/lint), run a quick re-review of just that change.
Loop until ci:check passes and no verified findings remain unaddressed.

应用已验证的
```
blocker
```
/
```
should-fix
```
级别的修复。仅当nitpick级别的修复简单且明显正确时才应用；否则将其列在PR中供Ben判断。
Checkpoint： 按逻辑分组提交修复（例如，每个维度或每个关注点对应一次提交），使修复历史可单独审核。
运行
```
pnpm ci:check
```
（prettier、knip、tsc、oxlint）。修复失败项并重新运行，直至检查通过。若修复内容重大（非格式/lint问题），对该变更进行快速重新审核。
循环执行，直至ci:check通过且所有已验证的结果均已处理完毕。

5. Push and open/update the PR

5. 推送分支并开启/更新PR

Push the branch. Open a PR against
```
main
```
if one doesn't exist; otherwise update the existing PR's description.
PR description requirements:
- High-level — what changed and why, written for a human skimming. No file paths, no per-file changelog.
- How to review — a short ordered guide: what to look at first, what the risky/judgment-call areas are, what was deliberately left out of scope.
- Review notes — unfixed nitpicks and any REJECT verdicts worth a second opinion, clearly labeled as such.
Report back to Ben: PR link, one-paragraph summary, and anything that still needs his judgment. Do not merge.

推送分支。若尚未开启PR，则针对
```
main
```
分支开启PR；否则更新现有PR的描述。
PR描述要求：
- 高层级概述——变更内容及原因，供人快速浏览。无需包含文件路径或逐文件变更日志。
- 审核指南——简短的有序指导：先查看什么内容，哪些是风险/需判断的区域，哪些内容被刻意排除在范围之外。
- 审核备注——未修复的nitpick项以及任何值得重新评估的REJECT结论，需明确标记。
向Ben反馈：PR链接、一段总结，以及仍需他判断的事项。切勿合并PR。