write-slices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Write Slices

编写切片

Cut a spec into reviewable slices with blocking edges, written as one JSON file.

将规格说明拆分为带阻塞依赖边、可供评审的切片，并写入一个 JSON 文件。

1. Take the spec

1. 获取规格说明

Take the path from the invocation. If none was given and exactly one

spec/features/<slug>/spec.md

has no

slices.json

beside it, propose it; otherwise ask.

If the spec lacks a Behaviour or Seams section, name it, tell the user to run

/write-spec

, and end the turn.

获取调用时传入的路径。如果未传入路径，且恰好有一个

spec/features/<slug>/spec.md

在其旁边没有

slices.json

，则提出该路径供用户确认；否则询问用户。

如果规格说明缺少 Behaviour 或 Seams 章节，指出缺失项，告诉用户运行

/write-spec

，然后结束本轮。

2. Check the seams

2. 检查 Seams

Check that every

file:line

in Seams exists. A seam the spec marks as new has none; use the spec's exact phrase for it. If any file is missing, list every missing seam, tell the user to fix the spec, and end the turn.

Record the commit SHA and branch.

Look for a verification skill: a project skill, in

.agents/skills/

or a harness's skills folder, whose

SKILL.md

says it runs the product and records whether a check passed.

检查 Seams 中的每个

file:line

是否都存在。如果规格说明将某个 seam 标记为 new，它就没有对应的

file:line

；此时使用规格说明中的确切表述。如果有任何文件缺失，列出每个缺失的 seam，告诉用户修复规格说明，然后结束本轮。

记录 commit SHA 和 branch。

查找 verification skill：它可以位于

.agents/skills/

或 harness 的 skills 文件夹中，并且其

SKILL.md

声明会运行产品并记录检查是否通过。

3. Decompose

3. 拆分

A slice is the behaviours sharing one seam that cannot be split further without breaking the product. Slices are vertical, each checkable by someone using the product, never a layer. The non-vertical kinds:

```
prefactor
```
goes first when every feature slice would carry the same structural change.
Wide refactors run
```
expand
```
,
```
migrate
```
in batches sized by blast radius, then
```
contract
```
.

Split when a slice needs a second seam or claims more than about three behaviours. A field you cannot fill means the slice is wrong.

Edges are technical:

S2

is blocked by

S1

only when it cannot be built or tested until

S1

's code exists. The spec's Sequence section is not edges, and a chain where every slice blocks the next hides an edge that is not real.

Autonomy is mechanical:

hitl

when

done.manual

is non-empty or the slice needs an action an agent cannot perform, such as a secret, consent screen or deploy approval; otherwise

afk

With a verification skill, every check it can run goes in

done.automated

as verify steps, even if the spec filed it under Manual.

done.manual

keeps only human judgement of how something looks or reads.

一个切片是共享同一个 seam、且若继续拆分就会破坏产品的一组 behaviours。切片是垂直的，每个切片都可由使用产品的人进行验证，绝不能是某一层。非垂直切片类型包括：

如果每个 feature 切片都需要包含相同的结构性变更，则将
```
prefactor
```
放在最前面。
大范围重构先运行
```
expand
```
，再按 blast radius（影响范围）确定批次运行
```
migrate
```
，最后运行
```
contract
```
。

当一个切片需要第二个 seam 或涵盖超过大约三个 behaviours 时，应进行拆分。任何无法填写的字段都表明该切片划分有误。

依赖边是技术性的：只有当

S2

在

S1

的代码存在之前无法构建或测试时，

S2

才被

S1

阻塞。规格说明中的 Sequence 章节并不表示依赖边；如果每个切片都阻塞下一个切片并形成链式关系，就说明其中存在并不真实的依赖边。

自主性判定是机械性的：当

done.manual

非空，或切片需要 Agent 无法执行的操作（例如

secret

、

consent screen

或

deploy approval

）时，使用

hitl

；否则使用

afk

。

如果有 verification skill，它能运行的每项检查都应作为 verify 步骤放入

done.automated

，即使规格说明将其列在 Manual 项下。

done.manual

仅保留人对某项内容外观或表述效果的主观判断。

4. Outline

4. 列出大纲

Before filling fields, show one line per slice,

S2  feature  Parse the header line  blocked by: S1

, and ask:

Is the granularity right?
Are the edges right?
Should any slice be merged or split?

Wait, then apply corrections.

在填写字段之前，每个切片展示一行，例如

S2  feature  Parse the header line  blocked by: S1

，并询问：

粒度是否合适？
依赖边是否正确？
是否应该合并或拆分任何切片？

等待用户回答，然后应用修正。

5. Write the file

5. 写入文件

Write

spec/features/<slug>/slices.json

, beside the spec. Regenerate an existing slices file whole. Tell the user to commit the feature folder: implement-slice reads it from git.

json

{
  "spec": "spec/features/<slug>/spec.md",
  "commit": "<sha>",
  "branch": "<branch>",
  "slices": [
    {
      "id": "S1",
      "kind": "feature",
      "title": "<imperative phrase>",
      "behaviours": [1, 2],
      "seam": "<file:line from the spec's Seams section>",
      "blocked_by": [],
      "autonomy": "afk",
      "done": { "automated": ["<check>"], "manual": [] }
    }
  ]
}

```
id
```
:
```
S
```
plus a number, in outline order.

kind

feature

prefactor

expand

migrate

contract

```
behaviours
```
: numbers from the spec's Behaviour list, never text.
```
seam
```
: copied verbatim from Seams.
```
blocked_by
```
: ids whose code must exist first.
```
done.automated
```
: checks a machine runs.
```
done.manual
```
: what a person must look at.
Non-feature kinds also carry
```
scope
```
: free text on what the slice touches and leaves alone.

在规格说明旁写入

spec/features/<slug>/slices.json

。完整重新生成已有的 slices 文件。告诉用户提交 feature 文件夹：

implement-slice

会从 git 读取它。

json

{
  "spec": "spec/features/<slug>/spec.md",
  "commit": "<sha>",
  "branch": "<branch>",
  "slices": [
    {
      "id": "S1",
      "kind": "feature",
      "title": "<imperative phrase>",
      "behaviours": [1, 2],
      "seam": "<file:line from the spec's Seams section>",
      "blocked_by": [],
      "autonomy": "afk",
      "done": { "automated": ["<check>"], "manual": [] }
    }
  ]
}

```
id
```
：按大纲顺序为
```
S
```
加数字。

kind

：

feature

、

prefactor

、

expand

、

migrate

或

contract

。

```
behaviours
```
：来自规格说明 Behaviour 列表中的数字，绝不能是文本。
```
seam
```
：从 Seams 中原样复制。
```
blocked_by
```
：其代码必须先存在的切片 id。
```
done.automated
```
：机器运行的检查。
```
done.manual
```
：人必须查看的内容。
非 feature 类型还应包含
```
scope
```
：用自由文本说明该切片涉及什么以及不涉及什么。

6. Self-check

6. 自检

Read the file back and check:

Every Behaviour number is claimed by exactly one slice, and no others appear.
Every
```
seam
```
appears verbatim in Seams.
Only non-feature kinds carry
```
scope
```
.
```
blocked_by
```
ids exist and form no cycle.
A slice claiming no behaviours connects through
```
blocked_by
```
to one that claims some.
```
autonomy
```
follows step 3.
With a verification skill, no
```
done.manual
```
item is a check that skill can run.

Report each violation on its own line, like

S3: claims behaviour 4, already claimed by S2

, fix, and repeat until clean.

The slices file is the only output: implement nothing.

重新读取文件并检查：

每个 Behaviour 编号都恰好被一个切片认领，且不得出现其他编号。
每个
```
seam
```
都与 Seams 中的内容逐字一致。
只有非 feature 类型包含
```
scope
```
。
```
blocked_by
```
中的 id 均存在，且不构成循环。
未认领任何 behaviours 的切片必须通过
```
blocked_by
```
连接到至少一个认领了 behaviours 的切片。
```
autonomy
```
符合第 3 步的规则。
存在 verification skill 时，
```
done.manual
```
中不得包含该 skill 能运行的检查项。

每条违规单独占一行报告，例如

S3: claims behaviour 4, already claimed by S2

，然后修复，并重复检查，直到没有问题。

切片文件是唯一输出：不要实现任何内容。