to-design — 设计提案（决策与取舍）

只在有真岔口要留档时才用。 产出的是「为什么这么选」，不是长 SPEC。

工作状态、证据层、三个 profile 的边界、产物落点见 ../loop-it/CONTRACT.md——本文件不复述。

设计文档不是契约。 契约在 issue 正文（CONTRACT 第 1 节）。被实现证伪或已经过时，就直接重写或删掉，不要供着。

何时调用

判据是固定清单，不许自由心证。碰了下面任何一条才用它：

（与 CONTRACT 第 5 节的危险面同源：那里是停点判据，这里是留档判据。）

一条都没碰 → 不要写设计文档，直接往下。 装得进一个上下文就走 /loop-it；需求还没成形就先 /prd。

不问「要不要写文档」，问「这里有没有真岔口值得留档」。

输入

PRD、issue、半成形的想法都行——输入越薄，浮现决策问得越多。

（可选）扫一遍代码库，把设计落在现实上：既有模式、前例、约束、真实痛点。Background 引用户仓库里的真实代码最有说服力。

输出

<scope>/documents/design-<feature>.md，紧挨 PRD（落点规则见 CONTRACT 第 8 节）。

Go 提案的骨架可以保留，但按需取用：

不适用就删，删得显眼就说明原因。没有 Rationale 的设计文档不值得写：把已知的东西抄一遍不是产出。

PRD 的映射：Problem → Background（真实痛点 + 量化）；Goals → Abstract（提炼最重要的承诺）；验收条件 → Design（渐进式示例）；Technical Considerations → Design + Rationale；Non-Goals → Rationale（「我们没做 X，因为 Y」）；Risks → Compatibility + Implementation。

文风（照搬 Go 文档）

• 主语：决策用「我们」，行为用代码本身当主语；禁止无主语的被动腔。
• 句子：先用短句拍板，再用信息密集的长句铺开机制，长短交替。
• 段落：一段只讲一件事，结论先行；小标题写成完整论点句——写 老代码不受影响，编译结果与之前完全一致，而不是 兼容性。
• 语气：克制的诚实，承认代价；加粗全文只用一次。

自检三条：标题是「做什么」的结论不是名词短语；Rationale 至少列一个被放弃的方案；没有 TBD / TODO——要么解决，要么挪进 Open Questions。

浮现决策

动笔前先找出真岔口——一个有能力的工程师可能合理走两个方向的地方——并解决它们。

每个岔口都记下你没选的那条路，它就是 Rationale。没有备选方案时，强迫自己想「最朴素的做法是什么、为什么不够」：总有一个被否决的基线。

边界

• 契约不在这里：表 / 接口 / schema 归 /to-issues 的 issue 正文。
• HTML 只是可选呈现层，Markdown 才是主产物 → references/html-render.md。
• 不新增审批闸门：落盘即视为可用，不等「回复 OK」；反馈一律当修订，直接应用并重存。
• 方案最终被否也照写——记录「这条路为什么走不通」本身就是产物，Status 标 Rejected。
• 特性太大 → 按边界拆成多篇，互相链接。

失败怎么办

与其它技能的关系

/prd（要什么）→ /to-design（为什么这么选，本技能）→ /to-issues（issue 正文里的契约）→ /loop-it → /review-it → /ship-it