splice-issue

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Splice an issue — decompose into sub-issues

拆分issue——分解为子issue

Take an oversized issue or epic and cut it into a set of independently mergeable sub-issues. Each sub-issue should be 1–3 days of work, ship independently, and leave the system in a working state if later ones don't land.

将过大的issue或史诗任务拆分为一组可独立合并的子issue。每个子issue应对应1–3天的工作量，可独立交付，且即使后续子issue未完成，系统仍能保持可用状态。

Before You Start

开始之前

The source issue — read it in full with
```
gh issue view <number>
```
.
Any linked design docs or ADRs — find them in the issue body or referenced PRs.
The project's contribution guide (
```
CONTRIBUTING.md
```
,
```
.github/CONTRIBUTING.md
```
) — it may specify issue conventions (labels, milestones, project board).

源issue——使用
```
gh issue view <number>
```
完整查看。
任何关联的设计文档或ADR——在issue主体或引用的PR中查找。
项目贡献指南（
```
CONTRIBUTING.md
```
、
```
.github/CONTRIBUTING.md
```
）——其中可能指定了issue约定（标签、里程碑、项目看板）。

Step 1: read the issue end-to-end

步骤1：完整阅读issue

bash

gh issue view <number> --comments

Identify:

The goal — what "done" looks like in user-visible terms.
The scope boundary — what's explicitly out of scope.
Linked issues / PRs — prior work that informs this one.
Mentioned files or subsystems — where the work lives in the codebase.

bash

gh issue view <number> --comments

确定：

目标——从用户可见的角度定义“完成”状态。
范围边界——明确排除在范围外的内容。
关联的issue/PR——为当前任务提供参考的前期工作。
提及的文件或子系统——工作在代码库中的具体位置。

Step 2: map the work to the codebase

步骤2：将工作映射到代码库

bash

undefined

bash

undefined

For each subsystem mentioned, inspect it

检查每个提及的子系统

ls src/<mentioned-area>/ grep -rn "<key-term>" src/ | head -20

Recent activity in relevant files

相关文件的近期活动

git log --oneline -20 -- src/<area>/


The goal is to know WHERE each chunk of work would land, so sub-issues can be scoped to independent code areas.

git log --oneline -20 -- src/<area>/


目标是明确每个工作块的落地位置，以便将子issue的范围限定在独立的代码区域。

Step 3: identify natural seams

步骤3：识别自然拆分点

Look for cut lines that produce independently shippable pieces:

Data first, then behavior — add a field or table migration as one issue; use it as a second.
Read-only before mutation — "display X" before "edit X."
Backend then frontend (or vice-versa) when the contract is stable.
Single-user before multi-user — demo-quality before production-quality.
One entity at a time — if the epic covers three entity types, three sub-issues.
Instrumentation before change — log / metric the current behavior before rewriting it.

Each seam should satisfy:

Independently mergeable. The system works without the next issue landing.
User- or developer-visible. Produces observable value.
Testable on its own. Not just scaffolding with no behavior.

寻找能产生可独立交付模块的拆分方式：

先数据后行为——将字段或表迁移作为一个issue；后续使用该数据作为另一个issue。
先只读后修改——先实现“显示X”，再实现“编辑X”。
先后端后前端（或反之）——当接口契约稳定时采用此方式。
先单用户后多用户——先实现演示版，再优化为生产版。
一次处理一个实体——如果史诗任务涉及三种实体类型，则拆分为三个子issue。
先监控后变更——在重写现有行为前，先记录/度量当前行为。

每个拆分点需满足：

可独立合并——即使下一个issue未完成，系统仍能正常运行。
用户或开发者可见——能产生可观察的价值。
可独立测试——不能只是无实际行为的脚手架。

Step 4: draft the sub-issues

步骤4：草拟子issue

For each chunk, draft an issue with this shape:

markdown

undefined

针对每个工作块，按照以下结构草拟issue：

markdown

undefined

{one-line title — imperative, concrete}

{单行标题——命令式、具体明确}

Part of #{parent-issue}.

隶属于#{父issue编号}。

Context

背景

{2–3 sentences: the parent goal, where this slice fits in.}

{2–3句话：父任务目标，本模块在整体中的位置。}

Scope

范围

What this issue adds: {bullet list — specific files or behaviors}
What this issue does NOT cover: {explicit non-goals, linking to sibling sub-issues}

本issue新增内容：{项目符号列表——具体文件或行为}
本issue不包含内容：{明确的非目标，关联到同级子issue}

Acceptance criteria

验收标准

Dependencies

依赖关系

Blocks: #{sibling-issue-if-this-must-land-first}
Blocked by: #{sibling-issue-this-waits-on}
Independent of: {list siblings this doesn't touch}


Aim for **3–6 sub-issues** on a typical epic. If you're at 10+, the parent was probably multiple epics.

阻塞：#{需先完成的同级子issue编号}
被阻塞：#{需等待的同级子issue编号}
独立于：{本模块不涉及的同级子issue列表}


对于典型的史诗任务，目标拆分为**3–6个子issue**。如果拆分出10个以上，说明原父任务可能包含多个史诗任务。

Step 5: present to the user

步骤5：向用户展示计划

Before creating anything on GitHub, show the full plan:

markdown

undefined

在GitHub上创建任何内容之前，先展示完整计划：

markdown

undefined

Splice plan for #{parent-issue}: {parent title}

#{父issue编号}的拆分计划：{父issue标题}

Proposed sub-issues (ordered by dependency):

#NEW-1 — {title} — {1-line scope}
#NEW-2 — {title} — {1-line scope} (blocked by #NEW-1)
#NEW-3 — {title} — {1-line scope} (independent) ...

Estimated order of implementation: 1 → (2, 3 in parallel) → 4 → 5.


Get explicit user approval before creating issues. Offer to adjust the seams.

建议的子issue（按依赖顺序排列）：

#NEW-1 — {标题} — {单行范围描述}
#NEW-2 — {标题} — {单行范围描述}（被#NEW-1阻塞）
#NEW-3 — {标题} — {单行范围描述}（独立） ...

预计实施顺序：1 → (2、3并行) → 4 → 5。


在创建issue前需获得用户明确批准。可根据用户意见调整拆分方式。

Step 6: create the sub-issues

步骤6：创建子issue

After approval:

bash

for each sub-issue draft:
  gh issue create --title "<title>" --body "<body from step 4>" --label "part-of-<parent>"

Capture the new issue numbers. Then update the parent:

bash

gh issue comment <parent> --body "$(cat <<EOF
Spliced into sub-issues:
- [ ] #<NEW-1> — <title>
- [ ] #<NEW-2> — <title>
...
Closing this epic; individual sub-issues track work.
EOF
)"

获得批准后：

bash

for each sub-issue draft:
  gh issue create --title "<title>" --body "<body from step 4>" --label "part-of-<parent>"

记录新issue的编号。然后更新父issue：

bash

gh issue comment <parent> --body "$(cat <<EOF
已拆分为以下子issue：
- [ ] #<NEW-1> — <title>
- [ ] #<NEW-2> — <title>
...
关闭此史诗任务；具体工作由各个子issue跟踪。
EOF
)"

If the parent is an epic that should stay open to track the rollup, skip the close.

如果父任务是需要保持打开状态以跟踪整体进度的史诗任务，则跳过关闭步骤。

gh issue close <parent> --comment "Work tracked in sub-issues listed above."

undefined

gh issue close <parent> --comment "工作进度由上述子issue跟踪。"

undefined

Verify

验证

bash

undefined

bash

undefined

Every sub-issue exists and references the parent

确保每个子issue都存在并关联父issue

for n in <NEW-1> <NEW-2> ...; do gh issue view "$n" | grep -i "part of" done

The parent references every sub-issue

确保父issue关联所有子issue

gh issue view <parent> | grep -E "#<NEW-[0-9]+>"

undefined

gh issue view <parent> | grep -E "#<NEW-[0-9]+>"

undefined

Common Mistakes

常见错误

Mistake	Correction
Sub-issues that depend on each other linearly (no parallelism)	Look for independent cuts (by entity, by layer, by user segment). A linear 5-issue chain is often a single sequenced issue with phases.
Sub-issues with no visible outcome	"Set up scaffolding" alone isn't an issue — fold it into the first user-visible slice.
Acceptance criteria that say "works well"	Concrete, testable: " `/api/users/:id` returns 404 for a missing user with `Content-Type: application/json` ."
Creating issues before the user approves the splice	Always show the plan first (step 5). Issues are public records — wrong splits waste everyone's time.

错误	修正方法
子issue线性依赖（无并行空间）	寻找独立拆分方式（按实体、按层级、按用户群体）。线性的5个issue链通常应作为单个分阶段的issue。
子issue无可见成果	“搭建脚手架”本身不应作为独立issue——将其合并到第一个用户可见的模块中。
验收标准模糊（如“运行良好”）	改为具体、可测试的描述：“ `/api/users/:id` 针对不存在的用户返回404状态码，且 `Content-Type: application/json` 。”
在用户批准拆分计划前创建issue	务必先展示计划（步骤5）。issue是公开记录——错误的拆分会浪费所有人的时间。