{slug}-design.md

{slug}-checklist.yaml

See

codestable/reference/shared-conventions.md

for shared paths and naming conventions. Generally, the feature directory has already been created by brainstorm phase; if not, create it in this step.

• Formal drafting: The user can clearly explain the requirements (or has already filled out

  {slug}-intent.md

  ), directly proceed to the "Workflow" section for complete drafting.
• Initialization mode: The user says "Start a new requirement / Create a draft / Add a new feature", but wants to write a semi-finished design themselves instead of dictating. Proceed to the next section "Initialization mode", create the directory and empty

  {slug}-intent.md

  , then end this round. Wait for the user to fill it out before returning.
• Start from roadmap item: The user says "Start working on {sub-feature slug} in the roadmap" or "Move forward with the next item in {roadmap}". The slug is taken from roadmap items.yaml, do not create a new one; before drafting, read the roadmap main document and items.yaml to understand the context and dependency status; when finalizing, add

  roadmap

  /

  roadmap_item

  two fields to the frontmatter, and update items.yaml to change the corresponding item's

  status

  to

  in-progress

  and fill

  feature

  with the feature directory name. See "Start from roadmap item" below for details.

{slug}-intent.md

1. Quickly align two things with the user — one-sentence requirement summary + finalize the slug (lowercase letters, numbers, hyphens; e.g.,

   user-auth

   ,

   export-csv

   ). Use the current date (use

   currentDate

   in frontmatter). The feature directory is named

   YYYY-MM-DD-{slug}

   .
2. Create the directory

   codestable/features/{YYYY-MM-DD}-{slug}/

   .
3. Write an empty

   {slug}-intent.md

   as a draft skeleton, with the following content:
   markdown

   ---
   doc_type: feature-intent
   feature: {YYYY-MM-DD}-{slug}
   status: draft
   summary: {One-sentence requirement, filled by AI based on alignment with user}
   ---
   
   # {slug} intent
   
   ## Background / Why do this
   
   (One sentence is enough)
   
   ## Rough implementation plan
   
   (Approximately 100 words describing the idea, including key steps / data flow)
   
   ## Related data structures / types
   
   (Paste related types, interface signatures, or point to code locations)
   
   ## Known scope exclusions / pending items
   
   (Optional: Clear boundaries or areas you haven't figured out yet)

4. Inform the user "The skeleton has been created. Come back to me after filling it out, and I'll write the formal design based on the intent", then end this round and do not proceed with the design workflow.

planned

codestable/roadmap/{roadmap-slug}/{roadmap-slug}-items.yaml

1. Read roadmap context — Open

   {roadmap-slug}-roadmap.md

   and

   {roadmap-slug}-items.yaml

   :
   • The target item's

     status

     must be

     planned

     — if it's

     in-progress

     , the design is already underway (continue the existing work); if it's

     done

     /

     dropped

     , stop and ask the user.
   • All prerequisite items in the target item's

     depends_on

     must be

     done

     — if any are

     planned

     /

     in-progress

     , the order is wrong. Stop and tell the user "Prerequisite {X} is not completed yet. It is recommended to finish it first, or confirm whether to adjust the roadmap order".
   • Read the "Notes" of this item in the main document and the overall "Scheduling ideas" to understand its position in the large requirement.
2. Take the slug from the roadmap — The feature directory is named

   YYYY-MM-DD-{slug of the roadmap item}

   , using the current date. Do not create a new slug, otherwise items.yaml and the feature will not match.
3. Create the feature directory and proceed to the "Workflow" section as usual.
4. Add two additional fields to the design frontmatter:
   yaml

   roadmap: {roadmap-slug}
   roadmap_item: {sub-feature slug}

5. When finalizing the design with

   status: approved

   , update items.yaml:
   • Find the item with

     slug: {roadmap_item}

     .
   • Change

     status: planned

     →

     in-progress

     .
   • Change

     feature: null

     →

     feature: YYYY-MM-DD-{slug}

     (feature directory name).
   • Validate with

     python codestable/tools/validate-yaml.py --file {path} --yaml-only

     .
6. Report: Inform the user that the roadmap has been updated, and the next step is the implement phase.

codestable/reference/shared-conventions.md

1. Nouns — New/changed entities, data structures, external contracts, type definitions. This is the shared language for implement and acceptance phases; omitting them will lead to misalignment.
2. Verb skeleton — Key orchestration, main workflow, progress steps, critical branches. Not pseudocode, but "what order this thing happens in, which steps it goes through".
3. Cross-layer disciplines — Constraints that seem like implementation details but can only be found through manual review if decided incorrectly: error semantics (rollback or retry on failure, what to return externally), idempotency, concurrency/order, extension point locations, observability points. See the third item below "Every feature must be uninstallable" for the specific implementation of this category at the feature level.

{slug}-design.md

1. Cut or split any section that exceeds one screen. If it can't fit on one screen, readers will lose their sense of orientation.
2. Lock down terms first. Run a grep for all new terms before drafting, covering code, architecture central directory, and design documents of all features. The cost of term conflicts is that others will look in the wrong place when checking code — the cost of prevention is far lower than the cost of sorting it out afterwards.
3. Examples take precedence over definitions. First use specific examples for interface behavior (input→output for APIs, Props→rendering/Events examples for components), then supplement with formal types if complex. Readers can build a model faster by seeing specific input and output than by reading an abstract description.
4. Progress by "feature visibility", not by code file order. First build the minimal closed loop (an end-to-end runnable path), then add details. This way, each step can be independently verified, and if a deviation is found along the way, only one step is lost.
5. New logic is placed in new files by default. New cohesive logic units are placed in independent files by default, instead of appending to existing files. Each item in the change plan is marked as "Create new file" or "Append to existing file (reason)". The reason is that larger files make it harder to distinguish responsibilities, and adding things to old files will make future developers read irrelevant changes when checking git blame.
6. The same information appears only once in the most natural location. Repetitive statements will make readers repeatedly confirm "Are these two the same thing?", which is more annoying than missing one.
7. Workflow first, template second. Complete the workflow below first, then fill in the content according to the template. Don't switch workflows while writing.

• State assumptions: Every judgment that is not directly stated by the user (input boundaries, error handling, edge behaviors) is written as "Assumption: ...", allowing the user to refute it precisely.
• Provide options instead of choosing yourself: If there are 2-3 reasonable approaches for a point, first list all candidates and then explain your preference, allowing the user to switch during review.
• Mention simpler alternatives: When the user's direction seems to achieve the same goal in a lighter way, explicitly say "There is a simpler approach: ..., should we rule it out first?". Don't stay silent just because the user has already stated the direction.
• Stop if you don't understand: If you are not sure you understand the requirement correctly, directly say "I'm not sure about this section", don't guess and continue writing.

• Don't use weak standards like "Make it work". Phrases like "Complete X function" / "Handle errors properly" / "Smooth user experience" essentially push the verification responsibility downstream. Rewrite them as "Return B when input is A" / "Display prompt Y when error X occurs".
• Every progress step has an exit signal. Just writing "Implement XX" is not enough; write "After completion, it can pass {specific test / operation steps}".
• "Explicitly not doing" must also be verifiable. "Not doing XX" must be specific enough to be checked reversely via grep or tests, not empty phrases like "Avoid over-design".

1. Continuation check — Glob

   codestable/features/{feature}/{slug}-design.md

   /

   {slug}-intent.md

   /

   {slug}-brainstorm.md

   :
   • If

     {slug}-intent.md

     exists: Treat it as the user's design input, do not repeat questions about already clarified parts, only follow up on uncovered areas.
   • If

     {slug}-brainstorm.md

     exists: Treat it as conversation input.
   • If the design file does not exist, or only has an empty template / frontmatter → Treat as new creation.
   • If design

     status=draft

     and each section is basically complete → Last time it was written but not reviewed, jump to "5. Overall review" in this workflow.
   • If some sections of the design are missing → Only supplement the missing sections, report "Last time we wrote up to Section X, we'll complete the rest and send you a unified review".
   • If design

     status=approved

     → Do not overwrite silently, ask the user whether to continue modifying or create a new slug.
2. Read architecture — Architecture main entry

   codestable/architecture/DESIGN.md

   + index + subsystem architecture docs related to the requirement. Focus on existing nouns (can they be reused / will there be conflicts) and cross-layer disciplines (what this feature must comply with). Writing without reading will most likely result in a design that is disconnected from reality.
3. Align requirement — Glob + grep in

   codestable/requirements/

   :
   • If a corresponding req exists: Record the slug in the

     requirement

     field of the design frontmatter; read the "User story" and "Boundaries" sections of the req before drafting, the design must not conflict.
   • If no corresponding req exists, but this feature adds/changes user-perceivable capabilities: Stop, prompt the user to trigger

     cs-req

     to draft or update the req.
   • For pure internal refactoring / technical debt / toolchain: Leave the

     requirement

     field in frontmatter empty, write in Section 1 "This feature does not add new capabilities, no corresponding requirement".
4. Read existing code related to the requirement — Specific files to read are determined by requirement clues. This is the prerequisite for the design to connect with existing code.

• Grep terms to prevent conflicts
  • Trigger: The key concept name to be introduced by this feature does not seem to exist in code / architecture / historical features.
  • Action: Grep covers code +

    codestable/architecture/

    + design documents of all features. If there is a conflict, change the name, or explicitly state in Section 0 "In this document, X refers to Y, which is not the same as X' in the code".
• Align complexity tiers
  • Trigger: Signals in the requirement that may deviate from the default tier — "External SDK" (readability rises from team to public), "High concurrency / low latency" (performance rises from reasonable to budgeted), "Pure exploration script / one-time tool" (robustness drops from L2 to L1).
  • Action: Open

    codestable/reference/code-dimensions.md

    , match the default combination according to the scenario, list the deviation points and reasons for user confirmation. After confirmation, write into the "Complexity tiers" subsection of Section 1, only record dimensions that deviate from the default.
  • No signal: Write one sentence in Section 1 "This feature follows the default tier for {scenario}, no deviations", no need to open the tier table.
• Grep for "similar modules with different names"
  • Trigger: Intuition that this feature "may have been done before but with a different name" — common in general tools, abstract capabilities, cross-module functions.
  • Action: Grep several synonyms to find candidate modules, confirm whether to extend the existing implementation instead of creating a new one.
• Archive retrieval
  • Trigger: Keywords clearly look like something that has been documented before (a decision, a pitfall, an exploration conclusion, a historical feature).
  • Action: First run

    python codestable/tools/search-yaml.py --dir codestable/compound --query "{keyword}"

    , then filter and read carefully by

    doc_type=decision/trick/learning/explore

    ; do the same for historical features —

    python codestable/tools/search-yaml.py --dir codestable/features --filter doc_type=feature-design --query "{keyword}"

    .
  • If hit, prioritize reuse, record the reference source in the design document.

codestable/reference/shared-conventions.md

• Is this something that an existing module should be responsible for? If yes, extend that module, don't create a new one outside.
• Does this span multiple modules — should we extract a common layer and place it in the middle, or let one party lead and others depend on it?
• Does this not fit well with any existing module? Then we may need to create a new independent module / subsystem — we need to figure out in advance where to place the new module, what to expose externally, and how to interact with others.
• Is there already a module doing similar things but with a different name that you didn't notice? Grep the project, don't reinvent the wheel just because of different naming.

DESIGN.md

• How long is this file now? How many responsibilities does it take on? Is the new content an extension of existing responsibilities, or the N+1th thing?
• How many methods does this class have? Is the new method a natural extension of the same responsibility, or does it push this class towards "can do everything"?
• For frontend-related content, also check if the component tree hierarchy is too deep, and if the state ownership is clear (local state / props passing / global store).

reference.md

{slug}-design.md

{slug}-checklist.yaml

codestable/reference/shared-conventions.md

steps

checks

{slug}-design.md

{slug}-checklist.yaml

reference.md

• steps

  : Extract step by step from the "Progress order" subsection of Section 3 "Implementation hints", one step per entry.

• checks

  : Extract comprehensively from these places —
  • Each item in Section 1 "Explicit scope exclusions" → Scope guard check items.
  • Each item in Section 1 "Mount point checklist" → Uninstallability check items (

    source: mount point

    , the acceptance phase uses this to verify reversely "Can it be completely removed according to the checklist").
  • Key interface contracts in Section 2 → Interface consistency check items.
  • Each test constraint in the "Test design" subsection of Section 3 "Implementation hints" → Test verification check items.

validate-yaml.py --file {path to slug-checklist.yaml} --yaml-only

{slug}-design.md

{slug}-checklist.yaml

reference.md

• YAML frontmatter examples
• Top-level section anchor requirements
• Complete format and status semantics of

  {slug}-checklist.yaml

• What each section 0-4 should include

reference.md

• Term grep for conflict prevention has been done and results recorded
• Complexity tiers have been aligned: Deviated dimensions have been recorded in the "Complexity tiers" subsection of Section 1, or it has been explicitly confirmed that all follow the default
• Requirements have been aligned: Either the

  requirement

  field in frontmatter is filled with the corresponding slug, or the design explicitly states "This feature does not add new capabilities, no corresponding requirement"
• YAML frontmatter exists, and

  doc_type

  /

  feature

  /

  status

  /

  summary

  /

  tags

  are all filled
• The requirement summary includes "what not to do", and there is no secret scope expansion later
• The mount point checklist is complete: Each item is specific to a file or configuration key, with sufficient granularity for the acceptance phase to verify uninstallability reversely
• Key decisions and rejected solutions have been recorded
• Each key interface has specific examples (API: input→output; component: Props→rendering/Events), covering normal paths and main error paths
• Examples are marked with source locations (file path + function/component name) via comments
• Progress steps are 4-8 steps, each can be independently verified
• Test design is organized by feature points, each feature point has test constraints / verification methods / key use case skeleton
• High-risk implementation constraints have been recorded
• After user confirmation, the

  status

  in frontmatter has been changed to

  approved

• {slug}-checklist.yaml

  has been extracted from

  {slug}-design.md

  and validated with

  validate-yaml.py

• The number of steps entries in

  {slug}-checklist.yaml

  matches the "Progress order" subsection of Section 3 "Implementation hints"
• If this feature starts from a roadmap item: Frontmatter includes

  roadmap

  /

  roadmap_item

  fields; the corresponding item in

  codestable/roadmap/{roadmap}/{roadmap}-items.yaml

  has been updated to

  status: in-progress

  ,

  feature

  filled with the feature directory name, and the yaml has been validated with

  validate-yaml.py

codestable/features/{feature}/

codestable/reference/shared-conventions.md

• Starting to write without reading relevant architecture documents — the resulting design will most likely not match existing code
• Not doing term conflict prevention checks — it will take ten times longer to find the reason via git blame after conflicts occur
• Describing interface behavior with prose without providing specific examples — readers cannot build a model and cannot judge during review
• Writing the contract layer as a full-field encyclopedia — do not copy existing and unchanged interfaces repeatedly
• Forcing to draw diagrams — if there are ≤2 modules and the calls are linear, drawing diagrams will blur the focus instead
• Splitting progress steps too finely (>8 steps) — so fine that each step has no independent value
• Only providing half the document for user review first — the user cannot see global consistency
• Secretly expanding the scope in the requirement summary or change plan — will not match during later acceptance