synthesis

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Synthesis Skill

Synthesis 技能

VCS Provider

VCS 提供商

This skill uses VCS operations through Exarchos MCP actions (

create_pr

merge_pr

list_prs

check_ci

, etc.). These actions automatically detect and route to the correct VCS provider (GitHub, GitLab, Azure DevOps). No

gh

glab

az

commands needed — the MCP server handles provider dispatch.

Not to be confused with
merge_orchestrate
. This skill calls
merge_pr
to land a user-facing PR on
main
via the VCS provider — a remote operation.
merge_orchestrate
(
@skills/merge-orchestrator/SKILL.md
) is the upstream sibling: a local
git merge
of a subagent worktree branch onto the integration branch during the
delegate → merge-pending → delegate
HSM loop. Synthesize never invokes
merge_orchestrate
; merge-pending never invokes
merge_pr
.

本技能通过Exarchos MCP操作（

create_pr

、

merge_pr

、

list_prs

、

check_ci

等）执行VCS操作。这些操作会自动检测并路由到正确的VCS提供商（GitHub、GitLab、Azure DevOps）。无需使用

gh

glab

az

命令——MCP服务器会处理提供商的调度。

请勿与
merge_orchestrate
混淆。本技能调用
merge_pr
通过VCS提供商将面向用户的PR合并到
main
分支——这是一个远程操作。
merge_orchestrate
（
@skills/merge-orchestrator/SKILL.md
）是上游关联技能：在
delegate → merge-pending → delegate
的HSM循环中，将子代理工作树分支本地
git merge
到集成分支。Synthesize技能绝不会调用
merge_orchestrate
；merge-pending阶段也绝不会调用
merge_pr
。

Overview

概述

Submit stacked PRs after review phase completes. The

prepare_synthesis

composite action consolidates readiness checks, stack verification, test validation, and quality signal analysis into a single call -- eliminating the multi-script coordination that historically caused synthesis failures.

Prerequisites:

All delegated tasks complete with reviews passed (spec + quality)
The integration branch already exists from delegation phase
Task branches present and pushed to remote

Do NOT proceed if either review is incomplete or failed -- return to

/review

first.

Entry points: Synthesis is normally reached from the

review

phase of feature / debug / refactor workflows. It is also reachable from

oneshot

workflows via the opt-in path — when a user signals "let's open a PR for this" during

plan

implementing

, the

request_synthesize

event is appended, and

finalize_oneshot

then resolves the choice state and transitions the workflow to

synthesize

. See

@skills/oneshot-workflow/SKILL.md

for the opt-in mechanics and

synthesisPolicy

semantics.

在评审阶段完成后提交堆叠PR。

prepare_synthesis

复合操作将就绪检查、堆栈验证、测试验证和质量信号分析整合为一次调用——消除了过去导致合成失败的多脚本协调问题。

前置条件：

所有委托任务已完成且评审通过（规范+质量）
集成分支已在委托阶段创建
任务分支已存在并推送到远程仓库

请勿在评审未完成或失败的情况下继续——先返回

/review

阶段。

入口点：Synthesis通常从功能/调试/重构工作流的

review

阶段进入。也可通过可选路径从

oneshot

工作流进入——当用户在

plan

或

implementing

阶段表示“let's open a PR for this”时，会追加

request_synthesize

事件，随后

finalize_oneshot

会解析选择状态并将工作流转换到

synthesize

阶段。有关可选机制和

synthesisPolicy

语义，请参阅

@skills/oneshot-workflow/SKILL.md

。

Triggers

触发条件

Activate this skill when:

User runs
```
/synthesize
```
command
All reviews have passed successfully
Ready to submit PRs
Oneshot workflow resolved to
```
synthesize
```
via
```
finalize_oneshot
```

在以下情况激活本技能：

用户执行/synthesize命令
所有评审已成功通过
准备好提交PR
Oneshot工作流通过
```
finalize_oneshot
```
解析为
```
synthesize
```

Process

流程

Runbook: Follow the synthesis-flow runbook:
exarchos_orchestrate({ action: "runbook", id: "synthesis-flow" })
If runbook unavailable, use
describe
to retrieve action schemas:
exarchos_orchestrate({ action: "describe", actions: ["prepare_synthesis"] })

运行手册：遵循合成流程运行手册：
exarchos_orchestrate({ action: "runbook", id: "synthesis-flow" })
如果运行手册不可用，使用
describe
获取操作 schema：
exarchos_orchestrate({ action: "describe", actions: ["prepare_synthesis"] })

Step 1: Verify Readiness

步骤1：验证就绪状态

Call the

prepare_synthesis

composite action to validate all preconditions in a single operation:

typescript

mcp__exarchos__exarchos_orchestrate({
  action: "prepare_synthesis",
  featureId: "<id>"
})

This action performs:

Phase readiness -- Confirms workflow is in the correct phase with all reviews complete
Stack integrity -- Detects diverged branches, missing task branches, or broken parent chains and reconstructs automatically
Test verification -- Runs
```
npm run test:run && npm run typecheck
```
from the stack top
Benchmark regression -- If
```
state.verification.hasBenchmarks
```
is true, checks for performance regressions
Quality signals -- Queries
```
code_quality
```
view for regressions and actionable hints
Gate events -- Auto-emits
```
gate.executed
```
events for each check (tests, benchmarks, CodeRabbit)

For the full breakdown of individual checks the composite action performs, see

references/synthesis-steps.md

On success: All checks passed. The response includes a readiness summary with any quality hints to present to the user. Proceed to Step 2.

On failure: The response identifies which check failed and provides remediation guidance. Follow the guidance -- typically returning to

/review

/delegate

If any quality hint has

confidenceLevel: 'actionable'

, present the

suggestedAction

to the user before proceeding.

调用

prepare_synthesis

复合操作，通过一次操作验证所有前置条件：

typescript

mcp__exarchos__exarchos_orchestrate({
  action: "prepare_synthesis",
  featureId: "<id>"
})

该操作执行以下检查：

阶段就绪性——确认工作流处于正确阶段且所有评审已完成
堆栈完整性——检测分支偏离、缺失任务分支或断裂的父链，并自动重建
测试验证——从堆栈顶部运行
```
npm run test:run && npm run typecheck
```
基准回归检查——如果
```
state.verification.hasBenchmarks
```
为true，检查性能回归
质量信号——查询
```
code_quality
```
视图以获取回归情况和可操作提示
网关事件——为每项检查（测试、基准、CodeRabbit）自动发送
```
gate.executed
```
事件

有关该复合操作执行的各项检查的详细说明，请参阅

references/synthesis-steps.md

。

成功时：所有检查通过。响应包含就绪状态摘要以及需呈现给用户的质量提示。进入步骤2。

失败时：响应会指出哪项检查失败并提供补救指导。遵循指导操作——通常是返回

/review

或

/delegate

阶段。

如果任何质量提示的

confidenceLevel: 'actionable'

，在继续之前向用户呈现

suggestedAction

。

Step 2: Write and Validate PR Descriptions

步骤2：编写并验证PR描述

For each PR in the stack, write a structured description following

references/pr-descriptions.md

. Required sections: Summary, Changes, Test Plan, plus a footer. Projects can override required sections via

.exarchos/pr-template.md

Title format:

<type>: <what>

(max 72 chars)

Write the PR body to a temp file:

bash

cat > /tmp/pr-body.md <<'EOF'

针对堆栈中的每个PR，按照

references/pr-descriptions.md

编写结构化描述。必填部分：Summary、Changes、Test Plan，以及页脚。项目可通过

.exarchos/pr-template.md

覆盖必填部分。

标题格式：

<type>: <what>

（最多72字符）

将PR正文写入临时文件：

bash

cat > /tmp/pr-body.md <<'EOF'

Summary

[2-3 sentences: what changed, why it matters]

[2-3句话：变更内容及其重要性]

Changes

Component -- Description of change

Component -- 变更描述

Test Plan

[Testing approach and coverage]

Results: Tests X pass · Build 0 errors Design: doc Related: #issue EOF


Validate **before** creating the PR:
```typescript
mcp__exarchos__exarchos_orchestrate({
  action: "validate_pr_body",
  bodyFile: "/tmp/pr-body.md"
})

Do NOT call
create_pr
until validation passes. If validation fails, fix the body and re-validate.

[测试方法和覆盖范围]

Results: Tests X pass · Build 0 errors Design: doc Related: #issue EOF


在创建PR**之前**验证：
```typescript
mcp__exarchos__exarchos_orchestrate({
  action: "validate_pr_body",
  bodyFile: "/tmp/pr-body.md"
})

验证通过前请勿调用
create_pr
。如果验证失败，修改正文并重新验证。

Step 3: Submit and Merge

步骤3：提交并合并

Create PRs using the validated body and enable auto-merge. For each branch in the stack (bottom-up):

typescript

// Create PR via VCS MCP action
exarchos_orchestrate({
  action: "create_pr",
  base: "<parent-branch>",
  head: "<branch>",
  title: "<type>: <what>",
  body: "<pr-body>"
})

// Enable auto-merge
exarchos_orchestrate({
  action: "merge_pr",
  prId: "<number>",
  strategy: "squash"
})

After submission:

Apply benchmark label -- If

verification.hasBenchmarks

is true, apply label:

gh pr edit <number> --add-label has-benchmarks

Record PR URLs -- Capture URLs via

exarchos_orchestrate({ action: "list_prs", state: "open" })

Update state:

typescript

mcp__exarchos__exarchos_workflow({
  action: "set", featureId: "<id>", updates: {
    "artifacts": { "pr": ["<url1>", "<url2>"] },
    "synthesis": { "mergeOrder": ["<branch1>", ...], "prUrl": ["<url1>", ...], "prFeedback": [] }
  }
})

For merge ordering strategy, see

references/merge-ordering.md

Human checkpoint: Output "Stacked PRs enqueued: [URLs]. Waiting for CI/merge queue." then PAUSE for user input: "Merge stack? (yes/no/feedback)"

'yes' -- PRs merge; transition to completed via
```
/cleanup
```
'feedback' -- Route to
```
/shepherd [PR_URL]
```
to address comments, then return here
'no' -- Pause workflow; resume later with
```
/rehydrate
```

使用已验证的正文创建PR并启用自动合并。针对堆栈中的每个分支（自底向上）：

typescript

// 通过VCS MCP操作创建PR
exarchos_orchestrate({
  action: "create_pr",
  base: "<parent-branch>",
  head: "<branch>",
  title: "<type>: <what>",
  body: "<pr-body>"
})

// 启用自动合并
exarchos_orchestrate({
  action: "merge_pr",
  prId: "<number>",
  strategy: "squash"
})

提交后：

添加基准标签——如果

verification.hasBenchmarks

为true，添加标签：

gh pr edit <number> --add-label has-benchmarks

记录PR URL——通过

exarchos_orchestrate({ action: "list_prs", state: "open" })

捕获URL

更新状态：

typescript

mcp__exarchos__exarchos_workflow({
  action: "set", featureId: "<id>", updates: {
    "artifacts": { "pr": ["<url1>", "<url2>"] },
    "synthesis": { "mergeOrder": ["<branch1>", ...], "prUrl": ["<url1>", ...], "prFeedback": [] }
  }
})

有关合并排序策略，请参阅

references/merge-ordering.md

。

人工检查点：输出“Stacked PRs enqueued: [URLs]. Waiting for CI/merge queue.”然后暂停等待用户输入：“Merge stack? (yes/no/feedback)”

'yes'——PR合并；通过
```
/cleanup
```
转换到完成阶段
'feedback'——路由到
```
/shepherd [PR_URL]
```
处理评论，然后返回此处
'no'——暂停工作流；之后通过
```
/rehydrate
```
恢复

Event Emissions (REQUIRED)

事件发送（必填）

After PRs are created and auto-merge is enabled, emit the

stack.submitted

event:

typescript

mcp__exarchos__exarchos_event({ action: "append", stream: "<featureId>", event: {
  type: "stack.submitted",
  data: {
    branches: ["task-001-branch", "task-002-branch"],
    prNumbers: [101, 102]
  }
}})

During shepherd iterations (CI monitoring loop), emit after each assessment:

typescript

mcp__exarchos__exarchos_event({ action: "append", stream: "<featureId>", event: {
  type: "shepherd.iteration",
  data: {
    iteration: 1,
    prsAssessed: 2,
    fixesApplied: 0,
    status: "all-green"
  }
}})

These events are checked by

check-event-emissions

during workflow validation. Missing emissions will trigger warnings.

创建PR并启用自动合并后，发送

stack.submitted

事件：

typescript

mcp__exarchos__exarchos_event({ action: "append", stream: "<featureId>", event: {
  type: "stack.submitted",
  data: {
    branches: ["task-001-branch", "task-002-branch"],
    prNumbers: [101, 102]
  }
}})

在shepherd迭代（CI监控循环）期间，每次评估后发送：

typescript

mcp__exarchos__exarchos_event({ action: "append", stream: "<featureId>", event: {
  type: "shepherd.iteration",
  data: {
    iteration: 1,
    prsAssessed: 2,
    fixesApplied: 0,
    status: "all-green"
  }
}})

这些事件会在工作流验证期间被

check-event-emissions

检查。缺失事件会触发警告。

Post-Merge Cleanup

合并后清理

After PRs merge, invoke cleanup:

typescript

mcp__exarchos__exarchos_workflow({
  action: "cleanup", featureId: "<id>", mergeVerified: true,
  prUrl: ["<url>", ...], mergedBranches: ["<branch>", ...]
})

Then sync:

git fetch --prune

and remove worktrees.

PR合并后，调用清理操作：

typescript

mcp__exarchos__exarchos_workflow({
  action: "cleanup", featureId: "<id>", mergeVerified: true,
  prUrl: ["<url>", ...], mergedBranches: ["<branch>", ...]
})

然后同步：

git fetch --prune

并移除工作树。

Anti-Patterns

反模式

Don't	Do Instead
Skip review phase	Always run `/review` first
Force push stack branches	Use normal push
Delete worktrees before merge	Wait for merge confirmation
Create PR with failing tests	Ensure review phase passes first
Run readiness scripts manually	Use `prepare_synthesis` composite action

请勿	建议做法
跳过评审阶段	始终先运行 `/review`
强制推送堆栈分支	使用常规推送
合并前删除工作树	等待合并确认
创建测试失败的PR	确保评审阶段先通过
手动运行就绪检查脚本	使用 `prepare_synthesis` 复合操作

Handling Failures

故障处理

See

references/troubleshooting.md

for test failures, PR check failures, merge queue rejections, and MCP tool errors.

有关测试失败、PR检查失败、合并队列拒绝和MCP工具错误的处理，请参阅

references/troubleshooting.md

。

Phase Transitions and Guards

阶段转换与防护

For the full transition table, consult

@skills/workflow-state/references/phase-transitions.md

Quick reference: The

synthesize

→

completed

transition requires guard

pr-url-exists

— set

synthesis.prUrl

artifacts.pr

in the same

set

call as

phase

完整的转换表请参阅

@skills/workflow-state/references/phase-transitions.md

。

快速参考：

synthesize

→

completed

转换需要防护条件

pr-url-exists

——在设置

phase

的同一个

set

调用中设置

synthesis.prUrl

或

artifacts.pr

。

Schema Discovery

Schema 发现

Use

exarchos_workflow({ action: "describe", actions: ["set", "init"] })

for parameter schemas and

exarchos_workflow({ action: "describe", playbook: "feature" })

for phase transitions, guards, and playbook guidance. Use

exarchos_orchestrate({ action: "describe", actions: ["prepare_synthesis"] })

for orchestrate action schemas.

使用

exarchos_workflow({ action: "describe", actions: ["set", "init"] })

获取参数schema，使用

exarchos_workflow({ action: "describe", playbook: "feature" })

获取阶段转换、防护条件和工作手册指导。使用

exarchos_orchestrate({ action: "describe", actions: ["prepare_synthesis"] })

获取编排操作的schema。

Completion Criteria

完成标准

```
prepare_synthesis
```
readiness check passed
PR descriptions written per
```
references/pr-descriptions.md
```
PRs created and auto-merge enabled
PR links provided to user
State updated with PR URLs and merge order

```
prepare_synthesis
```
就绪检查通过
PR描述按照
```
references/pr-descriptions.md
```
编写
PR已创建并启用自动合并
已向用户提供PR链接
状态已更新PR URL和合并顺序",