trim-spec

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Trim Spec

精简规格说明书

A long spec is usually not verbose — it is duplicated. The same rule sits in a decision, in the outline, and in an AC, and the copies have drifted apart. The method is one column,

restated_at

: for every claim, where else is this stated?

冗长的规格说明书通常并非表述啰嗦，而是存在内容重复。同一条规则会出现在决策内容、大纲以及验收标准（AC）中，且各副本之间已出现偏差。我们的方法是新增一列

restated_at

：针对每一项声明，记录该声明还在哪些位置出现过。

Input

输入

Target — a file path or a spec folder (
```
meta/specs/NNN-slug/
```
), trimmed in place.
Precondition — a consistency audit has run on this target. If not, run one first (the
```
reviewer
```
agent, criteria: any two statements of one rule that disagree). De-duplicating an unaudited doc can delete the correct copy and keep the stale one.
Class — PIPELINE when another skill greps this file, else STANDALONE. The class decides the shape answer in Step 2 and whether Step 4's anchor pass runs.

目标 — 文件路径或规格说明书文件夹（
```
meta/specs/NNN-slug/
```
），将在原位置完成精简。
前置条件 — 已对目标文档执行一致性审核。若未审核，需先运行审核（由
```
reviewer
```
Agent执行，审核标准：同一规则的任意两种表述存在分歧）。对未审核的文档去重可能会删除正确版本，保留过时版本。
类别 — 若有其他skill会检索该文件，则为PIPELINE；否则为STANDALONE。类别将决定步骤2的输出形式，以及是否执行步骤4的锚点验证环节。

Steps

步骤

Step 1 — Inventory every claim, extract only

步骤1 — 梳理所有声明，仅提取内容

Fan out

general-purpose

agents partitioned by section (3 for ~700 lines). Each returns one row per normative claim:

claim | at | type | restated_at | conf

```
type
```
— MECHANISM (symbol, signature, constant, formula, state transition — what an implementer types) · CHOICE · WHY · EVIDENCE (measured or live-verified, with its source) · UI-COPY (exact string, style token) · HISTORY.
```
at
```
— the section heading or decision id the claim lives under.
```
restated_at
```
— where else in the file the claim is stated, VERBATIM or PARAPHRASE.
Never cite a line number in either — the cut renumbers every line, so a line-keyed inventory goes stale while you are still using it.
```
conf
```
— 0.00–1.00 on the
```
restated_at
```
call.

Instruct them explicitly: extract only, no recommendations.

调用按章节划分的

general-purpose

Agent（约700行文档分配3个Agent）。每个Agent返回每条规范性声明对应的一行数据：

claim | at | type | restated_at | conf

```
type
```
— MECHANISM（符号、签名、常量、公式、状态转换——即开发者需要编写的内容）· CHOICE（决策选择）· WHY（决策原因）· EVIDENCE（经过测量或实时验证的内容，并标注来源）· UI-COPY（精确字符串、样式令牌）· HISTORY（历史记录）。
```
at
```
— 声明所在的章节标题或决策ID。
```
restated_at
```
— 该声明在文档中其他出现的位置，分为VERBATIM（完全一致）或PARAPHRASE（改写表述）。
禁止引用行号——精简操作会重新编排所有行号，基于行号的梳理结果在使用过程中会很快失效。
```
conf
```
—
```
restated_at
```
匹配结果的置信度，范围0.00–1.00。

需明确指示Agent：仅提取内容，不提供任何建议。

Step 2 — Derive the cut inputs, then confirm the plan

步骤2 — 生成精简输入，确认执行方案

Sole homes — every claim whose
```
restated_at
```
is
```
unique
```
. Untouchable. Before collapsing any block, confirm each fact in it has a live copy outside it; that copy is the sole home, not the block.
Drifted pairs — copies of one rule that disagree. Reconcile which one is true before choosing a survivor, or the cut silently picks a side.
Per-block survivors — for each replaced decision, every fact stated nowhere else. Do not stop at the first.
Partially superseded decisions — status still
```
locked
```
, one clause dead, the rest authoritative. Only the dead clause goes.

A PIPELINE target stays one file: moving a decision out carries its

Status: open

and

[NEEDS CLARIFICATION:

markers out of grep range, so

tech-design

and

write-plan

report a blocked spec as locked (Gate anchors,

skills/product-interview/SKILL.md

). No skill reads a second file.

A STANDALONE target may split builder material (MECHANISM · UI-COPY · live EVIDENCE) from maintainer material (CHOICE · WHY · HISTORY · disproved EVIDENCE).

Group the claims by

type

and total the lines of the sections holding each group — that is how small each shape still open to you could get.

Show the cost-ordered plan and those totals, then

AskUserQuestion

唯一载体 — 所有
```
restated_at
```
为
```
unique
```
的声明。此类声明不可修改。在合并任何内容块前，需确认块内每个信息点在块外都有有效副本；该副本即为唯一载体，而非内容块本身。
偏差副本对 — 同一条规则的不同副本存在分歧。在选择保留版本前需先确认哪个版本正确，否则精简操作会默认选择其中一方，且不会发出提示。
块内保留内容 — 对于每个被替代的决策，需保留所有未在其他位置出现的信息点。不可仅保留第一个信息点。
部分失效的决策 — 状态仍为
```
locked
```
，但部分条款已失效，其余条款仍具权威性。仅删除失效条款。

PIPELINE类目标需保持为单个文件：若将决策内容移出，其

Status: open

和

[NEEDS CLARIFICATION:

标记会超出检索范围，导致

tech-design

和

write-plan

将已阻塞的规格说明书误判为已锁定（参考锚点规则，见

skills/product-interview/SKILL.md

）。没有skill会读取第二个文件。

STANDALONE类目标可将面向开发者的内容（MECHANISM · UI-COPY · 有效EVIDENCE）与面向维护者的内容（CHOICE · WHY · HISTORY · 已被推翻的EVIDENCE）拆分。

按

type

对声明分组，并统计每组内容所在章节的行数——这是各类型内容可精简到的最小规模。

展示按精简成本排序的方案及行数统计，然后调用

AskUserQuestion

确认。

Step 3 — Cut in cost order

步骤3 — 按成本顺序执行精简

Every deletion cites a

restated_at

or a survivor row.

Scaffolding — uniform status lines and empty
```
Supersedes:
```
/
```
Superseded-by:
```
fields. Replace with one convention note stating the exact field form a reopened decision re-adds — the lock gate greps the
```
Status:
```
line's exact form; nothing greps the supersession fields.
Superseded blocks → one table — id, what it was, what replaced it, its survivors quoted. This is the one sanctioned exception to "the only edits to a superseded block are Status + Superseded-by" (canonical template,
```
skills/product-interview/SKILL.md
```
), and it holds only because the table quotes every survivor.
Resolved open questions carrying nothing unique.
Duplicate mechanism — one home per rule: the Structure Outline. Decisions state the choice and point at it.
Merged views — a file map, a per-file walk and a "files touched" list are three views of one thing.
Wording, last — invoke the
```
tighten-instruction
```
skill via the Skill tool. Never change a fact, and never a line break: rewrapping a long AC moves its
```
[tag]
```
to a second line and silently drops that AC downstream (Gate anchors rule 4).

Keep untouched: exact UI copy and style tokens, ACs, constraints holding live-verified facts, and the Structure Outline's schemas, signatures and file list.

每一处删除操作都需引用

restated_at

或保留内容的行数据。

框架内容 — 统一的状态行和空的
```
Supersedes:
```
/
```
Superseded-by:
```
字段。替换为一条约定说明，明确重新开启决策时需添加的字段格式——锁定锚点会检索
```
Status:
```
行的精确格式；没有检索工具会关注替换相关字段。
已被替代的内容块→合并为一张表格 — 包含ID、原内容、替代内容、保留内容引用。这是唯一允许打破“对已被替代内容块的唯一编辑仅为修改Status和Superseded-by字段”规则的情况（参考标准模板，见
```
skills/product-interview/SKILL.md
```
），前提是表格中引用了所有保留内容。
已解决的开放问题 — 不包含任何唯一信息的问题。
重复的MECHANISM内容 — 每条规则仅保留一个载体：结构大纲。决策内容中仅说明选择结果并指向大纲。
重复的视图内容 — 文件映射、逐文件说明和“涉及文件列表”是同一内容的三种呈现形式。
措辞优化（最后执行） — 通过Skill工具调用
```
tighten-instruction
```
skill。绝不修改任何信息，也绝不更改换行：重新排版过长的AC会将其
```
[tag]
```
移至第二行，导致下游流程中该AC被静默忽略（参考锚点规则4）。

以下内容不可修改：精确的UI文案和样式令牌、AC、包含实时验证信息的约束条件、结构大纲中的 Schema、签名和文件列表。

Step 4 — Prove nothing was lost, at both grains

步骤4 — 验证无信息遗漏，覆盖两个粒度

Facts. Give one fresh

general-purpose

agent both versions and one falsifiable task: find facts present in the original and absent from the trimmed file. Not "review the trim".

Not a finding — removed redundancy, shorter wording, reordering, scaffolding removal.
Seed it with the sole homes, the survivors, and every exact string, token and citation.
Search the whole file before declaring loss — facts move sections.
Split across two agents when one context cannot hold both versions.

Anchors — PIPELINE only.

Canonical greps — re-run them verbatim from Gate anchors in
```
skills/product-interview/SKILL.md
```
; never re-derive them.
Other anchors — the headings a gate greps, id prefixes, marker tokens, one-physical-line ACs.
Headings kept only as anchors — comment them, naming what greps each one, or the next trim removes it.

Fix every finding, then grep each restored string to confirm it landed.

信息点验证。指派一个新的

general-purpose

Agent同时处理原版本和精简后的版本，执行一项可证伪的任务：找出原版本中存在但精简版本中缺失的信息点。不可仅要求“审核精简结果”。

不视为遗漏 — 移除冗余内容、缩短措辞、调整顺序、删除框架内容。
初始提示 — 提供唯一载体、保留内容、所有精确字符串、令牌和引用信息。
声明遗漏前需检索整个文件 — 信息点可能已转移至其他章节。
若单个Agent无法同时容纳两个版本 — 拆分任务由两个Agent执行。

锚点验证 — 仅适用于PIPELINE类目标。

标准检索 — 严格按照
```
skills/product-interview/SKILL.md
```
中锚点规则的原文重新执行检索；不可自行推导检索规则。
其他锚点 — 检索工具依赖的标题、ID前缀、标记令牌、单行AC。
仅作为锚点保留的标题 — 添加注释说明哪个检索工具依赖该标题，否则下次精简操作会将其删除。

修复所有遗漏问题，然后检索每个恢复的字符串以确认其已正确归位。

Step 5 — Report

步骤5 — 生成报告

**Trim complete — <file>:**
- lines: [before] → [after] ([net], [%])
- drifted pairs reconciled: [id + which copy was true | none]
- restored by the loss pass: [fact — why it was unique | none]
- anchors kept only as anchors: [anchor — what greps it | none]
- over the Step-2 estimate: [by how much, and why | no]

**精简完成 — <文件>:**
- 行数: [原行数] → [精简后行数] ([净减少量], [减少百分比])
- 已调和的偏差副本对: [ID + 正确版本 | 无]
- 遗漏验证环节恢复的内容: [信息点 — 唯一原因 | 无]
- 仅作为锚点保留的内容: [锚点 — 依赖的检索工具 | 无]
- 超出步骤2预估量: [超出量及原因 | 无]

Rules

规则

Never cut to hit a number. The target is "no fact lost"; size is the byproduct.

绝不以达到行数指标为精简目标。核心目标是“无信息遗漏”；文件大小仅是副产品。