cs-feat-design

cs-feat-design

Required reading before starting

Before making any judgment or taking any action, first run the 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）。

The output of this stage is a design document {slug}-design.md, plus the action checklist extracted from it {slug}-checklist.yaml, and the pre-human-review {slug}-design-review.md. These things will later be consumed by implement / code review / QA / acceptance, so if something is wrong or missing here, downstream will be wrong too.

For shared paths and naming conventions, see .codestable/reference/shared-conventions.md. At this stage the feature directory has generally already been created by brainstorm; if not, create it in this step. Report language: the design / plan body must follow .codestable/attention.md and useChinese; if the draft was written in English, rewrite it into Chinese before writing it to disk. frontmatter / yaml fields are not translated.

This stage has three entry points:

Formal drafting: the user can already explain the requirements clearly (or has already filled in {slug}-intent.md), go directly to the "Process" section and carry out the full drafting.
Initialization mode: the user says "start a new requirement / create a draft / create a new feature", but wants to write a half-finished design themselves first instead of dictating it. Go to the next section "Initialization mode", set up the directory and an empty {slug}-intent.md , then end this round and wait for the user to finish filling it in before coming back.
Starting from a roadmap item: the user says "start working on the {sub-feature slug} in the roadmap" or "advance the next item of {roadmap}". Take the slug from roadmap items.yaml, do not make up a new one; before writing, read the roadmap main document and items.yaml to understand the context and dependency status; when writing to disk, the frontmatter must carry the roadmap / roadmap_item two fields, and at the same time write back to items.yaml to change the corresponding item's status to in-progress、feature filled with the feature directory name. See "Starting from a roadmap item" below for details.

Design principles: the design is not a prose explanation before implementation, but an executable contract for subsequent implementation and acceptance. It must translate "done well" into observable evidence, cut the steps into independently verifiable units, expose risks and dependencies up front, and perform a self-critique before handing it to the user to fix vague criteria, mixed steps, and weak dependencies.

Advancement principles: the design must write the "operation manual" needed by subsequent execution in place: how to confirm the current baseline, what evidence to look at after each step is complete, which commands must be rerun, which deliverables must actually be written to disk, and which contract to return to and fix when something fails. Otherwise implement can only make ad hoc judgments, review has no stable contract to audit against, QA does not know what evidence to run, and acceptance can only trust the implementation report.

Initialization mode: help the user create the directory and intent draft

Trigger: the user wants to write a half-finished design themselves ({slug}-intent.md) as input for the subsequent design, but does not want to manually create the directory.

Actions:

Quickly align with the user on two things—a one-sentence requirement summary + finalize the slug (lowercase letters, numbers, hyphens;user-auth、export-csv like this). Use the current date (for frontmatter, currentDate is fine). The feature directory name is YYYY-MM-DD-{slug}。
Create the .codestable/features/{YYYY-MM-DD}-{slug}/ directory。
Write an empty {slug}-intent.md as the draft skeleton, template see references/intent-template.md 's "feature intent draft template".
Tell the user "the skeleton is built; come back to me after filling it in, and I'll write the formal design based on the intent", thenthis round ends; do not continue advancing the design process。

Why stop here? The value of intent is to let the user think offline and put what's in their head onto paper. If the AI keeps asking, it degrades intent mode into brainstorm and loses its meaning.

Start from a roadmap entry

Trigger: the user says "start working on {sub-feature} in the roadmap" or points to an entry in items.yaml planned entry.

Read roadmap context—open {roadmap-slug}-roadmap.md and {roadmap-slug}-items.yaml：
- The target entry must status: planned + depends_on have all prerequisites done, otherwise stop and report
- Must read Section 3 "Module Breakdown" and Section 4 "Interface Contracts / Shared Protocols" of the main document—this is the hard constraint input for this feature. If the contract is unreasonable / missing → stop and suggest going back to cs-roadmap update to change it,do not secretly bypass it in the design
Take the slug from the roadmap, the feature directory YYYY-MM-DD-{roadmap 条目 slug}, do not create a new one
Follow the "process" section, add to the frontmatter roadmap / roadmap_item two fields
When candidates are written to disk, write back to items.yaml: for the corresponding entry status: in-progress + feature: YYYY-MM-DD-{slug}, use validate-yaml.py to validate; for the design, first keep status: draft, and only after passing cs-feat-design-review and user confirmation change approved

For the complete handoff protocol, see .codestable/reference/shared-conventions.md Section 2.5.

What the design should and should not write

The design only covers the orchestration side of "orchestration-computation separation":The current state and changes of this feature at the noun layer and the orchestration layer. Details of the computation layer (exactly how to write it, which functions to change, how to set up tests) belong to implement.

Write three kinds of things, using the two-part "current state → change" form for both the noun layer and the orchestration layer:

Noun layer—value objects / entities / data structures / external contracts / type definitions
Orchestration layer—main flow / workflow / key orchestration functions / control-flow topology (linear / branching / parallel DAG / state machine). Start with a main flow diagram to build the mental model
Flow-level constraints—error semantics, idempotency, concurrency / ordering, extension point locations, observability points. The mount point list also belongs to this category

When this feature introduces or changes a module interface, seam, adapter, or cross-dependency testing strategy, follow references/codebase-design.md to do an embedded deep-module check; this is not switching to a standalone codebase-design skill。

Plus afixed structural health check step(Section 2.5): assess whether the files about to be changed are too fat / have mixed responsibilities, and whether the directories that new files will go into are flattened; decide whether to do a "move only, do not change behavior" micro-refactor (split files / reorganize directories) before implementation. Even if the conclusion is "do not do it", write it explicitly in the design—otherwise the AI will by default keep stuffing code into fat files and adding files to crowded directories. This section goes into the overall review together with the whole draft and does not go through confirmation separately.

Criteria: Rewriting it a different way changes the noun layer or orchestration layer → a design matter; rewriting it a different way that is merely "the code is less pretty / functions are split differently / tests use a different framework" → an implement matter.

Do not write the changed-file list, function-level landing points, test code, or library selection details—at the design stage the relevant code hasn't been fully read yet, and predictions will most likely be revised later. After implement receives the design, it scans the current state before deciding.

The plan document is for giving people an overview, not for careful reading

When readers open {slug}-design.md they want to grasp the key points within 5 minutes, not read it word by word. Specific practices:

If any section exceeds 1 screen, cut it or split it—if it doesn't fit on one screen, readers lose their bearings
Lock down terminology first—before writing, grep the code / architecture / historical features to prevent conflicts; the cost of straightening things out afterward is far higher than prevention
Examples take priority over definitions—for interface behavior, give an "input→output" example first, and add formal types later if it's complex
The same piece of information appears only once, in the most natural place—repetition is more annoying than missing one item
By default, put new logic in new files(write this in the change plan)—the larger the file, the harder it is to distinguish responsibilities

Three disciplines when drafting

1. Don't make decisions for the user

When encountering "corners the user didn't clarify," by default stop and ask; don't pick one yourself and fill it in. Specifically:

Declare assumptions: write judgments that are not the user's original words as "Assumption: ...", so the user can rebut precisely
Give options without choosing yourself: lay out 2-3 reasonable approaches and then state your preference
If you don't understand, stop: forcing a guess and writing on will fail to match the acceptance points at the acceptance stage

2. Write both goals and constraints as verifiable

Don't write weak standards like "make it run" or "the user experience is smooth"—rewrite them as "return B when input A"
"Explicitly not doing" should be specific enough to be checked in reverse by grep or tests; don't write empty phrases like "don't over-design"

3. Every feature must be unloadable

Answer: "If you want to pull it out, what places need to be pulled?" If you can't answer, it means the boundaries weren't thought through clearly, and once the feature ships it becomes an immovable fait accompli.

The result goes into the mount point checklist (Section 2.3).Criterion: delete this item—does the feature disappear from the user's/system's perspective? Yes → list it, no → don't list it. For detailed ✅/❌ examples and how to write them, see reference.md. This checklist also incidentally helps you discover whether you've accidentally instrumented too many places—more real mount points mean more scattered coupling, which is a signal.

Process: what to do when

1. Startup check

Prerequisite gate: the requirements input contains at least the four items user goal / core behavior / success criteria / explicitly not doing (source: intent / brainstorm / conversation). If missing, fill them in; if the user themselves can't clarify, fall back to brainstorm.

4 mandatory items：

Continuation check——Glob {slug}-design.md / {slug}-intent.md / {slug}-brainstorm.md：
- intent / brainstorm: read them in as input; don't re-ask the parts already made clear
- design status=draft each section is basically complete → if a checklist exists, jump to "5. Independent design review gate" in this process; otherwise generate the checklist first
- some design sections are missing → fill in the missing sections, and report "last time it was written up to X; after filling in, I'll give you the whole thing for review"
- design status=approved → Don't overwrite by default; ask the user whether to keep editing or start a new slug
Scan .codestable/ for global inputs——Glob .codestable/ Discover available directories and document types, and use them by category:
- requirements/CONTEXT.md → Read the domain glossary and name things using project terminology; don't invent names yourself
- requirements/adrs/ → ADRs related to cross-module or process-level constraints are a must-read; for ADRs that match and conflict with the plan, mustrespond directly to "why still do it this way" or adjust the plan
- requirements/{slug}.md → If there's a corresponding req: frontmatter requirement fill in the slug and read the two sections "User Stories / Boundaries"; when a new capability appears for the first time → trigger cs-req draft draft a vision req, frontmatter requirement fill in the new slug; leave blank for pure refactoring / technical debt
- compound/ → grep -r "关键词" .codestable/compound/ Search historical accumulation; if it hits relevant pitfalls / style constraints, fold them into the plan
- features/ → Search historical designs for similar features to reference
- For the remaining directories, judge by content type yourself
Read the existing code related to the requirements—which files to read is determined by the requirement clues
Identify the verification baseline—From attention / README / package scripts / CI / historical acceptance, find the build / typecheck / lint / test / e2e / browser verification entry points this feature should use; if the commands may currently already be red, write them into Section 1 "Baseline Risks"; before implement starts, do a lightweight pre-check first to avoid counting pre-existing red lights as failures of this feature

Trigger 3 items by signal(skip if no signal):

Terminology grep to prevent conflicts—When a new concept name has not been seen in code / architecture / historical features, grep it once; if there's a conflict, rename it or clearly distinguish it in Section 0
Complexity tier alignment—When the requirements contain deviation signals such as "external SDK / high concurrency / one-off tool", open .codestable/reference/code-dimensions.md list the deviation points; if there's no signal, write "use the default tier"
grep for "similar modules with different names"—When you intuitively feel "someone may have already done this but named it differently", grep synonyms

For detailed rules see .codestable/reference/shared-conventions.md Section 5.

2. Figure out where this feature should go

Before writing the noun layer / orchestration layer, first answer:Where does what we're adding this time belong in the project's overall structure?

Should an existing module handle it? → Extend within that module; don't start a new one
Does it span multiple modules? → Extract a common layer vs. let one party lead and the others depend on it
Is it unlike any existing module? → Create a new independent module/subsystem; think through in advance what it exposes externally and how it interacts with others
Is there possibly already a module doing something similar but named differently? → grep a few synonyms

Cost: put it in the wrong module and it becomes a "catch-all basket"; create a parallel implementation and several versions coexist.

Write the conclusion into Section 1 "Decisions and Constraints". When new modules or cross-module interfaces are involved, prompt the user to go through cs-domain to start an ADR recording this structural decision.

The default way AI messes up isadding to the handiest file without thinking。

3. Write the noun layer and orchestration layer in a "current state → change" two-part format

Following the reference.md template, write the four subsections of Section 2 (2.1 noun layer / 2.2 orchestration layer / 2.3 mount points / 2.4 rollout strategy). Key reminders:

"Current state" must point to code locations; don't assume—readers rely on it to judge whether the "change" is reasonable
When touching module interface / seam / adapter, add references/codebase-design.md the Interface design check
One mermaid diagram at the start of the orchestration layer to build the mental model
Mount points judged by "if you delete it, does the feature disappear"; 3-5 is the normal range
Advancement strategy sliced by paradigm dimension (orchestration skeleton → compute nodes → persistence → tests), not down to file:line
Section 2.5 "Structural health and micro-refactoring" is a fixed step—evaluate per reference.md writing requirementsTwo kinds of objects: files to change (file level) + target directories for new files (directory level).Before evaluating, first check compound's existing conventions(keywords around "directory organization / file placement / naming conventions"); if matched, just follow them. Conclusion is one of three choices:
1. Don't do it—files healthy / directories not crowded / small change size / micro-refactoring benefit doesn't outweigh risk; write "No micro-refactoring this time, reason: ..."
2. Do micro-refactoring (split files)—files are bloated or responsibilities are mixed but can be solved with provable refactor (split functions / split files / move definitions, compiler green throughout)
3. Do micro-refactoring (reorganize directories)—target directory is flat and can be solved through pure file moves + import path updates (compiler green throughout)
When choosing 2 / 3, give a concrete plan for "what to move → where to move it → how to verify behavior is unchanged", put it into the checklist asstep 1 with independent verification on exit, then start the feature body
When reorganizing directories, ask one more question: is it a stable pattern or a one-off cleanup—stable pattern (e.g. "custom business components all go in components/custom/", and future features should follow it too) then at the end of 2.5 add a "suggested conventions to consolidate" section, prompting the user to go through cs-keep archiving after implement passes; one-off cleanup (it's just that this directory happens to be crowded) then only move without archiving.design stage does not archive directly—the plan hasn't actually been run yet; leave a hook to decide after implement
design only does safe micro-refactoring, with strict boundaries: "only move, don't change behavior"—file level relies on IDE rename / move + compiler validation, directory level relies on pure file moves + import path updates + compiler validation. Once it involves changing function signatures / changing return value structures / changing call relationship semantics / module splitting or merging, thenbeyond design scope: write it into "out-of-scope observations" at the end of section 2.5, prompting the user "suggest handling later via cs-refactor ",does not block this feature, not a prerequisite dependency. Whether to actually do it and when is decided by the user outside the feature
Section 2.5 is reviewed together with the whole draft, not confirmed separately—package it with the feature plan for the user to review in one pass, avoiding splitting into two rounds that drags out the pace

4. Fill in the remaining sections and generate the review candidate

Fill in the remaining sections (sections 0 / 3 / 4) per the reference.md template. Draft frontmatter status: draft。

After the full draft is formed, first confirm that the body language matches .codestable/attention.md(default Chinese; English drafts should be rewritten first), then write the draft design to disk, and extract the candidate from {slug}-design.md and extract the candidate from {slug}-checklist.yaml. The checklist's steps/checks should initially both remain pending, and be validated with validate-yaml.py . Do not wait for user confirmation before generating the checklist, because before human review the cs-feat-design-review needs to review whether both the design and the checklist are aligned.

Section 3 "Acceptance Contract" guidance: write each item as "input / trigger → expected observable result", covering normal + boundary + error, and add Acceptance Coverage Matrix and DoD Contract; for the full template, see reference.md.

Add a section on execution risks and evidence plans(write it into Section 1 or Section 2.4, placed according to the document's natural position):

Top 3 risks: the three points most likely to be implemented incorrectly, hardest to roll back, and most easily missed in acceptance; for each point write the corresponding mitigation (a certain step, a certain acceptance scenario, a certain prior command)
Non-obvious dependencies: external services, data migration, existing module order, user decision items; explain which step is blocked
Evidence types: what each acceptance scenario will ultimately be proven by (types / unit tests / integration / manual / browser screenshots / API responses / diff review)
Key assumptions: judgments that are not the user's exact words but that the solution depends on being true, so the user can change them during review
Mandatory verification commands: which commands must be run before this feature is complete; if the command baseline may already be red, state clearly: "run the pre-check first; when it is red, distinguish pre-existing issues from those introduced this time"
Deliverables list: the categories of user-visible or system-visible artifacts that should ultimately be added / modified / deleted (code entry points, config keys, schema, routes, documentation consolidation, roadmap status); acceptance should be cross-checked against repository facts
Cleanliness rules: debug output, temporary TODO/FIXME, commented-out code, and useless imports that this feature must not add; if a certain kind of debug output is the feature itself, the exception and scope must be explicitly stated in the design

Principles for writing steps：

The number of steps is determined by the natural slicing of the work, not by merging unrelated content just to make 4-8; if it truly exceeds 8, first check whether it should go back to the roadmap and be split into sub-features
Each step delivers one coherent thing and can be independently verified; when "and / as well as / at the same time" appears in the name, recheck whether it should be split
Each step exit_signal must be yes/no and provable by a command, test, screenshot, API response, page observation, type check, or diff review
Each step should indicate the suggested verification action (command / manual / browser / diff review) and the main deliverable type, to make it easy for implement to create the step evidence block
UI features must ultimately cover visible states and polish: empty state, loading, error, disabled / unauthorized, long text / small screen, focus / keyboard / contrast; if not applicable, state the reason
When security / permissions / input handling / data migration are involved, the last functional step or a separate step must cover hardening: validation, privilege escalation, rollback, compatibility, regression surface

Do a self-critique once before handing it to the user, and fix the issues in the document first:

Falsifiability: Are Sections 3 and each item in the checklist yes/no? Are there words like "normal / complete / friendly / stable" that cannot be verified?
Step atomicity: Is there a step that stuffs in two things that can be independently accepted? Is there a step that only makes sense after the next step is completed?
Weakest dependency: Which step, if it goes wrong, will pollute the most subsequent content? Does it need to be verified in advance, split into an independent step, or have acceptance scenarios added?
Evidence completeness: Does every key scenario have an evidence type? Does the frontend require browser screenshots / visual verification?
Baseline executability: Are the required commands clear? If the commands may currently already be red, is there a pre-check and attribution explanation?
Deliverable verifiability: Can acceptance see every promised artifact from git diff / filesystem / configuration / document status?
Cleanliness coverage: Is it explicitly forbidden to have temporary debug output, TODOs, dead imports, commented-out code, and are necessary exceptions explained?
Interface depth: Do newly added / changed interfaces give callers enough leverage? Are the seam and adapter really needed?

5. Independent design review gate

Run cs-feat-design-review：

passed: only then can design + checklist + design-review report be handed to the user for overall review.
changes-requested: fix design/checklist according to the finding, re-validate the yaml and rerun cs-feat-design-review。
blocked: fill in the inputs, wait for an independent Task agent reviewer, or have the user explicitly downgrade to local-only and rerun.

6. Overall user review

Send an overall review prompt (the prompt is in Section 5 of reference.md), along with the Top 3 risks, key assumptions, self-critique conclusion, and {slug}-design-review.md summary. If the user gives feedback, change it; if the changes affect the noun layer, orchestration layer, acceptance contract, steps/checks, roadmap contract, or risk strategy, the checklist must be updated in sync and return to Phase 5 to rerun design review. After the user explicitly gives the go-ahead, change status from draft to approved。

7. Confirm checklist

Confirm {slug}-checklist.yaml is in sync with the final approved design. For the full format, extraction rules, and typical rhythm, see Section 3 of reference.md.

After writing to disk python .codestable/tools/validate-yaml.py --file {path} --yaml-only validation.

8. Exit

Check against the exit conditions below and guide the user into Phase 2.

Exit conditions

The overall user review passes, and:

frontmatter is complete (doc_type / feature / status=approved / summary / tags), the requirement field is aligned
the design body has been written to disk according to .codestable/attention.md 's report language (Chinese by default; frontmatter / yaml fields remain in machine-readable format)
Section 1 includes "what not to do" and complexity-tier deviations (or explicitly follows the default)
Sections 2.1 / 2.2 use the two-part "current state -> change" format; interfaces have examples + source locations; the orchestration layer starts with a main flow diagram
when module interface / seam / adapter are touched, the depth / locality / seam / dependency strategy inspection conclusions have been recorded
Section 2.3 mount points are tightened according to the criterion "if you delete it, does the feature disappear" (generally 3-5 items)
Section 2.4 rollout strategy is sliced by paradigm dimension, and each step has an exit signal
Section 2.5 structural health assessment covers file-level + directory-level; the compound convention has been checked before assessment; the conclusion is stated explicitly (do nothing / split files / reorganize directories); when "micro-refactor" is chosen, it is step 1 of the checklist and has an independent exit signal; when "reorganize directories" is chosen and it is a stable pattern, it includes a "convention recommended for codification" section; structural issues beyond "move only, do not change behavior" are listed in "out-of-scope observations" and only flagged without blocking
Section 3 key scenarios cover normal + boundary + error; includes "explicitly not doing" reverse-check items; each item has an evidence type, Acceptance Coverage Matrix, and DoD Contract
Top 3 risks / non-obvious dependencies / key assumptions have been written into the design or review summary
Each checklist step can be independently verified, and exit_signal is yes/no; UI / security / migration-type features have covered polish / harden or explicitly state not applicable
Self-critique for falsifiability / step atomicity / weakest dependency / evidence completeness has been performed and issues corrected
Must-run verification commands / baseline risks / pre-check requirements are clearly written
The deliverables list can be verified by acceptance from repository facts
Cleanliness rules are clearly written: handling criteria for debug output, temporary TODO/FIXME, commented-out code, and unused imports are explicit
{slug}-design-review.md Passed cs-feat-design-review, with no unresolved blocking finding
{slug}-checklist.yaml Persisted and passed validate-yaml.py validation
At the start of the roadmap, items.yaml has been written back (status: in-progress + feature filled in)

Common pitfalls

Starting to write without reading the relevant architecture / grepping terminology—the plan does not match the existing code, and after terminology conflicts, git blame takes ten times as long
Describing interface behavior in prose without concrete examples—readers cannot build a model
In the noun layer / orchestration layer, writing only "changes" without "current state"—readers cannot judge whether the changes are reasonable
Writing the mount point list as a list of modified files—internal changes belong to implement, while mount points should list only registry entries for which "if you delete it, the feature disappears"
Writing test code / framework / mock / function-level insertion points in the design—these belong to implement's discretion
Writing only signatures for interfaces without invariants / ordering / error mode / seam rationale—implement and tests will each fill in semantics on their own
Forcing a diagram—when there are ≤ 2 modules and calls are linear, a diagram instead blurs the focus
Reviewing with only half the document first—users cannot see global consistency
Skipping cs-feat-design-review and having the user decide directly—users can only see the surface of the plan, not the independent review conclusions for the checklist, contract, and acceptance strategy
Secretly expanding scope in the requirements summary—it will not match during acceptance
Writing acceptance scenarios as "good experience / complete state / correct logic"—acceptance cannot determine them and can only rely on feeling
A checklist step can only be verified after the next step is completed—this indicates the slice is not independent, and failures during execution cannot be localized