Back to Details

pre-merge

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Pre-Merge

合并前审查

Create a GitHub PR linking back to the PRD and slice issues, then review the full diff against the project's architectural principles. Produces advisory findings — does not block merge, auto-fix code, or file issues.
创建关联PRD和拆分任务的GitHub PR，然后对照项目架构原则审查完整的diff。输出建议性的审查结果，不会阻塞合并、自动修复代码或创建issue。

Invocation Position

调用时机

This is a primary pipeline skill used after implementation has been verified and before merging to main.
Use 
/pre-merge
when the branch is ready for PR creation, architectural review, and final plan-to-code reconciliation.
Do not use it as a substitute for implementation verification, QA intake, or refactor planning. It assumes the work is already built and ready to review.
这是一项核心流水线技能，使用时机为实现验证通过后、合并到主干分支之前。
当分支已准备好创建PR、进行架构审查以及最终的计划与代码对齐校验时，使用
/pre-merge
命令。
请勿将其用于替代实现验证、QA录入或重构规划。该技能默认待处理的工作已经开发完成，可进入审查阶段。

When to Use

适用场景

  • After QA passes and before merging a feature branch to main
  • After Ralph finishes AFK execution and you've verified behavior
  • For any branch you want reviewed before merge, even without a full pipeline run
  • QA测试通过后，合并功能分支到主干分支前
  • Ralph完成离线执行且你已验证功能行为符合预期后
  • 任何你希望在合并前进行审查的分支，即便没有运行完整流水线也可使用

Execution Flow

执行流程

Phase 1: Gather Context

阶段1：上下文收集

  1. Ask for the PRD issue number. Accept "none" if this change didn't go through the full pipeline.
  2. If a PRD was given:
    bash
    gh issue view <number>
gh issue list --search "in:body #<prd-number>" --state all --json number,title,state,body --limit 100
    Parse boundary maps (Produces/Consumes sections) from each slice issue body.
  3. Assess the diff:
    bash
    git diff main...HEAD --stat
git log --oneline main..HEAD
    If no diff from main, tell the user there's nothing to review and stop.
  1. 询问PRD对应的issue编号。 如果本次变更没有走完整流水线，可接受“none”作为回答。
  2. 如果提供了PRD：
    bash
    gh issue view <number>
gh issue list --search "in:body #<prd-number>" --state all --json number,title,state,body --limit 100
    从每个拆分任务issue的正文中解析边界映射（Produces/Consumes 部分）。
  3. 评估diff：
    bash
    git diff main...HEAD --stat
git log --oneline main..HEAD
    如果和主干分支没有diff，告知用户没有可审查的内容并终止流程。

Phase 2: Create the PR

阶段2：创建PR

  1. Check for an existing PR:
    bash
    gh pr list --head $(git branch --show-current) --json number,url
  2. Create or update the PR. Use 
    gh pr create
    or 
    gh pr edit
    .
PR body template (when PRD exists):
markdown
undefined
  1. 检查是否已存在PR：
    bash
    gh pr list --head $(git branch --show-current) --json number,url
  2. 创建或更新PR。 使用
    gh pr create
    或
    gh pr edit
    命令。
PR正文模板（存在PRD时使用）：
markdown
undefined

Summary

摘要

[1-3 sentences derived from the PRD's Problem and Solution sections.]
[从PRD的问题和解决方案部分提取的1-3句话描述]

PRD

PRD

Closes #<prd-issue-number>
关闭 #<prd-issue-number>

Slices

拆分任务

  • #N — Title (for closed slices)
  • #N — Title (for still-open slices)
  • #N — 任务标题（已关闭的拆分任务）
  • #N — 任务标题（仍开放的拆分任务）

Key Decisions

关键决策

[Bullet list of notable implementation decisions that refined or diverged from the PRD. Derived from commit messages and slice issue comments. Omit this section if nothing diverged.]

**PR body template (no PRD):**

```markdown
[优化或偏离PRD的重大实现决策列表，从提交信息和拆分任务评论中提取。如果没有偏离可省略该部分。]

**PR正文模板（无PRD时使用）：**

```markdown

Summary

摘要

[1-3 sentences summarizing the change, derived from the diff and commit messages.]

3. Print the PR URL.
[从diff和提交信息中提取的1-3句话变更总结]

3. 输出PR的URL。

Phase 3: Architectural Review

阶段3：架构审查

Consult 
review-checklist.md
for the eight review dimensions and their violation patterns.
Small diff (< 200 changed lines, < 10 files): run all eight dimensions sequentially in the main agent.
Larger diff: spawn two sub-agents in parallel:
  • Sub-agent A (structural): Deep Modules, Vertical Slice Integrity, State Discipline
  • Sub-agent B (contracts & quality): Boundary Map Contracts, Test Quality, docs/solutions/ Adherence, Runtime Initialization, Fix Completeness
Each sub-agent reads the full diff and its assigned dimensions from 
review-checklist.md
, then returns findings in the three-tier severity format.
Dimension 4 (Boundary Map Contracts) only runs if a PRD with slice issues was provided. Without boundary maps, there are no contracts to verify.
Dimension 7 (Runtime Initialization) only runs if the diff includes schema files, migration files, environment config, or server startup code. Without infrastructure changes, there is nothing to verify.
Dimension 6 (docs/solutions/ Adherence): Search 
docs/solutions/
for files whose 
components
or 
technologies
frontmatter overlaps with the changed code areas. If relevant solutions exist, check whether the implementation follows or consciously diverges from documented patterns.
TypeScript projects: For branches with significant 
.ts
or 
.tsx
changes, mention that 
/ts-audit
can be run on the changed files for type-safety analysis that complements the architectural review. Do not invoke it automatically — note it as an option. Example: "For deeper TypeScript analysis, consider running 
/ts-audit
on the changed files."
参考
review-checklist.md
中的8个审查维度及对应的违规模式。
小型diff（变更行数<200，变更文件<10）：在主Agent中按顺序运行全部8个维度的审查。
大型diff：并行启动两个子Agent：
  • 子Agent A（结构维度）：深度模块、垂直切片完整性、状态规范
  • 子Agent B（契约与质量维度）：边界映射契约、测试质量、docs/solutions/ 规范遵从性、运行时初始化、修复完整性
每个子Agent读取完整diff以及
review-checklist.md
中分配给它的审查维度，然后按三级 severity 格式返回审查结果。
维度4（边界映射契约）仅在提供了带拆分任务issue的PRD时才会运行，没有边界映射的情况下没有可验证的契约。
维度7（运行时初始化）仅在diff包含schema文件、迁移文件、环境配置或服务启动代码时才会运行，没有基础设施变更的情况下没有可验证的内容。
维度6（docs/solutions/ 规范遵从性）： 在
docs/solutions/
目录下搜索frontmatter中
components
或
technologies
与变更代码范围重叠的文件。如果存在相关解决方案，检查实现是否遵循了文档记录的模式，或是有意识地偏离了该模式。
TypeScript项目： 对于包含大量
.ts
或
.tsx
变更的分支，提示可以对变更文件运行
/ts-audit
来执行类型安全分析，作为架构审查的补充。不要自动调用该命令，仅将其作为选项告知用户。示例："如需更深入的TypeScript分析，可以考虑对变更文件运行
/ts-audit
。"

Phase 4: Present Findings

阶段4：展示审查结果

Combine findings from all dimensions (or sub-agents). Present in the terminal using three tiers:
undefined
整合所有维度（或子Agent）的审查结果，按照以下三个层级在终端展示：
undefined

Architectural Review

架构审查

Observations (for awareness — no action needed)

观察项（仅用于告知，无需处理）

[Patterns noticed that aren't violations. Example: "The presence module exports 6 functions — reasonable, but worth watching if it grows."]
[注意到的不属于违规的模式，示例："presence模块导出了6个函数——当前规模合理，但如果继续增长需要关注。"]

Suggestions (action optional — would improve quality)

建议项（可选处理，可提升代码质量）

[Grouped by dimension. Things that aren't violations but would make the code better.]
[按维度分组，不属于违规但可以优化代码的内容]

Concerns (action recommended — potential principle violation)

风险项（建议处理，可能违反架构原则）

[Grouped by dimension. Each concern cites the principle, shows the specific code, and explains why it matters.]
No action is required. These are advisory. When ready, merge the PR at <PR-URL>.

**Scope Notes (only when a PRD with slice issues was provided):**

After the three-tier findings, note any significant scope drift between the planned decomposition and the actual diff:

- Work that appears in the diff but wasn't in any slice's Boundary Map (omitted scope discovered during implementation)
- Declared Produces that don't appear in the diff (planned work that was cut or deferred)
- Slices where the actual diff footprint was dramatically different from the boundary map's declared scope

These are factual notes, not review findings. They don't produce Observations, Suggestions, or Concerns — they record plan-vs-actual divergence so the user and `/compound` can decide whether a pattern is worth capturing. Omit this section entirely if the diff aligns closely with the planned boundary maps.

If a concern warrants deeper work, note: "Consider running `/request-refactor-plan` for this area." Do not invoke it.

If a finding looks like a behavioral bug, note: "Consider running `/qa` to verify." Do not file an issue.

Omit any tier that has zero findings.
[按维度分组，每个风险项需引用对应原则，展示具体代码并解释影响]
无需强制处理，以上仅为建议。 准备就绪后，可通过<PR-URL>合并PR。

**范围说明（仅在提供了带拆分任务issue的PRD时展示）：**

在三级审查结果之后，标注规划的任务拆分与实际diff之间的重大范围偏差：

- diff中存在但没有出现在任何拆分任务边界映射中的工作（实现过程中发现的遗漏范围）
- 声明的产出没有出现在diff中（被削减或延期的规划工作）
- 实际diff的影响范围与边界映射声明的范围存在显著差异的拆分任务

这些是事实记录，不属于审查结果，不会被归入观察项、建议项或风险项——它们记录了计划与实际的偏差，方便用户和`/compound`命令判断是否有值得记录的模式。如果diff与规划的边界映射高度对齐，可以完全省略该部分。

如果某个风险项需要更深入的处理，提示："可以考虑针对该范围运行`/request-refactor-plan`"，不要自动调用该命令。

如果某个审查结果看起来是功能bug，提示："可以考虑运行`/qa`进行验证"，不要自动创建issue。

如果某个层级没有任何结果，直接省略该层级。

What This Skill is NOT

本技能的适用边界

  • Not a test runner. Pre-commit hooks run tests, typecheck, and lint on every commit.
  • Not a bug finder. 
    /qa
    files behavioral bugs as GitHub issues.
  • Not a refactoring planner. 
    /request-refactor-plan
    produces RFC-style refactor proposals.
  • Not a CI gate. Findings are advisory. The user decides what to address before merging.
  • 不是测试运行器。pre-commit钩子会在每次提交时运行测试、类型检查和 lint 校验。
  • 不是bug检测工具。
    /qa
    命令会将功能bug作为GitHub issue提交。
  • 不是重构规划工具。
    /request-refactor-plan
    会输出RFC格式的重构方案。
  • 不是CI门禁。审查结果仅为建议，由用户决定合并前需要处理哪些内容。

Handoff

流转说明

  • Expected input: verified implementation work that is ready for review and PR creation
  • Produces: a PR with lineage plus an architectural review readout
  • May redirect: to 
    /qa
    when a finding looks behavioral, or to 
    /request-refactor-plan
    when deeper structural cleanup is warranted
  • Comes next by default: merge, then 
    /compound
  • 预期输入：已通过验证、可进入审查和PR创建阶段的实现工作
  • 输出：带溯源信息的PR以及架构审查结果
  • 可能流转到：如果发现功能相关问题，流转到
    /qa
    ；如果需要深度结构清理，流转到
    /request-refactor-plan
  • 默认后续步骤：合并，然后运行
    /compound