Back to Details

review-merge-readiness

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Requesting Code Review (Structured Review: Requirements Alignment + Production Readiness)

发起代码审查（结构化审查：需求对齐 + 生产就绪性）

Goal: Make code review a repeatable process, not random comments.
Core principle: Review early, review often.
目标：让代码审查成为可重复的流程，而非随意的评论。
核心原则：尽早审查，经常审查。

When Review is Required

何时需要进行审查

Mandatory:
  • After completing important features
  • After each batch in 
    workflow-execute-plans
    ends (default 3 tasks per batch)
  • Before merging to main branch
Optional but valuable:
  • When stuck (get a fresh perspective)
  • Before major refactoring (establish baseline first)
  • After fixing complex bugs (verify no new regressions)
强制场景：
  • 完成重要功能后
  • workflow-execute-plans
    中的每个批次结束后（默认每批次3个任务）
  • 合并到主分支前
可选但有价值的场景：
  • 遇到瓶颈时（获取新视角）
  • 大型重构前（先建立基准）
  • 修复复杂漏洞后（验证无新回归问题）

How to Initiate (Minimum Information Set)

如何发起（最低信息要求）

1) Determine Review Scope (git SHA)

1) 确定审查范围（git SHA）

Prefer using "baseline before plan/task started" as 
BASE_SHA
:
bash
undefined
建议使用“计划/任务开始前的基准版本”作为
BASE_SHA
：
bash
undefined

Common approach: use main as baseline

Common approach: use main as baseline

BASE_SHA=$(git merge-base HEAD main 2>/dev/null || git merge-base HEAD master) HEAD_SHA=$(git rev-parse HEAD)

If you want to review just the most recent commit within a small task:

```bash
BASE_SHA=$(git rev-parse HEAD~1)
HEAD_SHA=$(git rev-parse HEAD)
BASE_SHA=$(git merge-base HEAD main 2>/dev/null || git merge-base HEAD master) HEAD_SHA=$(git rev-parse HEAD)

若只需审查小型任务中最新的一次提交：

```bash
BASE_SHA=$(git rev-parse HEAD~1)
HEAD_SHA=$(git rev-parse HEAD)

2) Prepare Review Basis (Plan / Requirements)

2) 准备审查依据（计划/需求）

Review must provide:
  • WHAT_WAS_IMPLEMENTED: What you just completed (1-3 bullet points)
  • PLAN_OR_REQUIREMENTS: Corresponding plan excerpt or requirements document path (e.g., 
    run_dir/03-plans/feature-plan.md
    )
审查必须提供：
  • WHAT_WAS_IMPLEMENTED: 刚完成的内容（1-3个要点）
  • PLAN_OR_REQUIREMENTS: 对应的计划摘录或需求文档路径（例如：
    run_dir/03-plans/feature-plan.md
    ）

3) Get diff (Evidence)

3) 获取差异文件（证据）

bash
git diff --stat "$BASE_SHA..$HEAD_SHA"
git diff "$BASE_SHA..$HEAD_SHA"
bash
git diff --stat "$BASE_SHA..$HEAD_SHA"
git diff "$BASE_SHA..$HEAD_SHA"

Review Execution Methods (Choose One)

审查执行方式（选择其一）

Method A: Sub-Agent Review (if your system supports it)

方法A：子Agent审查（若系统支持）

Use template: 
review-merge-readiness/code-reviewer.md
, fill in placeholders and execute.
使用模板：
review-merge-readiness/code-reviewer.md
，填充占位符后执行。

Method B: Self Review (works without sub-agent)

方法B：自我审查（无需子Agent即可使用）

Check each item per template checklist and output same structured result (Strengths + Issues by severity + Verdict).
对照模板检查清单逐一核对，并输出相同结构的结果（优点 + 按严重程度分类的问题 + 结论）。

Review Output Format (Must Be Structured)

审查输出格式（必须结构化）

Output must include:
  • Strengths: Specific positives (at least 1)
  • Issues: Categorized by severity:
    • Critical (Must Fix): Security/data loss/functionality bugs/would cause production incidents
    • Important (Should Fix): Obviously poor architecture/missing error handling/test gaps/requirements misalignment
    • Minor (Nice to Have): Style/small optimizations/documentation polish
  • Assessment: Merge readiness (Yes/No/With fixes) + 1-2 sentence technical reasoning
Each Issue must include:
  • Location: 
    file:line
  • What's wrong
  • Why it matters
  • How to fix (provide minimal change suggestion)
输出必须包含：
  • 优点: 具体的积极点（至少1个）
  • 问题: 按严重程度分类：
    • Critical（必须修复）: 安全问题/数据丢失/功能缺陷/会导致生产事故的问题
    • Important（应该修复）: 明显的架构缺陷/缺少错误处理/测试覆盖不足/需求不符
    • Minor（建议优化）: 代码风格/小优化/文档完善
  • 评估: 合并就绪状态（是/否/需修复后） + 1-2句技术说明
每个问题必须包含：
  • 位置：
    文件:行号
  • 问题内容
  • 影响原因
  • 修复建议（提供最小修改方案）

Relationship with Other Review Skills

与其他审查技能的关系

  • review-clean-code
    : More focused on "maintainability/cleanliness", suitable for deep code smell investigation
  • review-react-best-practices
    : More focused on React/Next.js performance patterns (waterfalls/bundle/re-renders). Use when the diff touches React UI, data fetching, or performance-sensitive areas.
  • This skill: More focused on "requirements alignment/production readiness/merge verdict" conclusion-oriented review
If you just need a "can we merge?" verdict: use this skill. If you want a deep health check: additionally invoke 
review-clean-code
.
  • review-clean-code
    : 更侧重于“可维护性/代码整洁度”，适合深入排查代码异味
  • review-react-best-practices
    : 更侧重于React/Next.js的性能模式（请求瀑布/包体积/重渲染）。当差异涉及React UI、数据获取或性能敏感区域时使用。
  • 本技能：更侧重于“需求对齐/生产就绪性/合并结论”的结论导向型审查
若只需“能否合并？”的结论：使用本技能。 若需要深度健康检查：额外调用
review-clean-code
。