cs-feat-impl

cs-feat-impl

Required reading before starting

Before making any judgment or taking any action, first run CodeStable preflight: read .codestable/attention.md; if missing, first cs-onboard; do not substitute by reading an external AI entry point (see .codestable/reference/execution-conventions.md）。

By this point the user has already signed off on the plan; your job is to turn the plan into code. What tends to go wrong is not the coding itself, butwhat to do when you discover during implementation that the plan does not cover a situation—charging ahead turns the plan into a mere formality. The whole set of rules below exists to make "stop" the default action.

Execution principle: implementation is not "make all the changes in one go and then talk," but rather verifiable increments according to the approved checklist. Each step must first have a clear exit signal, and once done, immediately verify with evidence; on failure, diagnose and retry first, and if it still fails, write a narrow-scope fix note; only after consecutive failures hand it back to the user. Do not let an unverified intermediate state roll into the next step.

Advancement principle: during implementation, keep the task resumable, attributable, and auditable at all times. Confirm the baseline before starting; update the checklist and evidence each time a step completes; on failure, fix only the currently failing criterion; check cleanliness at every step; when interrupted by the user, stop at a step boundary; record knowledge learned that would affect subsequent features as a candidate first, and hand it to acceptance for final consolidation.

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

Execution gate (worktree + commit)

Before entering implementation, run the start gate, using the project runtime path .codestable/tools/...：

python3 .codestable/tools/codestable-worktree-gate.py --root . --json start --unit .codestable/features/YYYY-MM-DD-{slug}

If the gate does not pass, do not start changing code; when the user approves an override, first write in the unit directory worktree-override.md（reason / scope / approval）。

dogfood / temporary isolated repository exception: only when the user's task explicitly requires actually executing the workflow in a one-off isolated repo, and that repo is not the target main repository for delivery, is it allowed not to create a linked worktree; you must still write in the unit directory worktree-override.md, recording reason=dogfood-ephemeral-repo, the original user authorization text, the scope of impact, and the subsequent cleanup strategy. This exception must not be used for ordinary feature implementation.

After implementation is complete and before outputting the report, run the commit gate:

python3 .codestable/tools/codestable-worktree-gate.py --root . --json commit --unit .codestable/features/YYYY-MM-DD-{slug}

If the gate does not pass, handle the findings first, and do not treat "tests passed" as completion. For installation of the gate tool and the branch-guard hook description, see .codestable/reference/branch-guard-hooks.md。

Three postures when writing code

The specific rules are the concrete expression of these three postures; understanding the postures matters more than memorizing the rules.

1. By default, write the least amount of code

Write only what the current step explicitly requires. Do not casually add "might be needed later" configurable options, abstraction layers, parameter toggles, or defensive fallbacks. Criterion: if after writing a section you feel "do I still need to add X," first ask whether X is something the current user can perceive—if not, do not add it. If after finishing the whole thing you look and see that 200 lines could actually be explained clearly in 50 → rewrite. Extra code is not neutral; it is a maintenance burden for future maintainers.

2. Only touch what should be touched; do not casually "improve" neighbors

When changing a function, change only that function. Other functions in the same file may have ugly style or odd naming—unless they directly conflict with this change, do not touch them. Match the style of new code to the existing style in the current file. Mixed-in "incidental changes" dilute a feature PR into "a lump of miscellaneous changes," multiplying review cost several times over. Things worth changing should be recorded as follow-up issues in the "incidental discovery" format below.

Orphan handling: if your change makes some import / function become dead code → delete it.NotDead code caused by your change → keep it and record it as an incidental find.

3. Don't decide things design didn't specify

Halfway through writing, you find a corner the design didn't cover (boundary conditions, error paths, files outside the plan) — by default, stop and go back to design to discuss. The "patch branch" and "terminology guard" below are two typical landing points of this stance;Any moment of "design didn't say it explicitly so I picked one for it" triggers this。

Startup check

1. Is the plan file sufficient to support implementation

frontmatter：doc_type=feature-design / feature consistent / status=approved / summary non-empty / tags ≥ 2。

Standard design(sections 0/1/2/3/4):

Section 0 has content; section 1 contains "explicitly not doing" and the complexity tier
Section 2.1 noun layer uses the "current state → change" two-part format, each new/changed interface has at least one example + source location
Section 2.2 orchestration layer starts with a main flow diagram, "current state → change" is complete, flow-level constraints are recorded
Section 2.3 mount points use the criterion "if you delete it, does the feature disappear", and internal code changes were not mistakenly listed
Section 3 has a key scenario list + reverse check items (excluding test code / framework selection)

Fastforward design(sections 0/1/2/3):

Section 0 contains "explicitly not doing"; section 1 has change points (files + function/type names)
Each acceptance criterion in section 2 is verifiable; the advancement steps in section 3 have exit signals

If any item fails → return to cs-feat-design to fill it in. Reason: items the plan missed must be filled in on the spot during implementation, which amounts to bypassing the checkpoint.

Note: Section 3 "acceptance contract" of a standard design only says "what should hold after completion", not "specifically how to do it". The changed file list / function-level landing points / test code are left to implement to decide; don't send it back asking for additions just because design didn't write them.

2. Is {slug}-checklist.yaml present

File exists, thefeature field is consistent
steps is non-empty (already produced by design, paradigm dimension slicing, 4-8 steps);checks non-empty
Doesn't exist → return to cs-feat-design to generate

3. Read the context fully

Full plan doc (standard design focus: section 1, 2.1/2.2/2.3/2.4, 3)
{slug}-checklist.yaml, requirement sources (user description + brainstorm note),.codestable/attention.md
Source locations for section 2.1 interface examples / code files mentioned in fastforward section 1 change points — just read the relevant functions
If review-fix: read {slug}-review.md, and take only unresolved blocking findings as this round's targets
If qa-fix: read {slug}-qa.md, and take only failed / blocked QA items as this round's targets

4. Confirm with the user which step to start from

Usually step 1; when resuming from a previous interruption, continue from the next step after what's already done .

The steps given by design is paradigm dimension slicing (orchestration skeleton → computation nodes → persistence → tests),which file each step changes specifically is decided by you at execution time. If a step is actually 3 independent sub-actions, or you find a micro-refactor is its prerequisite (see reflection check), align with the user then append / split steps,don't do it secretly。

5. Baseline pre-check

Before touching the first line of code, read the "must-run verification commands / baseline risks" in the design. Run the commands most relevant to this feature with acceptable cost first (at least typecheck / targeted tests; for the frontend, first confirm the dev server / page entry can be opened).

All green: record in the work log "Baseline pre-check passed: {command list}"
Red lights present: first determine whether they are pre-existing issues or prerequisites that this feature must fix first
- Pre-existing red light and does not affect the current feature: record it as a baseline risk; subsequent verification only requires "no new failures / targeted checks pass", and the final report must state this clearly
- Pre-existing red light but affects the current feature: stop and confirm with the user whether to first add a safety net / fix the baseline, or adjust the design
- Cannot attribute it: do not continue making large changes; first narrow down the command or read the error to locate it

The purpose of this step is not to make the whole repository green, but to avoid misjudging "already broken before startup" as failure of this step, and to avoid continuing to pile up code on a broken baseline.

Connection to the micro-refactor in design section 2.5：

If the conclusion of 2.5 is "do micro-refactor (split files)" or "do micro-refactor (reorganize directories)", it is step 1 of the checklist—run it independently, and verify according to the item in section 2.5 "how to verify behavior is unchanged":
- Split files: compilation green + existing tests pass + zero diff in external interface signatures
- Reorganize directories: compilation green + existing tests pass + diff limited to file moves + import path updates (no function body changes at all）
do not merge into the next step—once mixed together, behavior changes and structural changes cannot be separated, and if problems occur you cannot roll back to a clean intermediate state
If the conclusion of 2.5 is "do not do it" but a splitting signal is triggered by a reflection check midway through writing → follow the "reflection check" path below (stop → align with the user → if it can be solved provably, add an independent step),do not secretly add it by bypassing user confirmation
If there is a "conventions suggested for retention" section at the end of 2.5: during the implement phasedo not proactively archive—only after the directory reorganization runs successfully and zero behavior change is confirmed, include a line in the report: "the conventions suggested for retention in design 2.5 are ready; wait for the acceptance phase to confirm whether to go through cs-keep", leaving the decision to acceptance / the user

Several core constraints during implementation

Strictly follow the steps in order

Follow the steps list order, do not merge, do not skip. Before starting each step, reread that step's action / exit_signal, confirm it is the only goal of this round; immediately verify the exit signal after completing each step, and set status to pending → done。

The most common violation is "conveniently doing the next step as well"—each step corresponds to an independently verifiable exit signal; doing two steps together means that when problems occur you do not know which step introduced them, and rollback cannot return to a clean intermediate state.

Immediately after completing each step, persist the status of the step corresponding to {slug}-checklist.yaml to disk. Do not wait until all steps are complete to update them all at once; the status file is the anchor for resuming from a breakpoint. When resuming after an interruption, read it first rather than relying on memory.

Every step must have an evidence block

After completing each step, leave minimal evidence in the work log / reporting materials:

Exit signal: extracted verbatim
Verification action: what commands were run / what pages were viewed / what diffs were checked / what interfaces were called
Result: pass / fail; for failures, write the actual error summary
Impact surface: the main functions, types, routes, configuration, or documentation added / modified in this step
Cleanliness: whether the code added in this step contains debug output, temporary TODO/FIXME, commented-out code, unused imports, or files outside the plan

Evidence is not required to be sent to the user at every step, but the final completion report must be traceable by step. Evidence for a UI step cannot just say typecheck; it must have browser / screenshot / visual verification; backend API steps should preferably be proven with tests or real requests; purely type-level constraints can be proven with typecheck.

Step Cleanliness Check

During each step's verification, additionally look at this step's diff:

Added debug output:console.log / console.error / print / fmt.Println / temporary logger
Added temporary TODO / FIXME / XXX
Commented-out old code or large blocks of dead code
Added import but unused
File changes not needed for this step

If hit, treat it as a failure: if it can be deleted on the spot, delete it and rerun verification; if it is genuinely part of the functionality (for example, newly added logging capability), the reason and scope must be explained in the design / report. Cleanliness is not an aesthetic issue; it is to prevent temporary construction traces from entering later stages.

Do not make changes outside the plan

If you find something worth refactoring (refer to .codestable/reference/shared-conventions.md Section 7 "Reflection checks while writing code"), as long asit is not within this feature's impact surfacerecord it as a follow-up issue:

> 顺手发现：{文件:行号} {问题简述}。不在本次范围，记录待后续 issue。

Code changed along the way is not in the plan, acceptance does not match; later people doing git blame also cannot tell whether it was for this feature or just done in passing.

Terminology guardianship

Standard design: every newly written type / function / variable name must be checked against Section 0 of the plan doc; new concepts not in the doc are not allowed. To introduce a new concept → stop first, modify Section 0, grep to prevent conflicts, and get user confirmation.

Fastforward design: there is no formal glossary, but when creating a new concept name, also grep the current code to prevent conflicts.

Cost: terminology conflicts mean two names for the same concept / two concepts for the same name—the latter makes search completely ineffective.

When the urge to add a "patch branch" appears, stop

While writing code, if if (特殊情况) { 特殊处理 } this kind of structure comes up,stop. This kind of branch basically has only one reason: the plan did not cover this situation. Continuing to write gives you "special logic added just to make the code run"—next time someone changes this area, they will not know why this branch exists. Go back to the plan and discuss: add it to the design / cut it / clearly mark it as a legacy issue.

Step failure recovery: diagnose → narrow fix → hand back

When a step's exit signal or related test fails, do not directly move to the next step, and do not hide the failure in the final report. Handle it in three stages:

First failure: failure diagnosis Clearly write the failed item, actual error, recently changed scope, and root cause hypothesis; retry only once around the current step. Do not expand scope before retrying.
Second failure: narrow-scope fix description If the retry still fails, write a temporary {slug}-step-N-fix.mdin the feature directory (or record the equivalent in the completion report):
- failed exit_signal / checks
- root cause judgment
- which files / behaviors are allowed to be changed
- Which verifications must be rerun after the fix Execute this narrow fix, and after it succeeds, return to the original step's verification; do not mark it done directly.
Third failure: hand back to the user If it still fails, stop and report the three attempts, evidence, current risks, and suggested next steps. Do not keep changing large swaths of code just to "complete the process".

This mechanism only handles failure of the current step; it is not a license to bypass design. If a design gap is found, still go back to cs-feat-design, not use a narrow-scope fix to justify making the call on the spot.

User interruption and resumption

If the user sends a new message midway through implementation:

The current step has not reached a safe point: first verify the smallest in-progress change / roll back to an explainable state, then respond
The current step has been verified: update the checklist status and evidence, then stop before the start of the next step
The user asks to change direction: do not continue executing the old checklist; first determine whether to change the design, split the step, or cancel the current feature

When resuming, use a fixed order: read design → read the checklist's current status → read the most recent implementation report / temporary step fix document → continue from the first pending step.

Code quality reflection check

In addition to the process constraints above, there is also a set of reflection checks for code quality—see .codestable/reference/shared-conventions.md Section 7.

Core:It is not "must split when over N lines", but "when encountering situation X, stop and ask yourself". Each one corresponds to a pitfall the AI will fall into by default (continuing to append to a large file, adding methods to a large class, patch branches, copy-paste, the 4th+ parameter, piling things into a catch-all util).

If the reflection check concludes "needs splitting / new file / renaming / extracting a shared layer" and it exceeds the scope of the existing steps → discuss and decide with the user; do not secretly finish the split and keep writing. The criteria are divided into two paths consistent with the boundaries in design 2.5 (to avoid impl creating its own set of standards):

Can be solved with "move only, do not change behavior"(split functions / split files / move definitions, compiler green throughout, zero diff in external signatures) → after aligning with the userappend as an independent stepinserted before the current step, run independent verification and exit before continuing
Exceeds the "move only, do not change behavior" boundary(requires changing function signatures / changing return value structure / changing call relationship semantics / module splitting or merging) → do not do it in this feature, record it in the "incidental discovery" format and prompt the user to later go through cs-refactor, and work around it in the current step with the minimal change; do not do it in the feature just because "I saw it anyway"—this dilutes the feature PR into a mixed change and also violates the boundary already drawn in design 2.5

Final round of local audit

After all steps are marked done , before the completion report, do a small final audit:

Reread {slug}-design.md Sections 1 / 2 / 3 and {slug}-checklist.yaml
Confirm item by item that all steps are done, and that checks have not yet been accepted but already have implementation evidence
Rerun the build / typecheck / lint / test or project-equivalent commands required for this feature; if there are frontend changes, run browser verification
Go through git diff, checking the newly added debug output, temporary TODO/FIXME, commented-out code, unused imports, and files outside the plan
Use the key scenarios in Section 3 to check in reverse: is there any item without evidence; if so, add tests or go back to implementation
List the actual deliverables: newly added / modified / deleted code entry points, configuration, schema, routes, documentation, roadmap status, to provide an index for the acceptance deliverable review
List knowledge candidates: project commands, environment pitfalls, stable conventions, library API pitfalls, user-confirmed preferences; do not write directly to knowledge, only hand them to acceptance section 8 for processing

If audit finds a problem, return to the corresponding step to handle it; do not leave the problem for acceptance to discover for the first time.

review-fix mode

When cs-code-review produces status: changes-requested and there are unresolved blocking findings, enter review-fix mode:

Only read and fix the blocking findings in the review report; do not take the opportunity to implement new requirements, refactor neighbors, or handle non-blocking suggestions.
Leave fix evidence for every REV number: changed files, verification commands, and why the blocker has been removed.
If fixing the blocker requires changing the design contract, expanding the feature scope, or touching a roadmap item boundary, stop and return to cs-feat-design / user confirmation.
After fixing, run the relevant verification and cleanliness checks, and output a review-fix report.
The next step must rerun cs-code-review; you cannot directly enter cs-feat-accept。

review-fix does not require adding ordinary steps to the checklist, unless the user explicitly asks to bring the fix actions into checklist tracking. By default, write the REV numbers and evidence in the report, and keep the review report as review input.

qa-fix mode

When cs-feat-qa produces status: failed or status: blocked and the failed items are attributable to this feature, enter qa-fix mode:

Only read and fix the failed / blocked items in the QA report; do not take the opportunity to handle new requirements, non-blocking suggestions, or residual risk already accepted by review.
Leave fix evidence for every QA number: changed files, verification commands, and why the failure has been removed.
If fixing the QA failure items requires changing the design contract, expanding the feature scope, or touching a roadmap item boundary, stop and return to cs-feat-design / user confirmation.
After fixing, run the relevant verification and cleanliness checks, and output a qa-fix report.
qa-fix changed the code diff, so the next step must rerun cs-code-review; after review passed, rerun cs-feat-qa. You cannot directly enter cs-feat-accept。

qa-fix does not require adding ordinary steps to the checklist, unless the user explicitly asks to bring the fix actions into checklist tracking. By default, write the QA numbers and evidence in the report, and keep the QA report as regression test input.

After writing, output a unified report

After all steps are complete, follow the "implementation completion report" template in references/reference.md to output and stop for user review. The template must list the real git status, changes categorized by step, out-of-plan touches, new concepts, step evidence, cleanliness, deliverables, knowledge candidates, the last round of local audit, and acceptance scenario self-checks.

How test cases are implemented

Each item in section 3 "Key Scenario List" of the standard design = one verifiable behavior constraint. Turn each item into observable evidence: unit test / integration test / manual operation / compile-time type guarantee. When a coding step is suitable for automated testing, a TDD vertical slice may be used within the step; this is cs-feat-impl 's embedded implementation strategy, not switching to an independent tdd skill. For specific testing strategy, see references/reference.md and references/tdd.md。

Exit conditions

For the complete checklist, see references/reference.md. The main file retains the hard gate summary:

The status of all steps is done, and each step has exit signal evidence.
The completion report has been output, and the user review has passed (or the review-fix / qa-fix report has been output, waiting to rerun the corresponding gate).
There are no unhandled "needs to be stopped" signals, out-of-plan changes, or cleanliness gaps.
A baseline pre-check was done before starting; a final round of local audit was done before completion.
Every key scenario in Section 3 has evidence / test coverage (fastforward compares against Section 2).

After exiting

Tell the user the next step: after normal implementation is complete, trigger cs-code-review; after review-fix, rerun cs-code-review; after qa-fix, rerun cs-code-review and cs-feat-qa. Do not casually proceed to the acceptance report; for the complete wording, see references/reference.md。

Common pitfalls

For the complete list, see references/reference.md. The most common red lines: reporting a half-finished product, making casual out-of-plan changes, not backfilling new concepts, forcing through a patch branch, skipping the review/QA gate, and having no evidence for key scenarios.