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：上下文收集

Ask for the PRD issue number. Accept "none" if this change didn't go through the full pipeline.

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.

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.

询问PRD对应的issue编号。 如果本次变更没有走完整流水线，可接受“none”作为回答。

如果提供了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 部分）。

评估diff：
bash
```
git diff main...HEAD --stat
git log --oneline main..HEAD
```
如果和主干分支没有diff，告知用户没有可审查的内容并终止流程。

Phase 2: Create the PR

阶段2：创建PR

Check for an existing PR:

bash

gh pr list --head $(git branch --show-current) --json number,url

Create or update the PR. Use
```
gh pr create
```
or
```
gh pr edit
```
.

PR body template (when PRD exists):

markdown

undefined

检查是否已存在PR：

bash

gh pr list --head $(git branch --show-current) --json number,url

创建或更新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

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

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

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