cs-req

codestable/requirements/

is the project's "capability inventory" — each document describes the problem that led to a capability, how it solves the problem, and its boundaries, written in plain language so non-technical readers can quickly understand it. Architecture documents focus on "how to build it", while requirement documents focus on "why this capability is needed". The advantage of separating the two is that discussions about requirements are not distracted by implementation details, and discussions about architecture are not constrained by product perspectives.

Requirements are status records, not planning records. Only describe "this capability currently exists and has these boundaries". By default, they are only refreshed along with code during feature-acceptance (if the feature implementation changes the boundaries / user stories, write back to the req), and are only actively updated via this skill's update mode when necessary. Do not record "planned tasks" or "future additions" — those belong to the planning layer of

cs-roadmap

. When the user says "I want capability X" but X hasn't been built yet, do not create a new req here — either the capability is being built and the target state needs to be written first to guide implementation (go through roadmap decomposition + feature-acceptance write-back to req later), or directly use

cs-roadmap

The value of requirement documents lies in being able to grasp key points at a glance — user stories are at the front, pain points and solutions are each a short paragraph, and boundaries are listed. Several common mistakes AI makes when writing requirement documents will destroy this "grasp key points at a glance" feature:

Written in PRD format (field stacking) — readers have to read each field to piece together the full picture.
Overly explanatory tone — like giving a lecture, not introducing something.
Fancy titles or metaphors — titles are like advertising slogans, readers need to read half a paragraph to understand what the capability is.
Including implementation details in requirements — "Call YYY interface via XXX service", which belongs to architecture docs.

The entire set of rules below is designed to prevent these four situations.

See
codestable/reference/shared-conventions.md
for shared paths and naming conventions. See
codestable/reference/requirement-example.md
for a sample document — read it before drafting to align the tone.

Applicable Scenarios

There is a capability / user scenario missing a requirement document and you want to fill it in
The capability has evolved (new user stories added / outdated pain point descriptions / boundary changes) and needs to be refreshed
During the feature-design phase, it is found that there is no corresponding requirement for the capability to be implemented this time — stop to fill it in before proceeding

Not applicable:

The user wants to write "how the system is built technically" → redirect to
```
cs-arch
```
The user wants to write a one-time feature solution → redirect to
```
cs-feat-design
```
The user wants to finalize a long-term specification / selection → redirect to
```
cs-decide
```
The user wants to write "how to use" for external readers → redirect to
```
cs-guide
```
The user proposes a large requirement to be split into multiple phases ("I want an X system") → redirect to
```
cs-roadmap
```
— that's the planning layer, do not stuff "pending capabilities" into req

Single-Target Rule

Only modify one document at a time, choose one of the two:

new: Draft a new requirement document (
```
codestable/requirements/{slug}.md
```
)
update: Refresh an existing requirement document based on new materials / implementation changes

Why is writing multiple documents at once not allowed? The value of requirement documents lies in each being reviewed — if AI drafts multiple documents at once, the user doesn't have the energy to review each carefully, and in the end, either all are roughly merged or all are left unread.

Allow "Features Without Requirements"

For features that do not add user-perceivable capabilities such as pure internal refactoring / technical debt cleanup / toolchain transformation, corresponding requirements are not mandatory. Just mark "No new capabilities added this time" in the corresponding position in feature-design, do not force-write a req just to fill a slot.

Workflow

Phase 1: Lock the Target

Confirm three things:

Mode (
```
new
```
/
```
update
```
)
Target document (new: new slug + one-sentence capability description; update: existing document path)
Scope covered this time (full document / specific sections)

One requirement doc describes one capability. When the user says "write all requirements for this module", first clarify: how many independent capabilities does this module provide externally? Each independent capability gets its own doc, do not stuff multiple capabilities into one doc.

Phase 2: Read Materials

Mandatory reading for all cases:

```
AGENTS.md
```
Other requirement documents under
```
codestable/requirements/
```
(to judge "whether this doc needs to reference others" / "whether there is duplication with any doc")
Materials provided by the user (oral descriptions, product ideas, user feedback, scattered requirement descriptions in existing feature solutions)

Read as needed:

Architecture doc that may carry this capability (
```
codestable/architecture/
```
) — used for the
```
implemented_by
```
field
Existing feature solutions related to this capability (to understand how this capability has evolved recently)

Related compound records (explore / decision may have recorded background of this capability):

bash

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

Additional mandatory reading for update mode: Full text of the current version of the document + changes to related implementations after the document's

last_reviewed

date (a quick scan of

git log

for code modules corresponding to architecture docs in

implemented_by

is sufficient).

Phase 3: One-Time Drafting

Write a complete first draft according to the "Document Structure" below, do not spit out semi-finished products in batches. There are often cross-section contradictions between user stories / pain points / solutions / boundaries (the scenario described in user stories does not match the path described in solutions), which can only be seen when they are put together.

Phase 4: Self-Check List (Run Immediately After Drafting)

Before user review, go through the following checks yourself. Each item targets a mistake AI tends to make by default:

Is the tone plain and conversational? — Read a paragraph aloud, does it sound like introducing something to a friend? Or like giving a lecture / writing a PRD? If it's the latter, rewrite it.
Is the title straightforward? — The title directly states what the capability is, no metaphors, no fancy language. "Explore and analyze before fixing bugs" > "Let AI be your first reader when fixing bugs".
Are user stories specific enough? — Each user story should allow imagining a specific scenario. Empty statements like "As a user, I want the system to be easy to use" are nonsense, delete them.
Have implementation details been included? — Requirement documents should not contain content like "via X interface", "call Y service", "use Z algorithm". Move such content to the corresponding architecture doc.
Are boundaries written? — Requirements without boundaries will be misused. At least include one "what it does not handle".
Can the pitch field be used as promotional copy? — The
```
pitch
```
in frontmatter should be non-technical, one sentence, and understandable to readers without context. Rewrite if not.
Update mode specific: Do all newly added / modified paragraphs have corresponding materials or implementation basis? Adding a "sounds more complete description" out of thin air is the start of drift.

Report the self-check results briefly to the user — if problems are found, state what was found and how it was handled (deleted / rewritten / supplemented), do not treat it as an invisible "formality" step.

Phase 5: User Review

Post the complete first draft to the user and prompt review. Revise according to user feedback until the user explicitly says "this doc is okay". Only proceed to Phase 6 after the user approves.

Phase 6: Finalize + Update Index

new mode: Write to
```
codestable/requirements/{slug}.md
```
, set frontmatter
```
status: current
```
, fill
```
last_reviewed
```
with the current date
update mode: Overwrite the existing file, update
```
last_reviewed
```
to the current date; if there are major structural changes, add a line "YYYY-MM-DD: {one-sentence description}" in the "Change Log" section at the end of the document
Update Index: If there is a
```
README.md
```
or index file under
```
codestable/requirements/
```
, add a link. If not, it's not mandatory — requirements are currently flat,
```
ls
```
itself is the index

Document Structure

Frontmatter

yaml

---
doc_type: requirement
slug: {English description, hyphen-separated; consistent with filename}
pitch: {One non-technical sentence explaining what this capability is, can be directly used as promotional material}
status: current | draft | outdated
last_reviewed: YYYY-MM-DD
implemented_by: []   # List of architecture doc slugs that carry this capability, can be empty
tags: []
---

Body Sections

markdown

# {Title — directly state what the capability is, no metaphors}

## User Stories

- As {specific role / situation}, I want {to be able to do something}, instead of {the current pain point}.
- ...(2-4 items, one per line)

## Why It's Needed

A short paragraph describing the pain points when this capability does not exist. It should be understandable to non-technical readers. This content is directly promotional material — the more vividly pain points are described, the more compelling it is when explaining what problems the system solves externally.

## How It Solves the Problem

A short paragraph describing roughly how this capability works. **Do not write implementation details** — no module names, interfaces, or algorithms mentioned. Just describe "what happens in the user experience".

## Boundaries

- What it does not handle (things that seem related but are not its responsibility)
- When not to use it
- Prerequisites (what the user needs to do first)

Change Log (Only for Update Mode)

markdown

## Change Log

- YYYY-MM-DD: {One-sentence description}

Hard Boundaries

Tone is plain conversational, not PRD — field stacking, lecture-style tone, fancy titles are not allowed; every paragraph must be understandable to non-technical readers at a glance.
No implementation details — Requirement documents only cover "what it is / why it's needed / what it solves", not "how to build it". All implementation-related descriptions must be moved to architecture docs.
Do not invent user stories for users — User stories must come from user materials or traceable scenarios (existing features, user feedback, explore records). AI is not allowed to create a "plausible" usage scenario out of thin air.
Single-target — Only modify one document at a time.
Do not modify code or architecture docs — This skill only writes requirement docs. If architecture issues are found, record them as "observation items" and let the user decide whether to start another workflow to handle them.
Do not diverge — Do not expand on issues outside the user's described scope, just record them as observation items.

Exit Criteria

Single mode (new / update) and single target document have been locked
Phase 4 self-check list has been completed item by item, and processing results have been reported
Document frontmatter is complete, with
```
doc_type: requirement
```
,
```
pitch
```
,
```
status
```
,
```
last_reviewed
```
all filled in
Four body sections are complete (User Stories / Why It's Needed / How It Solves the Problem / Boundaries)
Each user story allows imagining a specific scenario, no empty statements like "As a user, I want the system to be easy to use"
No implementation details are included in the requirement doc
The
```
pitch
```
field can be directly used as promotional copy
Update mode: If there are structural changes, a line has been added to the "Change Log" section
User has explicitly approved the review
No code / architecture doc / other spec has been modified by accident
No extra document changes outside the scope

Relationship with Other Workflows

Direction	Relationship
Collaboration with `cs-arch`	Requirements describe "why it's needed", architecture describes "how to build it"; use `implements: [req-slug]` in the frontmatter of architecture docs to link back to the requirements it carries
Upstream of `cs-feat-design`	When a feature needs to add / modify a capability, first confirm that the corresponding requirement exists or trigger this skill to create a new one; requirements are not mandatory for pure refactoring / technical debt features
Downstream of `cs-feat-accept`	During acceptance, if it is found that the feature has changed the boundaries or user stories of a capability → trigger this skill's `update` mode to refresh the corresponding req (the main path where status records are synchronized with code)
Collaboration with `cs-roadmap`	Reqs record "what this capability currently is", roadmap records "how to further develop it / build it from scratch". If a missing req is found during roadmap decomposition, let the user trigger this skill first; roadmap does not modify reqs
Creator of `cs-onboard`	The empty `codestable/requirements/` directory is created during onboarding, and then filled in by this skill

Common Mistakes

Including "planned tasks": Reqs are status records, unbuilt capabilities belong to roadmap, do not create new reqs here
Written as PRD field stacking: Readers have to read each field to piece together the full picture
Lecture-style tone: Immediately discard openings like "This capability is intended to provide..."
Using metaphors in titles: "Let AI be your first reader when fixing bugs" < "Explore and analyze before fixing bugs"
Too abstract user stories: "As a user, I want the system to be easy to use" — delete it
Including implementation details: "Implement Y by calling X interface" — this belongs to architecture docs
Not writing boundaries: Requirements will be misused leading to disappointment
Technical jargon in the
```
pitch
```
field: Cannot be extracted for promotional use
Drafting multiple documents at once: User review is not in-depth, all are roughly merged
Too broad scope: Multiple independent capabilities stuffed into one doc — split it
Adding paragraphs out of thin air in update mode: Content will drift further from reality

cs-req

NPX Install

Tags

SKILL.md Content (Chinese)

cs-req

Applicable Scenarios

Single-Target Rule

Allow "Features Without Requirements"

Workflow

Phase 1: Lock the Target

Phase 2: Read Materials

Phase 3: One-Time Drafting

Phase 4: Self-Check List (Run Immediately After Drafting)

Phase 5: User Review

Phase 6: Finalize + Update Index

Document Structure

Frontmatter

Body Sections

Change Log (Only for Update Mode)

Hard Boundaries

Exit Criteria

Relationship with Other Workflows

Common Mistakes