cs-feat-accept

At this point, the code has been written, but the workflow is not yet complete. This phase involves four indispensable tasks:

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
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
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)
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.

Strong Dependency on Design Sections

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. Code is fully implemented

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. Design doc is complete

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 Section	Standard Design Reference	Fastforward Design Reference
1 Interface Contract Check	Section 2 of Design (Interface Contract)	Change points in Section 1 of Design (Design Solution)
2 Behavior and Decision Check	Section 1 of Design (Decisions and Constraints)	Section 0 of Design (Requirement Summary)
3 Test Constraint Check	Section 3 of Design (Test Design)	Section 2 of Design (Acceptance Criteria)
4 Terminology Consistency	Section 0 of Design (Terminology Conventions)	No terminology table; just check code naming consistency
5 Architecture Incorporation	Section 4 of Design (Architecture Relationship)	Usually no architecture changes; if indeed irrelevant, write "No architecture-level changes for this fastforward"

3. {slug}-checklist.yaml Status

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. Read the full context

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. Breakpoint Recovery

{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

{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

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

# {Feature Name} Acceptance Report

> Phase: Phase 3 (Acceptance Closed-loop)
> Acceptance Date: YYYY-MM-DD
> Associated Design Doc: {Design Doc Path}

## 1. Interface Contract Check

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. Behavior and Decision Check

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. Test Constraint Check

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. Terminology Consistency

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. Architecture Incorporation

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 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 Update

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. Legacy Items

- 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

Do section by section, do not skip:

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
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
Section 4 (Terminology) – Use Grep, write the hit count and locations into the report
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)"
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
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
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

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

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

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"):

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/
```
)"
Introduced long-term constraints / technical selections beyond a single feature → "Do you need to archive this decision? (Follow
```
cs-decide
```
)"
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
```
)"
Added / modified public library interfaces (components, functions, commands, etc.) → "Do you need to update the library API reference doc? (Follow
```
cs-libdoc
```
)"
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

"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

cs-feat-accept

NPX Install

Tags

SKILL.md Content (Chinese)

cs-feat-accept

Strong Dependency on Design Sections

Startup Checks

1. Code is fully implemented

2. Design doc is complete

3. {slug}-checklist.yaml Status

4. Read the full context

5. Breakpoint Recovery

Acceptance Report Template

Check Rhythm

Exit Conditions

Final Commit

After Exit

Common Pitfalls