Back to Details

cs-feat-accept

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

cs-feat-accept

cs-feat-accept

到这一步代码已经写完了，但流程没结束。这一阶段做四件事，缺一不可：
  1. 核对实现有没有偏离方案——逐层对照 
    {slug}-design.md
    的四个节，发现偏差当场修，**不是在报告里"记一下"**就过去
  2. 把 feature 归并到整体架构——对照方案 doc 第 4 节，实际去更新架构中心目录下的相关 doc
  3. 把变化回写到 requirement——对照方案 doc frontmatter 的 
    requirement
    字段，如果本次实现改变了对应 req 的用户故事 / 边界 / pitch 表述，触发 
    cs-req
    update 把 req doc 一起刷新（纯重构无 req 的 feature 跳过这步）
  4. 把完成状态回写到 roadmap——如果方案 doc frontmatter 有 
    roadmap
    / 
    roadmap_item
    字段，本阶段必须改 
    codestable/roadmap/{roadmap}/{roadmap}-items.yaml
    对应条目 
    status
    为 
    done
    ，并同步主文档子 feature 清单。没有这两个字段（feature 没从 roadmap 起头）就跳过这步
为什么这四件事都重要？只做第一件，新功能加进去了但项目级架构 doc 还说着老结构，下一个 feature 的设计阶段读到的就是过期信息。漏掉第二件，可能把"实现已经偏离方案"的事实掩埋——架构 doc 写得很漂亮，代码却不是那么回事。漏掉第三件，对外讲这系统"能做什么"的那份文档会慢慢和实际能力脱节，下一个用户来看的时候对不上。漏掉第四件，roadmap 规划层和实际进度脱节——主文档说这条还没做、items.yaml 还是 
planned
，但代码和 req 已经上线，下次要推进 roadmap 下一条的人会重复跑流程。
验收报告是工作流的闭环凭证。没产出报告 = 工作流未完成。这条不是仪式——后人查"上次这个功能到底验收时确认了哪些行为"，没有报告就只能去翻 git diff 重新推断。
共享路径与命名约定看 
codestable/reference/shared-conventions.md
第 0 节。
At this point, the code has been written, but the workflow is not yet complete. This phase involves four indispensable tasks:
  1. Verify if the implementation deviates from the design – Check layer by layer against the four sections of 
    {slug}-design.md
    . Fix any deviations on the spot, do not just "note them" in the report and move on
  2. Incorporate the feature into the overall architecture – Refer to Section 4 of the design doc, and actually update the relevant docs in the architecture center directory
  3. Update the requirement with changes – Refer to the 
    requirement
    field in the design doc's frontmatter. If this implementation changes the user story / boundaries / pitch description of the corresponding requirement, trigger 
    cs-req
    update to refresh the requirement doc (skip this step for features that are pure refactoring without requirements)
  4. Update the roadmap with completion status – If the design doc's frontmatter has 
    roadmap
    / 
    roadmap_item
    fields, must change the 
    status
    of the corresponding entry in 
    codestable/roadmap/{roadmap}/{roadmap}-items.yaml
    to 
    done
    , and sync the sub-feature list in the main document. Skip this step if the two fields are not present (the feature did not originate from the roadmap)
Why are these four tasks important? If only the first task is done, the new feature is added but the project-level architecture doc still describes the old structure, so the next feature's design phase will read outdated information. Skipping the second task may bury the fact that "the implementation has deviated from the design" – the architecture doc looks good, but the code does not match. Skipping the third task will gradually disconnect the document that tells external parties "what the system can do" from the actual capabilities, leading to inconsistencies when the next user checks. Skipping the fourth task will disconnect the roadmap planning layer from actual progress – the main document says the item is still unstarted, the items.yaml still shows 
planned
, but the code and requirement are already online, so the next person to advance the roadmap will repeat the process.
The acceptance report is the closed-loop proof of the workflow. No report produced = workflow not completed. This is not a formality – when future people check "what behaviors were confirmed during the acceptance of this feature last time", without a report, they can only infer from git diffs.
See Section 0 of 
codestable/reference/shared-conventions.md
for shared paths and naming conventions.

跟 design 的章节强依赖

Strong Dependency on Design Sections

本技能整套对照表、模板节、提示语都按 design 当前的章节编号和命名硬编码。design 那边重构章节名 / 调整编号，本技能必须同步——否则下面所有"第 X 节 XX"指针都会指错地方。
下面这两个章节快照是本技能消费的真相源。每次 design 升级时，先核对这两个快照是否还匹配 design 现状，不匹配就先改这里再往下用：
标准 design 章节快照：
  • 第 0 节：术语约定
  • 第 1 节：决策与约束（含需求摘要 / 挂载点清单 / 复杂度档位 / 关键决策 / 前置依赖 / 主流程概述）
  • 第 2 节：接口契约
  • 第 3 节：实现提示（含改动计划 / 实现风险 / 推进顺序 / 测试设计）
  • 第 4 节：与项目级架构文档的关系
Fastforward design 章节快照：
  • 第 0 节：需求摘要
  • 第 1 节：设计方案
  • 第 2 节：验收标准
  • 第 3 节：推进步骤
The entire comparison table, template sections, and prompts of this skill are hard-coded according to the current section numbers and names of the design. If the design refactors section names / adjusts numbers, this skill must be updated synchronously – otherwise, all the "Section X XX" pointers below will point to the wrong places.
The following two section snapshots are the source of truth consumed by this skill. Every time the design is upgraded, first check if these two snapshots still match the current design status; if not, modify them first before proceeding:
Standard Design Section Snapshot:
  • Section 0: Terminology Conventions
  • Section 1: Decisions and Constraints (including Requirement Summary / Mount Point List / Complexity Level / Key Decisions / Prerequisites / Main Process Overview)
  • Section 2: Interface Contract
  • Section 3: Implementation Tips (including Change Plan / Implementation Risks / Promotion Sequence / Test Design)
  • Section 4: Relationship with Project-level Architecture Documentation
Fastforward Design Section Snapshot:
  • Section 0: Requirement Summary
  • Section 1: Design Solution
  • Section 2: Acceptance Criteria
  • Section 3: Promotion Steps

启动检查

Startup Checks

1. 代码确实实现到位了

1. Code is fully implemented

git status / 最近提交里能看到本功能的代码改动。没看到就是 implement 还没收尾，先回去。
The code changes for this feature can be seen in git status / recent commits. If not, the implementation is not yet complete; go back first.

2. 方案 doc 完整

2. Design doc is complete

文件头有 YAML frontmatter，
doc_type=feature-design
、
feature
跟当前目录一致、
status=approved
、
summary
非空、
tags
≥ 2。
标准 design：四个节（0 术语约定、1 决策与约束、2 接口契约、3 实现提示）都有实质内容，第 4 节（与项目级架构文档的关系）已填写。
Fastforward design：四个节（0 需求摘要、1 设计方案、2 验收标准、3 推进步骤）都有实质内容。验收报告按下面这个对照表去映射方案：
验收报告节标准 design 对照Fastforward design 对照
1 接口契约核对方案第 2 节（接口契约）方案第 1 节（设计方案）的改动点
2 行为与决策核对方案第 1 节（决策与约束）方案第 0 节（需求摘要）
3 测试约束核对方案第 3 节（测试设计）方案第 2 节（验收标准）
4 术语一致性方案第 0 节（术语约定）无术语表，检查代码命名一致性即可
5 架构归并方案第 4 节（架构关系）通常无架构变更；如果确实无关，写"本次 fastforward 无架构维度变更"
The file has YAML frontmatter, with 
doc_type=feature-design
, 
feature
matching the current directory, 
status=approved
, non-empty 
summary
, and 
tags
≥ 2.
Standard Design: All four sections (0 Terminology Conventions, 1 Decisions and Constraints, 2 Interface Contract, 3 Implementation Tips) have substantive content, and Section 4 (Relationship with Project-level Architecture Documentation) is filled out.
Fastforward Design: All four sections (0 Requirement Summary, 1 Design Solution, 2 Acceptance Criteria, 3 Promotion Steps) have substantive content. Map the design to the acceptance report using the following comparison table:
Acceptance Report SectionStandard Design ReferenceFastforward Design Reference
1 Interface Contract CheckSection 2 of Design (Interface Contract)Change points in Section 1 of Design (Design Solution)
2 Behavior and Decision CheckSection 1 of Design (Decisions and Constraints)Section 0 of Design (Requirement Summary)
3 Test Constraint CheckSection 3 of Design (Test Design)Section 2 of Design (Acceptance Criteria)
4 Terminology ConsistencySection 0 of Design (Terminology Conventions)No terminology table; just check code naming consistency
5 Architecture IncorporationSection 4 of Design (Architecture Relationship)Usually no architecture changes; if indeed irrelevant, write "No architecture-level changes for this fastforward"

3. {slug}-checklist.yaml 状态

3. {slug}-checklist.yaml Status

{slug}-checklist.yaml
的生命周期看 
codestable/reference/shared-conventions.md
。本阶段只核对并更新 
checks
一段：
  • 文件存在，
    feature
    字段跟当前 feature 目录一致
  • steps
    所有条目 status 为 
    done
    （有 
    pending
    说明 implement 没完成，先退回）
  • checks
    列表非空，所有条目 status 为 
    pending
  • 不存在 → 停下来，让用户先回 design 阶段生成
See 
codestable/reference/shared-conventions.md
for the lifecycle of 
{slug}-checklist.yaml
. In this phase, only check and update the 
checks
section:
  • The file exists, and the 
    feature
    field matches the current feature directory
  • All entries in 
    steps
    have status 
    done
    (if there are 
    pending
    entries, the implementation is not complete; return first)
  • The 
    checks
    list is non-empty, and all entries have status 
    pending
  • If it does not exist → stop and ask the user to generate it in the design phase first

4. 把上下文读全

4. Read the full context

  • 方案 doc 全文（重点是第 1 节需求摘要 / 明确不做、第 2 节接口契约、第 3 节测试设计）
  • {slug}-checklist.yaml
  • 架构中心目录下方案 doc 第 4 节提到的所有 doc
  • 本次功能的代码改动（git log / git diff）
  • Full text of the design doc (focus on Section 1 Requirement Summary / Explicitly Not Done, Section 2 Interface Contract, Section 3 Test Design)
  • {slug}-checklist.yaml
  • All docs mentioned in Section 4 of the design doc in the architecture center directory
  • Code changes for this feature (git log / git diff)

5. 断点恢复

5. Breakpoint Recovery

如果 
{slug}-acceptance.md
已存在且有部分填好的节，看哪些节已有实质内容（有 checklist 勾选或文字填写），从下一个未完成节继续。同时检查 
{slug}-checklist.yaml
的 
checks
中已 
passed
的项，跳过已验证完的检查。汇报一句："上次验收做到第 X 节，我从第 Y 节继续。"
If 
{slug}-acceptance.md
already exists and has partially filled sections, check which sections have substantive content (checklist checked or text filled), and continue from the next incomplete section. Also, check the items in 
checks
of 
{slug}-checklist.yaml
that have status 
passed
, and skip the already verified checks. Report: "Last acceptance reached Section X, I will continue from Section Y."

验收报告模板

Acceptance Report Template

逐节填写，别跳节。报告路径在 feature 目录下，跟 
{slug}-design.md
聚合（具体位置看 
codestable/reference/shared-conventions.md
第 0 节）。
markdown
undefined
Fill in section by section, do not skip sections. The report path is in the feature directory, aggregated with 
{slug}-design.md
(see Section 0 of 
codestable/reference/shared-conventions.md
for the specific location).
markdown
undefined

{功能名称} 验收报告

{Feature Name} Acceptance Report

阶段：阶段 3（验收闭环） 验收日期：YYYY-MM-DD 关联方案 doc：{方案 doc 路径}
Phase: Phase 3 (Acceptance Closed-loop) Acceptance Date: YYYY-MM-DD Associated Design Doc: {Design Doc Path}

1. 接口契约核对

1. Interface Contract Check

对照方案 doc 第 2 节接口契约，逐一核查实现与契约的一致性：
契约示例逐项核对：
  • 示例 A（{文件路径 + 函数名}）：示例中的输入→输出 → 代码实际行为：{一致 / 偏差说明}
  • 示例 B：...
正式类型定义核对（如方案 doc 中有补充类型定义）：
  • 类型 X：{关键字段} → 代码里对应定义：{一致 / 偏差说明}
流程图核对（如方案 doc 中有 Mermaid 图）：
  • 图中的所有节点 / 调用关系，在代码中均有实际落点（grep 确认）
发现偏差就停下来先修代码或回填方案 doc。在报告里写"已知偏差，暂不处理"是反模式——下一次有人按方案找代码时会被这个偏差绊倒。
Check the consistency between the implementation and the contract against Section 2 of the design doc:
Item-by-item check of contract examples:
  • Example A ({File Path + Function Name}): Input→Output in example → Actual behavior in code: {Consistent / Deviation Description}
  • Example B: ...
Formal type definition check (if supplementary type definitions are included in the design doc):
  • Type X: {Key Fields} → Corresponding definition in code: {Consistent / Deviation Description}
Flowchart check (if there is a Mermaid diagram in the design doc):
  • All nodes / call relationships in the diagram have actual implementations in code (confirmed via grep)
If deviations are found, stop and fix the code or update the design doc first. Writing "Known deviation, temporarily not processed" in the report is an anti-pattern – the next person looking for code according to the design will be tripped by this deviation.

2. 行为与决策核对

2. Behavior and Decision Check

对照方案 doc 第 1 节决策与约束：
需求摘要逐项验证：
  • 行为 A：{描述 + 实测结果}
  • 行为 B：{描述 + 实测结果}
明确不做逐项核对：
  • 范围外事项 X 确实没做（grep / 代码 review 确认）
  • 范围外事项 Y 确实没做
关键决策落地：
  • 决策 D1：{决策内容} → 代码里如何体现：{描述}
挂载点反向核对（可卸载性）：
对照方案 doc 第 1 节"挂载点清单"，逐条核对两件事——真实挂入的位置跟清单一致；假设照清单逆向拔掉本 feature，能不能拔干净，还是会留孤儿代码 / 孤儿配置 / 孤儿数据结构。
  • 挂载点 M1：{清单里那条} → 代码实际落点：{文件或配置 key}，一致性：{一致 / 偏差说明}
  • 挂载点 M2：...
  • 反向核查：grep 代码里对本 feature 的所有引用，是否全部落在清单范围内？清单外的引用说明有挂载点漏记，补进方案 doc 第 1 节
  • 拔除沙盘推演：假设要移除本 feature，按清单逐条逆向操作后，是否还残留任何文件 / 字段 / 配置？残留的写进"遗留"或回去补挂载点
Fastforward design 方案没有挂载点清单的话，在本节补一次现场盘点：grep 本次改动命中的所有挂入位置，列清单写进报告，作为当下的卸载依据。
Check against Section 1 of the design doc (Decisions and Constraints):
Item-by-item verification of requirement summary:
  • Behavior A: {Description + Actual Test Result}
  • Behavior B: {Description + Actual Test Result}
Item-by-item check of explicitly not done items:
  • Out-of-scope item X is indeed not implemented (confirmed via grep / code review)
  • Out-of-scope item Y is indeed not implemented
Key decision implementation:
  • Decision D1: {Decision Content} → How it is reflected in code: {Description}
Reverse check of mount points (uninstallability):
Against the "Mount Point List" in Section 1 of the design doc, check two things for each item – the actual mount location matches the list; if this feature is removed reversely according to the list, can it be completely removed, or will orphan code / orphan configuration / orphan data structures remain?
  • Mount Point M1: {Entry in List} → Actual code location: {File or Configuration Key}, Consistency: {Consistent / Deviation Description}
  • Mount Point M2: ...
  • Reverse Verification: Grep all references to this feature in the code; are they all within the scope of the list? References outside the list indicate missing mount points; add them to Section 1 of the design doc
  • Removal Sandbox Simulation: If this feature is to be removed, after performing reverse operations item by item according to the list, are there any remaining files / fields / configurations? Record the remaining ones in "Legacy" or go back to supplement the mount points
If the Fastforward design does not have a mount point list, supplement an on-site inventory in this section: Grep all mount locations hit by this change, list them in the report as the uninstallation basis for now.

3. 测试约束核对

3. Test Constraint Check

对照方案 doc 第 3 节测试设计，逐条测试约束验证：
  • C1：{约束断言}
    • 验证方式：{类型系统 / 单测 / 集成测试 / 肉眼}
    • 结果：{通过 / 未通过 + 原因 + 补救方案}
  • C2：...
前端改动必须浏览器肉眼验证（typecheck 通过不代表用户用起来对）：
  • UI 区域 X：浏览器验证 OK / 截图链接
  • 交互行为 Y：浏览器验证 OK
Verify each test constraint against Section 3 of the design doc (Test Design):
  • C1: {Constraint Assertion}
    • Verification Method: {Type System / Unit Test / Integration Test / Visual Inspection}
    • Result: {Passed / Failed + Reason + Remediation Plan}
  • C2: ...
Frontend changes must be verified visually in the browser (typecheck passing does not mean it works correctly for users):
  • UI Area X: Verified OK in browser / Screenshot Link
  • Interaction Behavior Y: Verified OK in browser

4. 术语一致性

4. Terminology Consistency

对照方案 doc 第 0 节术语约定，grep 代码：
  • 术语 X：代码命中 N 处，全部一致 ✓
  • 术语 Y：代码命中 N 处，全部一致 ✓
  • 防冲突：方案 doc 第 0 节列的禁用词（如有），grep 无命中 ✓
发现不一致就回到代码改正，别在报告里写"已知差异"后跳过——理由同第 1 节。
Check against Section 0 of the design doc (Terminology Conventions) via grep:
  • Term X: Hit N times in code, all consistent ✓
  • Term Y: Hit N times in code, all consistent ✓
  • Conflict Prevention: No hits for forbidden words listed in Section 0 of the design doc (if any) ✓
If inconsistencies are found, go back to correct the code; do not write "Known difference" in the report and skip – the reason is the same as Section 1.

5. 架构归并

5. Architecture Incorporation

架构归并不是"在 architecture 里加一条指向本 feature design 的引用"——那样做等于让后来的读者打开 architecture 后还得跳回历史 design 才能看懂系统。目标是把本次 feature 里稳定、系统级可见的内容提炼进 architecture，让读者只看 architecture 就能看懂新能力的存在和形态。
对照方案 doc 第 4 节"与项目级架构文档的关系"，从本次 feature 里抽出三类东西，逐项实际写入对应架构 doc：
  • 名词归并：方案第 2 节新增 / 变化的实体、类型、对外契约，提炼进 architecture 的"结构与交互"或"数据与状态"节
  • 动词骨架归并：方案第 1 节主流程、关键编排、关键分支里跨模块可见的部分，更新进 architecture 的结构图 / 模块交互描述
  • 跨层纪律归并：方案第 1 节里跨 feature 稳定的约束（错误语义、幂等性、扩展点、可观测点、挂载点规约），补进 architecture 的"已知约束 / 边界情况"节
逐项核对：
  • 架构中心目录下的 doc X（{路径}）：
    • 本次需要归并进来的内容（名词 / 动词骨架 / 纪律 分别是什么）：{描述}
    • 已实际写入：✓ / 未更新（理由：{不需要归并的具体理由，例如"本 feature 的改动完全局限在单模块内部，没有系统级可见的新结构"}）
  • 架构中心目录下的 doc Y：...
如果方案 doc 第 4 节为空或描述过于简略，在此补充评估：
  • 本 feature 新增了哪些模块 / 改变了哪些接口 / 引入了哪些跨模块纪律
  • 架构总入口是否需要新增对本 feature 的描述（注意是描述，不是只贴 design 链接）
  • AGENTS.md
    是否需要补充新的规约或已知坑
判据：归并完成后，让一个没读过本次 design 的人打开 architecture，他应该能知道"系统里现在有这个能力、它的大致形态、别人和它交互时要遵守什么"。达不到这个标准就是归并没做到位。
架构归并是实际写文件的动作，不是自评"应该不需要改"，也不是"加个 design 链接就算数"。每条都要有明确结论。
Architecture incorporation is not "adding a reference to this feature design in the architecture" – that would force future readers to jump back to the historical design to understand the system after opening the architecture. The goal is to extract stable, system-visible content from this feature into the architecture, so that readers can understand the existence and shape of the new capability just by looking at the architecture.
Against Section 4 of the design doc "Relationship with Project-level Architecture Documentation", extract three types of content from this feature and write them into the corresponding architecture docs item by item:
  • Terminology Incorporation: New / changed entities, types, and external contracts in Section 2 of the design, extracted into the "Structure and Interaction" or "Data and State" section of the architecture
  • Verb Skeleton Incorporation: Cross-module visible parts of the main process, key orchestration, and key branches in Section 1 of the design, updated into the architecture's structure diagram / module interaction description
  • Cross-layer Discipline Incorporation: Cross-feature stable constraints (error semantics, idempotency, extension points, observability points, mount point specifications) in Section 1 of the design, added to the "Known Constraints / Boundary Cases" section of the architecture
Check item by item:
  • Doc X in the architecture center directory ({Path}):
    • Content to be incorporated this time (what are the terminology / verb skeleton / discipline respectively): {Description}
    • Actually written: ✓ / Not updated (Reason: {Specific reason, e.g., "The changes of this feature are completely limited within a single module, with no system-visible new structures"})
  • Doc Y in the architecture center directory: ...
If Section 4 of the design doc is empty or too brief, supplement the evaluation here:
  • Which modules did this feature add / which interfaces did it change / which cross-module disciplines did it introduce
  • Whether the architecture's main entry needs to add a description of this feature (note: it is a description, not just a link to the design)
  • Whether 
    AGENTS.md
    needs to add new specifications or known pitfalls
Criterion: After incorporation, a person who has not read this design should be able to know "this capability exists in the system, its general shape, and what rules others must follow when interacting with it" when opening the architecture. If this standard is not met, the incorporation is not done properly.
Architecture incorporation is an actual file-writing action, not a self-assessment of "should not need to change", nor is "adding a design link" sufficient. Each item must have a clear conclusion.

6. requirement 回写

6. Requirement Update

对照方案 doc frontmatter 的 
requirement
字段（以及第 1 节里任何涉及用户可感能力变化的描述），判断本次 feature 是否改变了对应 requirement 的用户故事 / 边界 / pitch：
  • requirement
    字段为空（纯重构 / 技术债）：跳过本节，写一句"本 feature 不新增能力，无 requirement 回写"
  • 有对应 req，但本次实现没改变能力的用户视角：写一句"req-{slug} 用户故事 / 边界未变，无需更新"
  • 有对应 req，且本次实现改变了 req 的边界 / 用户故事 / pitch 表述：
    • 需要更新的内容：{描述}
    • 已更新：✓（触发 
      cs-req
      update 模式实际执行）/ 未更新（理由：{具体理由}）
和架构归并一样，这是实际写文件的动作，不是自评"应该不需要改"。
Against the 
requirement
field in the design doc's frontmatter (and any descriptions in Section 1 involving changes to user-perceivable capabilities), determine whether this feature has changed the user story / boundaries / pitch of the corresponding requirement:
  • requirement
    field is empty (pure refactoring / technical debt): Skip this section, write "This feature does not add new capabilities, no requirement update needed"
  • Corresponding requirement exists, but this implementation does not change the user perspective of the capability: Write "The user story / boundaries of req-{slug} remain unchanged, no update needed"
  • Corresponding requirement exists, and this implementation changes the boundaries / user story / pitch description of the requirement:
    • Content to be updated: {Description}
    • Updated: ✓ (Triggered 
      cs-req
      update mode to execute actually) / Not updated (Reason: {Specific reason})
Like architecture incorporation, this is an actual file-writing action, not a self-assessment of "should not need to change".

7. roadmap 回写

7. Roadmap Update

对照方案 doc frontmatter 的 
roadmap
/ 
roadmap_item
字段：
  • 两个字段都为空（feature 未从 roadmap 起头）：跳过本节，写一句"本 feature 非 roadmap 起头，无回写"
  • 两个字段都有值：
    • 打开 
      codestable/roadmap/{roadmap}/{roadmap}-items.yaml
    • 找到 
      slug: {roadmap_item}
      的条目，核对 
      status
      当前为 
      in-progress
      、
      feature
      为当前 feature 目录名——不对就停下来找原因（design 阶段漏了回写？有人手工改过？）
    • 把 
      status
      改为 
      done
    • 用 
      python codestable/tools/validate-yaml.py --file {path} --yaml-only
      校验
    • 打开 
      {roadmap}-roadmap.md
      主文档，找到第 3 节子 feature 清单里对应 
      {roadmap_item}
      那条，把显示状态同步为 
      done
      （勾选状态、对应 feature 目录名两处保持和 items.yaml 一致）
    • 已更新：✓（回写位置：items.yaml + 主文档）
  • 两个字段不一致（只填了一个）：停下来补齐或澄清，不做回写
衔接协议的完整定义看 
codestable/reference/shared-conventions.md
第 2.5 节。
和架构归并、requirement 回写一样，这是实际写文件的动作，不是自评。
Against the 
roadmap
/ 
roadmap_item
fields in the design doc's frontmatter:
  • Both fields are empty (feature did not originate from the roadmap): Skip this section, write "This feature did not originate from the roadmap, no update needed"
  • Both fields have values:
    • Open 
      codestable/roadmap/{roadmap}/{roadmap}-items.yaml
    • Find the entry with 
      slug: {roadmap_item}
      , check that the current 
      status
      is 
      in-progress
      and 
      feature
      is the current feature directory name – if not, stop and find the reason (did the design phase miss the update? Did someone modify it manually?)
    • Change 
      status
      to 
      done
    • Validate with 
      python codestable/tools/validate-yaml.py --file {path} --yaml-only
    • Open the main document 
      {roadmap}-roadmap.md
      , find the corresponding 
      {roadmap_item}
      entry in the sub-feature list of Section 3, and sync the display status to 
      done
      (keep the check status and corresponding feature directory name consistent with items.yaml)
    • Updated: ✓ (Update locations: items.yaml + main document)
  • The two fields are inconsistent (only one is filled): Stop to complete or clarify, do not perform the update
See Section 2.5 of 
codestable/reference/shared-conventions.md
for the complete definition of the衔接协议 (wait, no, this should be "handover protocol") → "See Section 2.5 of 
codestable/reference/shared-conventions.md
for the complete definition of the handover protocol."
Like architecture incorporation and requirement update, this is an actual file-writing action, not a self-assessment.

8. 遗留

8. Legacy Items

  • 后续优化点（已开 issue 或加入 issue 列表）：{列表}
  • 已知限制：{列表}
  • 实现阶段"顺手发现"列表：{列表}

---
  • Follow-up optimization points (already created as issues or added to the issue list): {List}
  • Known limitations: {List}
  • "Found along the way" list from the implementation phase: {List}

---

核对节奏

Check Rhythm

逐节做，别跳：
  1. 第 1 节（接口契约）和第 2 节（行为与决策，含挂载点反向核对）——这两节最容易暴露"实现跟方案对不上"，先做。第 2 节的挂载点反向核对必须实际做 grep + 沙盘推演，不能凭印象勾选
  2. 第 3 节（测试约束）——逐条对照，涉及类型系统的让 typecheck 跑一遍，涉及单测 / 集成的让测试跑一遍
  3. 第 4 节（术语）——用 Grep，把命中数和位置写进报告
  4. 第 5 节（架构归并）——读完方案 doc 第 4 节后逐项执行。"整体不影响架构"一句话带过是反模式，要么找出影响在哪、要么明确写"X 节列出的某项确认无影响（理由）"
  5. 第 6 节（requirement 回写）——对照方案 frontmatter 的 
    requirement
    判断要不要更新对应 req；和架构归并同规则，有变化就触发 
    cs-req
    update 实际执行
  6. 第 7 节（roadmap 回写）——对照方案 frontmatter 的 
    roadmap
    / 
    roadmap_item
    ，有值就改 items.yaml 对应条目为 
    done
    并同步主文档；无值跳过
  7. 第 8 节（遗留）——把实现阶段攒下的"顺手发现"和已知限制都记进来
各节核对完后，逐条更新 
{slug}-checklist.yaml
的 
checks
：
  • 验证通过 → 
    status
    改为 
    passed
  • 验证失败 → 
    status
    改为 
    failed
    ，先修代码 / 方案再改回 
    passed
  • 所有 checks 都为 
    passed
    后，验收报告才算完成
Do section by section, do not skip:
  1. Section 1 (Interface Contract) and Section 2 (Behavior and Decision, including reverse check of mount points) – these two sections are most likely to expose "implementation does not match the design", do them first. The reverse check of mount points in Section 2 must be done via actual grep + sandbox simulation, not checked by impression
  2. Section 3 (Test Constraints) – Check item by item; for those involving the type system, run typecheck; for those involving unit tests / integration tests, run the tests
  3. Section 4 (Terminology) – Use Grep, write the hit count and locations into the report
  4. Section 5 (Architecture Incorporation) – Execute item by item after reading Section 4 of the design doc. Writing "No overall impact on architecture" in one sentence is an anti-pattern; either find the impact or clearly write "Confirmed that item listed in Section X has no impact (Reason)"
  5. Section 6 (Requirement Update) – Determine whether to update the corresponding requirement against the 
    requirement
    field in the design's frontmatter; follow the same rules as architecture incorporation, trigger 
    cs-req
    update to execute actually if there are changes
  6. Section 7 (Roadmap Update) – Check against the 
    roadmap
    / 
    roadmap_item
    fields in the design's frontmatter; if there are values, change the corresponding entry in items.yaml to 
    done
    and sync the main document; skip if there are no values
  7. Section 8 (Legacy Items) – Record all "found along the way" items and known limitations accumulated during the implementation phase
After checking each section, update the 
checks
in 
{slug}-checklist.yaml
item by item:
  • Verified passed → Change 
    status
    to 
    passed
  • Verified failed → Change 
    status
    to 
    failed
    , fix the code / design first then change back to 
    passed
  • The acceptance report is only considered complete when all checks are 
    passed

退出条件

Exit Conditions

  • 验收报告 8 节都填完
  • 第 1 节接口契约核对全部勾选，无未处理偏差
  • 第 2 节行为与决策核对全部勾选，含挂载点反向核对（grep 无清单外引用、拔除沙盘推演无残留）
  • 第 3 节测试约束核对全部勾选（未通过的有补救方案），前端改动已浏览器验证
  • 第 4 节术语一致性无遗漏
  • 第 5 节架构归并每条都有明确结论，需要更新的 doc 已实际写入
  • 第 6 节 requirement 回写有明确结论：跳过 / 未变 / 已更新三种之一
  • 第 7 节 roadmap 回写有明确结论：跳过（非 roadmap 起头）/ 已更新（items.yaml + 主文档同步）两种之一；已更新的 items.yaml 通过 
    validate-yaml.py
    校验
  • {slug}-checklist.yaml
    所有 checks 的 status 都已更新为 
    passed
  • 用户终审确认
  • All 8 sections of the acceptance report are filled out
  • All items in Section 1 (Interface Contract Check) are checked, with no unprocessed deviations
  • All items in Section 2 (Behavior and Decision Check) are checked, including the reverse check of mount points (no out-of-list references via grep, no residues in removal sandbox simulation)
  • All items in Section 3 (Test Constraint Check) are checked (failed items have remediation plans), frontend changes have been verified in the browser
  • No omissions in Section 4 (Terminology Consistency)
  • Each item in Section 5 (Architecture Incorporation) has a clear conclusion, and the docs that need to be updated have been actually written
  • Section 6 (Requirement Update) has a clear conclusion: One of skip / unchanged / updated
  • Section 7 (Roadmap Update) has a clear conclusion: One of skip (did not originate from roadmap) / updated (items.yaml + main document synced); the updated items.yaml has passed 
    validate-yaml.py
    verification
  • All checks in 
    {slug}-checklist.yaml
    have been updated to 
    passed
  • User final approval confirmed

收尾提交

Final Commit

按 
codestable/reference/shared-conventions.md
第 4 节"收尾提交（scoped-commit）"的规则执行。本阶段的特定要点：
  • 提交范围：功能代码 + 方案 doc + 验收报告 + 本次实际更新过的架构 doc + 本次实际更新过的 requirement doc + 本次实际改过的 roadmap items.yaml / 主文档。代码交付要带文档，否则下次做 feature 的人查不到上下文。
  • 提交是收尾推荐序列的最后一环（见下文"退出后"）——前面那几项问完，再回到提交。
Execute according to the rules of "Final Commit (scoped-commit)" in Section 4 of 
codestable/reference/shared-conventions.md
. Specific points for this phase:
  • Commit Scope: Feature code + design doc + acceptance report + architecture docs actually updated in this phase + requirement docs actually updated in this phase + roadmap items.yaml / main document actually modified in this phase. Code delivery must include documentation, otherwise the next person working on the feature cannot find the context.
  • The commit is the last step in the recommended final sequence (see "After Exit" below) – ask about the previous items first, then return to the commit.

退出后

After Exit

告诉用户："验收报告已就绪，架构文档已归并，cs-feat 工作流走完。后续如发现 BUG，走 issue 修复工作流（不再回到本工作流）。"
然后按 
codestable/reference/shared-conventions.md
第 3 节的收尾推荐顺序，逐项一句话提示（用户说"不用"立刻跳过）：
  1. 本次 feature 暴露出值得复用的坑点或经验 → "需要沉淀一条 learning 文档吗？（走 
    cs-learn
    ，会写入 
    codestable/compound/
    ）"
  2. 引入了超出单个功能的长期约束 / 技术选型 → "需要把这条决定归档吗？（走 
    cs-decide
    ）"
  3. 方案 doc 第 2 节有接口变更 / 第 1 节有用户可见行为变更 → "需要更新开发者或用户指南吗？（走 
    cs-guide
    ）"
  4. 新增 / 修改了库公开接口（组件、函数、命令等） → "需要更新库 API 参考文档吗？（走 
    cs-libdoc
    ）"
  5. 最后问一次是否需要代为提交本次代码和文档（scoped-commit）。用户同意时，按收尾提交规则执行到 commit 完成。
可以建议：
  • 提交时把方案 doc + 验收报告 + 更新后的架构 doc 当作同一次提交的一部分
  • 验收报告里"遗留"的后续优化点真要做的话另开新一轮 cs-feat 流程，不要在现有 PR 里塞
Tell the user: "The acceptance report is ready, the architecture docs have been incorporated, and the cs-feat workflow is completed. If bugs are found later, follow the issue fix workflow (do not return to this workflow)."
Then, according to the recommended final sequence in Section 3 of 
codestable/reference/shared-conventions.md
, give one-sentence prompts item by item (skip immediately if the user says "no"):
  1. This feature exposed pitfalls or experiences worth reusing → "Do you need to create a learning document? (Follow 
    cs-learn
    , it will be written to 
    codestable/compound/
    )"
  2. Introduced long-term constraints / technical selections beyond a single feature → "Do you need to archive this decision? (Follow 
    cs-decide
    )"
  3. The design doc has interface changes in Section 2 / user-visible behavior changes in Section 1 → "Do you need to update the developer or user guide? (Follow 
    cs-guide
    )"
  4. Added / modified public library interfaces (components, functions, commands, etc.) → "Do you need to update the library API reference doc? (Follow 
    cs-libdoc
    )"
  5. Finally ask if you need to commit this code and documentation on behalf of the user (scoped-commit). If the user agrees, execute according to the final commit rules until the commit is completed.
You can suggest:
  • Include the design doc + acceptance report + updated architecture doc as part of the same commit
  • If the follow-up optimization points in the "Legacy Items" section of the acceptance report are to be implemented, start a new round of cs-feat workflow instead of adding them to the existing PR

容易踩的坑

Common Pitfalls

  • "测试都过了" → 测试约束 ≠ 测试用例，要逐条核对第 3 节测试设计
  • "我肉眼看了一下没问题" → 按清单走，逐项勾选
  • 第 1 节发现接口偏差后在报告里写"已知偏差"而不去修代码或回填方案 doc
  • 第 2 节挂载点反向核对只看清单不 grep 代码——漏记的挂载点就这么溜进项目，后面想拔拔不干净
  • 第 4 节术语 grep 发现不一致就在报告里写"已知差异"而不去改代码
  • 第 3 节前端改动只 typecheck 没在浏览器跑过
  • 第 5 节架构归并只写"整体不影响架构"一句话，没逐条核查方案 doc 第 4 节
  • 架构 doc 需要更新而只写"建议以后更新"——归并是当下的动作，不是建议
  • 第 7 节 roadmap 回写时只改了 items.yaml 没同步主文档子 feature 清单——两份必须一致，否则人读主文档时看到旧状态
  • frontmatter 有 
    roadmap
    / 
    roadmap_item
    却在第 7 节写"跳过"——有值就必须回写，跳过只适用于没填这两个字段的 feature
  • 报告写完没让用户终审就宣告"工作流完成"
  • 工作流收尾时没问用户是否需要代为 commit
  • 用户没明确同意就直接 
    git commit
  • "All tests passed" → Test constraints ≠ test cases; check each item in Section 3 (Test Design)
  • "I checked it visually and it's fine" → Follow the checklist and check item by item
  • When deviations are found in Section 1, write "Known deviation" in the report instead of fixing the code or updating the design doc
  • In the reverse check of mount points in Section 2, only look at the list without grepping the code – missing mount points slip into the project, making it impossible to remove them completely later
  • When inconsistencies are found in Section 4 via grep, write "Known difference" in the report instead of fixing the code
  • For frontend changes in Section 3, only run typecheck without verifying in the browser
  • In Section 5 (Architecture Incorporation), only write "No overall impact on architecture" in one sentence without checking each item in Section 4 of the design doc
  • When the architecture doc needs to be updated, only write "Suggest updating later" – incorporation is an immediate action, not a suggestion
  • When updating the roadmap in Section 7, only modify items.yaml without syncing the sub-feature list in the main document – the two must be consistent, otherwise people will see the old status when reading the main document
  • The frontmatter has 
    roadmap
    / 
    roadmap_item
    but write "Skip" in Section 7 – if there are values, the update must be performed; skip only applies to features without these fields
  • Declare "workflow completed" without getting user final approval after writing the report
  • Do not ask the user if you need to commit on their behalf when finishing the workflow
  • Directly execute 
    git commit
    without explicit user approval