SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillscs-req

cs-req

Office & productivity

View repository

Updated 10-15 20:30

About this skill

cs-req

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 external AI entry points (see .codestable/reference/execution-conventions.md）。

.codestable/requirements/ is the project's "capability list"—each one describeswhat problem a capability arose from, how it is solved, and where its boundaries lie, written so that non-technical readers can also understand it. Architecture documents cover "how it is built", while requirements documents cover "why it should exist".

req is the capability vision layer of the system—it describes "what users need and what capabilities the system provides to satisfy them". The three layers of temporal depth are distinguished by one status field:

  • draft: users have this need, but the system has not yet implemented it (future vision)
  • current: the system is satisfying it (current capability)
  • outdated: it was once satisfied, but has now been removed or is no longer maintained (trace of the past)

a draft req can exist independently of implementation—when a user says "I want capability X" but has not yet decided when to do it, you can first land a status: draft req to lock down the vision, providing a stable reference for later roadmap scheduling and design alignment.not doing roadmap planning does not mean there should not be a vision document。

the main path from draft → current is feature-acceptance: after capability implementation is complete and acceptance passes, acceptance triggers cs-req update to change status from draft to current, while refreshing the user stories / boundaries according to the actual implementation (preserving the original vision from being overwritten, and only adding a change log at the end).

the backfill path is retained: for capabilities already running but never documented with a req, use backfill to directly land status: current。

do not record "how to implement step by step"—that is the job of cs-roadmap . req only answers "what is wanted and why", not "which sprint to do it in or how many sub-features to split it into".

the value of a requirements document lies ingrasping the key points at a glance—user stories come first, pain points and solutions are each a short paragraph, and boundaries are in a list. Several problems AI easily causes that break this characteristic:

  • writing it in PRD format (a pile of fields)—readers have to read cell by cell to piece together the full picture
  • too explanatory in tone—it sounds like teaching a class rather than introducing something
  • fancy headings or metaphors—readers have to read half a paragraph before knowing what the capability is
  • stuffing in implementation details—"calls YYY interface through XXX service"

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

Applicable scenarios

  • triggered in the brainstorm stage: after discussion the vision is clear → draft draft the vision and land it in status: draft, so that later design and roadmap have a stable baseline for alignment
  • triggered in the feature-design stage: a new capability is designed in a solution for the first time → draft draft the vision (user stories / pain points / solution / boundaries) and land it in status: draft
  • triggered in section 6 of feature-acceptance: implementation of the capability corresponding to the draft req is complete → update upgrade to current(preserve the vision, append a change log); for an existing capability that has never had a req written → backfill directly land current; capabilities already in the current req changed their boundaries / user stories / pitch → update refresh
  • User-initiated inventory: capabilities already running have never had a req written (backfill）
  • User-initiated revision: the capability has evolved and needs refreshing (update）
  • User-initiated vision drafting: for future needs not yet scheduled, first land a draft req to pin down the positioning

Not applicable: making architecture decisions / adding terminology → cs-domain; writing a one-off feature plan → cs-feat-design; operational accumulation → cs-keep; writing external "how to use" → cs-doc-tutorial; breaking a large requirement into several rounds → cs-roadmap。

Single-target rule

Touch only one document at a time:

  • draft: draft a vision for a new capability not yet implemented (user stories / pain points / solution / boundaries),status: draft
  • backfill: fill in one for a capability that already exists but has never been documented,status: current
  • update: refresh one according to new material / implementation changes

Why not allow multiple? The value of a req lies inevery one being read— if you spit out several at once, the user has no energy to review them one by one, and in the end they either get merged in rough or sit unread.

Allow "features without a requirement"

Pure internal refactoring / tech debt cleanup / toolchain reworkdoes not add user-perceivable capabilityfeatures do not mandatorily need a req. feature-design can just mark "no new capability this time"; do not force-write one just to make up the numbers.

Workflow

Phase 1: Lock the target

Mode + target document + scope.

draft mode: the capability is not yet implemented; draft the vision from user material (verbal description / product ideas / user feedback). User stories and pain points must be genuine, and the boundaries must clearly state "what is out of scope" — the value of a vision lies precisely in drawing a clear line between "what to do" and "what not to do".

One req describesone capability. If the user says "write all the requirements for this module", first ask clearly: how many independent capabilities does the module provide externally? One per independent capability, do not cram them together.

Phase 2: Read the material

Common required reading：VISION.md(requirements hub index) + requirements/ other reqs under it (to judge whether cross-references are needed and whether there is duplication) + user material (verbal description / product ideas / user feedback / scattered requirement descriptions from existing features).

Read as the case requires: the architecture doc that may host this capability (used for implemented_by); related existing feature plans; compound accumulation (python .codestable/tools/search-yaml.py --dir .codestable/compound --query "{能力关键词}"）。

draft extra: take a glance at the roadmap — if the roadmap already mentions this capability, read it to understand the expected direction of breakdown, but the req itself is not bound to a roadmap entry. update extra: the full text of the current document + last_reviewed the changes in related implementation afterward (git log roughly scan the code module corresponding to implemented_by ).

Phase 3: Draft in one pass

Write according to "Document structure" belowa complete first draftwithout batching. The four blocks — user stories / pain points / solution / boundaries — often have cross-block contradictions (the scenario described by the user story does not match the path described by the solution), and these are only visible when placed together.

Phase 4: Self-check checklist

Run through it yourself before review. Each item targets a mistake AI makes by default:

  1. Is the tone human?——Does a passage read like you're introducing it to a friend? Or like you're lecturing / writing a PRD? If the latter, rewrite it.
  2. Are the titles plain——Just say directly what the capability is, no metaphors / fancy stuff. "When fixing bugs, explore and analyze first" > "Let AI be your first reader"
  3. Are the user stories specific enough——Each one has to let you picture a specific scenario. "As a user I hope the system is easy to use" is useless filler
  4. Has any implementation detail been stuffed in——There should be no "via the X interface", "using the Z algorithm". If there is, move it to architecture
  5. Are the boundaries written——Requirements without boundaries will be misused
  6. Can the pitch be used as promotional copy——De-technicalized, one sentence, a reader can understand it without context
  7. update specifics: Do all newly added / changed passages this time have source material or implementation basis? Adding descriptions that sound more complete out of thin air is the beginning of drift
  8. draft specifics: Is the vision written clearly——after reading "why it's needed", can someone unfamiliar with the project restate what pain point this capability solves?

Report the self-check results briefly——if you find problems, say how you'll handle them (delete / change / add), don't just go through the motions.

Phase 5: User review

Paste the complete first draft to the user. Revise until the user explicitly says "it's good".

Phase 6: Write to disk + index update

  • draft: write into requirements/{slug}.md，status: draft、last_reviewed the same day
  • backfill: write into requirements/{slug}.md，status: current、last_reviewed the same day
  • update: overwrite existing,last_reviewed the same day; if the structural change is large, 变更日志 add an entry at the end of the document; the status upgrade from draft → current is a structural change,mustadd a changelog
  • Index update: update requirements/VISION.md——list all reqs grouped by status, each with a one-sentence pitch and a status marker

Document structure

frontmatter

---
doc_type: requirement
slug: {英文连字符；和文件名一致}
pitch: {一句话去技术化说清楚这能力，可直接当宣传素材}
status: current | draft | outdated
last_reviewed: YYYY-MM-DD
implemented_by: []   # 承载的 architecture doc slug 列表，可空
tags: []
---

Body sections

# {标题 — 直接平铺说这能力是什么，不玩比喻}

## 用户故事

- 作为 {具体角色 / 处境}，我希望 {能做什么}，而不是 {现在怎么难受}
- ...（2-4 条，每条一行）

## 为什么需要

一段短的，讲这能力不存在时的痛点。非技术读者也能读懂。直接当宣传素材——痛点描述得越真切，对外讲这系统解决什么问题时就越有抓手。

## 怎么解决

一段短的，讲这能力大概怎么工作。**不写实现细节**——不提模块名 / 接口 / 算法。讲"用户体验上发生了什么"就够。

## 边界

- 它不管什么（哪些事情看起来相关但它不负责）
- 什么情况下别用它
- 用的前提（用户需要先做什么）

Changelog (only in update mode)

## 变更日志

- YYYY-MM-DD：{一句话描述}

Hard boundaries

  1. Tone is human speech, not PRD——Field dumps / lecturing tone / fancy titles are all unacceptable
  2. Don't write implementation details——Only talk about "what / why / what it solves"; anything involving implementation must be moved to architecture
  3. Don't make up user stories for the user——They must come from user material or traceable scenarios (existing feature / user feedback / explore); it is not allowed to fabricate "sounds reasonable" usage scenarios out of thin air
  4. Single goal——One at a time
  5. Don't change code, don't change the architecture doc——Only write req. If you find a problem with arch, record an "observation item"
  6. Don't go off on tangents——Record out-of-scope issues as observation items

Exit conditions

  • A single mode + single goal has been locked in
  • The Phase 4 self-check list has been run through item by item and reported
  • frontmatter is complete (doc_type: requirement / pitch / status / last_reviewed）
  • The body has all four sections complete (user stories / why it's needed / how to solve / boundaries)
  • Each user story lets you picture a specific scenario, with no "hope the system is easy to use" filler
  • No implementation details have been stuffed in
  • pitch It reads like it can be used directly as promotional copy, and the draft can also be used directly as promotional copy (the vision also needs to be sellable)
  • draft: status is draft, no implementation details fabricated, boundaries clearly drawn
  • update: structural changes present 变更日志(including draft → current status upgrade)
  • User review passed
  • Did not casually change code / architecture / other specs
  • No out-of-scope document changes

Relationship with other workflows

Direction Relationship
cs-domain works with req writes "why it should exist", cs-domain manages CONTEXT terminology / decides ADRs; ADR frontmatter can use relates_to: [requirements/{req-slug}] reverse link
cs-brainstorm can trigger After consultation, when the vision is clear, can trigger draft mode to draft the vision req
cs-feat-design can write design reads existing reqs to align user stories and boundaries; when a new capability is first designed, trigger draft mode to draft the vision req
cs-feat-accept Main path Acceptance uniformly handles req filing: completion of the capability implementation corresponding to a draft req triggers update(draft → current, retain the vision and append a change log); a capability that has never had a req written triggers backfill(directly file as current); a change to a capability that already has a current req triggers update refresh
cs-roadmap works with req records "what is wanted and why", roadmap records "how to implement it step by step". A roadmap entry can link to a req slug, but a req is not bound to a specific roadmap. A draft req does not put pressure on the roadmap—a vision can exist before scheduling
cs-onboard Creator onboard creates requirements/ empty directory + VISION.md empty skeleton

Common mistakes

  • Treating a draft req as a backfill write—the capability is not implemented yet but status: currentwas written, or solution details were fabricated pretending it already exists
  • When backfilling, not confirming whether the capability truly runs in the code—writing a "sounds plausible" req based on a single sentence from the user
  • Stuffing implementation details into a draft req—deciding how to implement it before it is even done; that should be decided in the design phase
  • Drawing the boundaries of a draft req too broadly—the value of a vision is in drawing the line; wanting everything means saying nothing
  • Writing it as a pile of PRD fields / a tone like lecturing / metaphorical titles / overly abstract user stories / stuffing in implementation details / not writing boundaries
  • pitch stuffed with technical jargon—cannot be extracted for use in promotion
  • Drafting multiple at once—the user does not review deeply
  • Scope too large, stuffing in multiple independent capabilities—split it
  • update adds sections out of thin air—the content drifts further from reality the more it is written