cs-feat-accept

cs-feat-accept

Required reading at startup

Before starting any judgment or action, first run CodeStable preflight: read .codestable/attention.md; if missing, first cs-onboard; do not read external AI entry points as a substitute (see .codestable/reference/execution-conventions.md）。

The code is already written, but the process is not over. This stage does four things, none of which can be skipped:

1. Check whether the implementation deviated from the plan—compare layer by layer against {slug}-design.md, fix deviations on the spot, **do not just "note it down"** in the report and move on
2. Inventory domain impact—identify whether this introduces new terminology / structural decisions, prompt the user to go through cs-domain to write CONTEXT.md / ADR (do not write it on their behalf in accept)
3. Record capability into requirement—after the capability corresponding to a draft req is implemented, upgrade it to current (retain the vision, append a change log); backfill capabilities that never had a req written
4. Write completion status back to roadmap—when the plan frontmatter has the roadmap / roadmap_item fieldmustchange the corresponding item in items.yaml to done and sync the main document

The cost of missing any one of these: CONTEXT.md / adrs/ fail to keep up and the next feature reads wrong terminology; req and actual capability become disconnected; the roadmap planning layer and actual progress become disconnected, and the next push repeats the process.

Acceptance principle: acceptance is the final audit, not a tidy-up of an implementation report. Re-read the original design and checklist, and re-verify item by item against the final workspace; a pass claimed during implementation can only be treated as a clue, not a conclusion. If gaps are found, first fix code / plan / documents and re-verify, then write the pass.

Advancement principle: the acceptance stage must close tasks using repository facts, not close tasks using conversational self-reports. The final conclusion must answer four questions: whether the original contract is satisfied, whether the verification evidence is sufficient and still holds in the final state, whether the promised deliverables are actually written to disk, and whether the reusable knowledge learned this time has entered CodeStable's sedimentation outlets.

Independent audit boundary: per .codestable/reference/execution-conventions.md 's Task agent selection rules, a read-only acceptance auditor may be launched to review design/checklist/review/QA/final diff and status write-back candidates; but the auditor can only return findings and must not write {slug}-acceptance.md, checklist, roadmap, requirement, or status files. acceptance is a process-closing action; the final verdict, status advancement, and file writes must be completed by the current main-process owner.

No report produced = workflow not completed. When later people check "which behaviors were confirmed at the last acceptance of this feature", with no report they can only dig through git diff and re-infer.

For shared paths and naming conventions see .codestable/reference/shared-conventions.md section 0.

This skill defaults to L3, and follows Global Route Governance: do not freely rewrite long-term requirement during the accept stage; capability-boundary changes must first have an owner-approved req delta, and if the delta is missing, stop and write approval-report.md. See the same package's reference.md。

---

Strong dependency on design's sections

This skill's entire mapping table is hardcoded to design's current section numbering.When design upgrades section names / numbering, this skill must be synced, otherwise all the "section X" pointers below point to the wrong places.

Standard design section snapshot：

• Section 0: Terminology conventions
• Section 1: Decisions and Constraints (requirement summary / complexity level / key decisions / prerequisites)
• Section 2: Terminology and orchestration (2.1 terminology layer / 2.2 orchestration layer / 2.3 mount points / 2.4 rollout strategy)
• Section 3: Acceptance contract (key scenario checklist + reverse verification items)
• Section 4: Domain impact (new terminology / structural decisions / process-level constraints)

Fastforward design: Section 0 requirement summary / Section 1 design plan / Section 2 acceptance criteria / Section 3 rollout steps

---

Startup check

1. Code is actually implemented—git status / recent commits show changes for this feature; otherwise return to implement
2. Plan doc is complete——frontmatter doc_type=feature-design / feature consistent / status=approved / summary non-empty / tags >= 2; for standard design, Sections 0/1/2/3 + Section 4 are filled in
3. {slug}-checklist.yaml—exists and feature consistent;steps all done(has pending return to implement);checks non-empty and all pending
4. {slug}-review.md—exists and frontmatter doc_type=feature-review、status=passed; no unresolved blocking findings. If missing → first run cs-code-review; if there is blocking → return to cs-feat-impl review-fix; if status is not passed → do not enter acceptance
5. Gate / DoD evidence—in goal / gate mode, read {slug}-evidence-pack.md、{slug}-gate-results.json、{slug}-dod-results.json; if missing or if a blocking DoD has no pass evidence, return to the implementation gate.
6. Source of verification evidence—independent cs-feat-qa is not a hard prerequisite for standalone accept; but acceptance must have verification evidence of equivalent strength:
   • Already has {slug}-qa.md: read and re-check. frontmatter must be doc_type=feature-qa、status=passed; failed / blocked → return to cs-feat-impl qa-fix; if status is not passed → do not enter acceptance.
   • Does not have {slug}-qa.md: do not force switching to run cs-feat-qa. In this accept, establish Inline Verification Matrix, against design Section 3, checklist checks, review Test And QA Focus / residual risk and project test entry points, run verification on the spot, and write the evidence into acceptance Section 3 and Section 10 final audit. This mode is equivalent to "accept-inline QA", but does not additionally generate a QA report.
   • Goal mode exception:cs-roadmap-impl-goal The protocol explicitly requires generating a QA report per feature; when goal mode lacks {slug}-qa.md , stop according to the goal protocol, and do not use accept-inline.
7. Core evidence re-check—regardless of whether the evidence comes from a QA report or accept-inline, re-check by the same standard:
   • Functional or mixed feature: the core functional paths in design Section 3, checklist checks, review QA focus must have runtime evidence. If the core paths were not run, the real user/API/runtime paths were not verified, or required commands were not executed, acceptance must state status=blocked. Next, choose according to the cause: code/test gap → cs-feat-impl after qa-fix, rerun review and accept-inline; environment gap → fill the environment first; user wants an independent QA report → run cs-feat-qa。
   • Non-functional feature: e2e / browser / API is not required, but it must be stated why end-to-end execution is not needed, and substitute evidence such as static checks, diff re-check, document consistency, schema/snapshot/type/build/target tests must be provided. If the explanation is missing or the evidence is insufficient, continue supplementing evidence; do not pass directly.
8. Read the context fully——Full solution doc (focus: Section 1 explicitly out of scope, 2.1 interface examples, 2.2 flow-level constraints, 2.3 mount points, Section 3 scenarios) + checklist + review report (findings / residual risk / Test And QA Focus) + QA report (if any: Feature type / Core evidence gate / Verification Matrix / Command Results / Scenario Results / residual-risk) + evidence pack / DoD results / Gate results + accept-inline verification matrix (if no QA report) + baseline pre-check / step evidence / actual deliverable index / knowledge write-back candidates in the implement completion report + domain impact candidates mentioned in Section 4 + requirements/CONTEXT.md + related ADRs + this code change (git log / diff)
9. Resume from breakpoint——{slug}-acceptance.md already exists and is partially filled → continue from the next incomplete section, skipping items already passed in checks; report "last time reached Section X, continuing from Section Y"

Fastforward design acceptance report mapping table：

Acceptance report section	Standard design reference	Fastforward design reference
1 Interface contract check	Section 2.1 interface examples	Section 1 change points
2 Behavior and decision check (including mount points)	Section 1 + Section 2.2 + Section 2.3	Section 0; on-site mount point inventory
3 Acceptance scenario check	Section 3 scenario list + reverse check	Section 2 acceptance criteria
4 Terminology consistency	Section 0 + Section 2.1 naming	Check code naming consistency
5 Domain impact inventory	Section 4	Usually none; write "no domain dimension changes"

---

Acceptance report template

Fill in section by sectionDon't skip sections. The report path is under the feature directory (for location see shared-conventions.md Section 0).

---
doc_type: feature-acceptance
feature: YYYY-MM-DD-slug
status: passed|blocked
accepted: YYYY-MM-DD
round: 1
---

# {功能名称} 验收报告

> 阶段：阶段 3（验收闭环）
> 验收日期：YYYY-MM-DD
> 关联方案 doc：{方案 doc 路径}

## 1. 接口契约核对

对照方案第 2.1 节名词层逐一核查：

**接口示例逐项核对**：
- [ ] 示例 A（{文件路径 + 函数名}）：示例输入→输出 → 代码实际行为：{一致 / 偏差说明}

**名词层"现状 → 变化"逐项核对**：
- [ ] 名词 X：声称的变化 → 代码改动：{一致 / 偏差}

**流程图核对**（第 2.2 节开头 mermaid 图）：
- [ ] 图中节点 / 调用关系在代码均有实际落点（grep 确认）

发现偏差**先修代码或回填方案 doc**。报告里写"已知偏差暂不处理"是反模式——下次按方案找代码会被绊倒。

## 2. 行为与决策核对

对照方案第 1 节 + 第 2.2 节：

**需求摘要逐项验证**：
- [ ] 行为 A：{描述 + 实测结果}

**明确不做逐项核对**（用第 3 节"反向核对项"）：
- [ ] 范围外事项 X **确实没做**（grep / review 确认）

**关键决策落地**：
- [ ] 决策 D1：{决策内容} → 代码体现：{描述}

**编排层"现状 → 变化"逐项核对**：
- [ ] 变化 V1：{在哪一步插入 / 哪条分支变更} → 代码实际落点

**流程级约束核对**（错误语义 / 幂等 / 并发 / 扩展点 / 可观测点）：
- [ ] 纪律 R1：{描述} → 代码遵守方式

**挂载点反向核对（可卸载性）**——对照第 2.3 节，必做两件事：
- [ ] 挂载点 M1：清单条目 → 代码实际落点：{一致 / 偏差}
- [ ] **反向核查**（grep）：本 feature 在代码里的所有引用是否都落在清单内？清单外的引用 → 漏记，补进第 2.3 节
- [ ] **拔除沙盘推演**：按清单逆向操作后是否还有残留？残留 → 写进"遗留"或补挂载点

Fastforward 方案没有挂载点清单 → 现场 grep 盘点本次改动命中的挂入位置作为卸载依据。

## 3. 验收场景核对

对照方案第 3 节关键场景清单，逐条可观察证据验证：

- [ ] **S1**：{场景"输入 / 触发 → 期望可观察结果"}
  - 证据来源：{类型系统 / 单测 / 集成 / 手工 / 肉眼}
  - 结果：{通过 / 未通过 + 原因 + 补救}

**功能性前端改动必须浏览器肉眼验证**（typecheck 通过不代表用户用起来对；非功能性前端改动用替代证据复核）：
- [ ] UI 区域 X：浏览器验证 OK / 截图链接

**review 报告重点复核**：
- [ ] `{slug}-review.md` 第 4 节 Test And QA Focus 已逐条覆盖
- [ ] `{slug}-review.md` 第 5 节 residual risk 已逐条处理 / 明确留作用户确认遗留

**QA 报告重点复核**：
- [ ] 验证证据来源：`{slug}-qa.md` / accept-inline verification
- [ ] QA 报告或 Inline Verification Matrix 已覆盖 design 关键场景和 review QA focus
- [ ] QA 报告或 Inline Verification Matrix 中的 feature 性质与核心证据说明合理：功能性核心路径有运行证据；非功能性 feature 有替代证据理由
- [ ] failed / blocked 项为 none
- [ ] residual-risk 已逐条处理 / 明确留作用户确认遗留，且没有承载核心验收缺口
- [ ] Evidence pack、DoD Results、Gate Results 已复核；blocking DoD 均有 pass evidence

## 4. 术语一致性

对照方案第 0 节 + 第 2.1 节命名 grep 代码：

- 术语 X：代码命中 N 处全部一致 ✓
- 防冲突：禁用词 grep 无命中 ✓

发现不一致 → 改代码，别在报告里写"已知差异"。

## 5. 领域影响盘点（提示而非代写）

**目标**：识别本次 feature 是否引入了应进 CONTEXT.md / adrs/ 的内容，**提示用户走 cs-domain**——不在 accept 里替它写。

对照方案第 4 节 + 实际实现，三类信号逐项盘点：

- **新名词** → `requirements/CONTEXT.md` 候选：新增 / 改名的实体、类型、对外契约；grep CONTEXT.md 看是否已有定义，没有就提示"走 cs-domain 加术语？"
- **结构性选择**（满足 ADR 3 判据：难回退 + 不显然 + 真权衡）→ `requirements/adrs/` 候选：新增模块 / 跨模块接口模式 / 新依赖选型 / 拒绝的备选
- **流程级约束** → `requirements/adrs/` 候选：稳定的错误语义 / 幂等约束 / 扩展点规约

逐项核对：
- [ ] 候选 X（{术语 / 结构选择 / 流程约束}）：建议 {cs-domain 写 CONTEXT / 写 ADR} → 已建议用户 ✓ / 不需要（理由：{具体}）

**不在 accept 里直接改 CONTEXT.md 或写 ADR**——这是 cs-domain 的事。accept 只盘点 + 建议。本节是登记表，不是动作。

## 6. requirement delta / clarification 回写

req 是能力愿景层，但 **accept 阶段不自由重写长期 requirement**（Global Route Governance，本技能 L3）。对照方案 frontmatter 的 `requirement`、第 1 节需求摘要、feature 目录下已有 `*-req-delta.md` 与 clarifications：

- 纯重构 / 无 requirement 影响 → 写"无 requirement 影响"，跳过。
- 新增了用户可感能力，或改了边界 / 用户故事 / pitch：**必须有 owner-approved req delta** 才机械应用（`draft`→`current` 或刷新 current，保留原始愿景 + 变更日志）；**没有 approved delta 就停下**写 `approval-report.md`，回 clarification / `cs-req` delta 流程，不在 accept 里直接落 current。
- `requirement` 指向 current 但本次未改用户视角 → 写"req-{slug} 未变"。

完整 7 分支判据与 Global Route Governance 全文见同包 `reference.md`（按 `SKILL.md` 所在目录解析）。这是受 delta 约束的实际写文件动作，不是把 accept 当成自由重写 requirements 的机会。

## 7. roadmap 回写

对照方案 frontmatter 的 `roadmap` / `roadmap_item`：

- [ ] 两字段都空（feature 未从 roadmap 起头）→ 跳过，写"非 roadmap 起头"
- [ ] 两字段都有值：
  - 打开 `.codestable/roadmap/{roadmap}/{roadmap}-items.yaml`
  - 找到 `slug: {roadmap_item}`，核对当前 `status: in-progress` + `feature: {目录名}`——不对停下来找原因
  - 改 `status: done`，用 `validate-yaml.py` 校验
  - 同步 `{roadmap}-roadmap.md` 主文档第 3 节子 feature 清单的对应条目状态
- [ ] 两字段不一致（只填了一个）→ 停下来补齐或澄清

衔接协议看 `shared-conventions.md` 第 2.5 节。和 req 同规则：实际写文件的动作。

## 8. attention.md 候选盘点

回看本次实现，结合 implement 完成汇报里的"知识回写候选"，盘点"每个 feature 都会撞一次"的环境 / 工具 / 工作流类信息。典型候选：编译命令、代理配置、本地起服务步骤、反复踩的环境坑、仓库内非显然的工作流约定。

**判据**：下一个 feature 的 AI 还会再踩一次的事才记。一次性踩坑、和具体业务耦合的细节归 learning / decide。

- [ ] 无候选：写"本 feature 未暴露需要补入 attention.md 的内容"
- [ ] 有候选：列出来，**不擅自写入**——本节只登记，落不落由用户在"退出后"环节定
  - 候选 1：{描述 + 建议放 attention.md}

同时分流其他知识出口：

- 稳定技术约束 / 目录归属 / 命名规约 / 可复用坑点 / 库 API 经验 / 调试路径 → 第 9 节遗留或退出后提示 `cs-keep`
- 用户操作指南或开发者指南变化 → 退出后提示 `cs-doc-tutorial`
- 公开 API / 组件 / 命令表面变化 → 退出后提示 `cs-doc-api`

## 9. 遗留

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

---

Check rhythm

Do it section by section. After each section is completedUpdate item by item {slug}-checklist.yaml 's checks: pass → passed, fail → failed(first fix the code / solution then change back to passed). Only after all checks are passed is the report considered complete.

Sections 1/2 are most likely to expose deviations, do them first. Section 2 mount point reverse checkmust actually grep + sandbox walkthrough, cannot be checked off from impression. Sections 5/6/7 are file-writing actions, not self-assessment.

Final audit rhythm

After the 9-section report is filled in and all checks are passed afteryou still cannot directly declare completion, run another round of final audit using the final workspace to reverse-check the original design: reread the original contract, aggregate command re-verification, scenario sampling re-check, deliverable / complete workspace / diff cleanliness / knowledge accumulation re-check, honest coverage marking (write re-verified / trust-prior-verify count). If a gap is found, first change the corresponding check back to failed, fix only the failed items, rerun the corresponding section and final audit; if the same gap still fails after three rounds, stop and hand back to the user, do not write "pass".

For the complete 8 steps, gap handling, and the "## 10. Final Audit" report template see the same package reference.md(resolved by the directory where SKILL.md is located). The acceptance report appends Section 10 Final Audit after Section 9.

---

Exit conditions

• All 9 sections of the acceptance report are filled in
• review report exists and status=passed, no unresolved blocking findings
• verification evidence source is clear: QA report passed, or acceptance sections 3 / 10 already have an accept-inline verification matrix
• verification evidence has no unresolved failed / blocked items
• no passing by writing unverified functional core paths, unrun real user/API/runtime paths, or unexecuted mandatory commands as residual-risk; the alternative evidence rationale for non-functional features has been reviewed
• sections 1/2 all checkboxes verified, no unhandled deviations (including mount point grep + removal sandbox walkthrough)
• section 3 scenario checkboxes all verified; functional frontend has been browser-verified, non-functional frontend has alternative evidence
• section 4 terminology consistency has no omissions
• section 5 domain impact inventory: every candidate has a clear conclusion (cs-domain suggested / not needed)
• section 6 req write-back has a conclusion: skipped / unchanged / backfilled / draft→current / updated
• section 7 roadmap write-back has a conclusion: skipped (not roadmap-initiated) / updated (items.yaml + main document synchronized, yaml passes validation)
• all checks in the checklist are passed
• final audit completed: aggregate commands rerun, full workspace review, deliverable persistence review, diff cleanliness review, knowledge capture exit triage, re-verified / trust-prior-verify recorded; no unhandled gaps
• user final review confirmation

---

after exiting

tell the user: "The acceptance report is ready, domain impact candidates have been inventoried, and the cs-feat workflow is complete. Subsequent BUGs go through the issue process."

according to shared-conventions.md section 3 closing recommended order, give a one-sentence prompt for each item (if the user says "no need", skip immediately):

1. reusable pitfalls / lessons / long-term constraints / technology choices → "Capture to compound? (cs-keep）"
   • special check: whether design section 2.5 has a "convention recommended for capture" paragraph. If so, read that rule verbatim to the user: "design 2.5 recommends capturing this convention: '{one-sentence rule}', it has worked, do you want to cs-keep archive it now?" — this is a stable pattern identified already at the design stage, and should be proactively raised more than a general "ask and see"
2. interface changes / user-visible behavior changes → "Need to update the guide? (cs-doc-tutorial）"
3. library public interfaces (components / functions / commands) changed → "Need to update the API reference? (cs-doc-api）"
4. section 8 has attention.md candidates → ask one by one "Add candidate X to attention.md?" If the user explicitly agrees → trigger cs-note to do section classification / deduplication / soft limit check (do not handwrite in accept, to avoid having a separate standard from cs-note);one at a time
5. stage / milestone wrap-up, preparing handoff, or this change affects README/docs,CLAUDE.md / AGENTS.md, agent memory → "Do a round of documentation and memory organization? (cs-docs-neat）"
6. finally ask whether to do a scoped-commit on the user's behalf

for closing commit rules see shared-conventions.md section 4. Commit scope: functional code + design doc + acceptance report + req doc / CONTEXT.md / ADR / roadmap items.yaml actually updated this time + main document.

---

common pitfalls

Common pitfalls (tests/QA passed ≠ acceptance scenarios satisfied; mount points must be grepped, not just checked against a list; domain inventory is a current action, not a suggestion; accept does not directly modify CONTEXT.md or write ADRs—that is cs-domain's job; accept only inventories + suggests; final audit gaps must be fixed first, not written off as "leftovers"; accept does not freely rewrite requirements, it must go through delta; do not declare completion or commit without the user's final review / consent, etc.) see the same package reference.md。