easysdd-requirements

easysdd/requirements/ is the project's "capability inventory" — each document describeswhat problem gives rise to a capability, how it is solved, and where its boundaries are, written in plain language so that non-technical readers can grasp it at a glance. Architecture documents cover "how it is built"; requirement documents cover "why this needs to exist." The benefit of recording the two separately is that when discussing requirements alone you are not distracted by implementation details, and when discussing architecture alone you are not led along by the product perspective.

The value of a requirement document lies inbeing able to grasp the key points at a glance— user stories come first, pain points and solutions each get a short paragraph, and boundaries are given as a list. The several problems AI most easily produces when writing requirement documents all undermine the property of "grasping the key points at a glance":

Writing in PRD format (a pile of fields) — readers have to read cell by cell to piece together the whole picture.
An overly explain-y tone — it reads like a lecture, not an introduction.
Flashy titles or metaphors — the title reads like ad copy, and readers have to read half a paragraph to know what the capability is.
Cramming implementation details into requirements — "call the YYY interface through the XXX service" is the job of an architecture doc.

The whole set of rules below exists precisely to keep these four situations from happening.

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

Applicable scenarios

A capability / user scenario lacks a requirement document and you want to add one
The capability has evolved (new user stories / outdated pain point statements / changed boundaries) and needs refreshing
During the feature-design stage you discover that the capability to be implemented this time has no corresponding requirement; stop first and add it before continuing

Not applicable:

The user wants to write "how this system is technically built" → switch to easysdd-architecture
The user wants to write the plan for a single feature → switch to easysdd-feature-design
The user wants to decide on a long-term rule / choice of technology → switch to easysdd-decisions
The user wants to write "how to use it" for external readers → switch to easysdd-guidedoc

Single-target rule

Only touch one document at a time, choose one of two:

new: draft a new requirement document (easysdd/requirements/{slug}.md）
update: refresh an existing requirement document according to new material / implementation changes

Why is writing multiple documents at once not allowed? The value of a requirement document lies ineach one being read— when AI drafts several at once, the user does not have the energy to carefully review each one, and in the end either they are all merged in roughly or all left unread.

Allow "features without a requirement"

For features such as purely internal refactoring / technical debt cleanup / toolchain overhaul, whichdo not add user-perceivable capabilities, there is no mandatory requirement to have a corresponding requirement. In feature-design, simply mark "no new capability this time" in the corresponding position; do not force-write a req just to make one.

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)
The scope covered this time (the whole document / certain sections)

A requirements doc describesone capability. When the user says "write all the requirements for this module", first ask clearly: how many independent capabilities does this module provide externally? One doc per independent capability; don't cram multiple capabilities into the same one.

Phase 2: Read the materials

Always required reading:

AGENTS.md
easysdd/requirements/ other requirements docs under it (to judge "does this one need to cross-reference them" and "is it duplicated with any of them")
Materials provided by the user (verbal descriptions, product ideas, user feedback, requirement descriptions scattered across existing feature proposals)

Read as the situation requires:

the architecture doc that may host this capability (easysdd/architecture/) — used for the implemented_by field
existing feature proposals related to this capability (to understand how this capability has evolved recently)
related compound deposits (explore / decision may have recorded background on this capability):
```
python easysdd/tools/search-yaml.py --dir easysdd/compound --query "{能力关键词}"
```

Additional required reading in update mode: the full text of the current version of the doc + the changes in the related implementation after that doc's last_reviewed (git log a rough scan of implemented_by the code modules corresponding to those architecture docs is enough).

Phase 3: Draft in one pass

Following the "Document structure" below, write out acomplete first draft, not half-finished pieces in batches. The four blocks — user stories / pain points / solution / boundaries — often have cross-block contradictions (the scenario described in the user stories doesn't match the path described in the solution), and you can only see that when they're put together.

Phase 4: Self-check list (run through it right after drafting)

Before the user reviews, go through the following set of checks yourself. Each one targets a mistake AI makes by default:

Does the tone sound like a human talking?— pick a passage and read it aloud; does it sound like you're introducing this thing to a friend? Or like you're lecturing / writing a PRD? If the latter, rewrite it.
Are the titles plain?— the title should directly say what this capability is; no metaphors, no fancy wording. "Explore and analyze first when fixing a bug" > "Let AI be your first reader".
Are the user stories specific enough?— each user story should let you imagine a concrete scenario. "As a user, I want the system to be easy to use" is empty talk; delete it.
Have implementation details been slipped in?— a requirements doc shouldn't contain things like "through interface X", "call service Y", "use algorithm Z". If it does, move them to the corresponding architecture doc.
Are the boundaries written?— requirements without boundaries will be misused. Give at least one "what it doesn't handle".
Can the pitch field be used as promotional copy?— the frontmatter's pitch should be de-technicalized, one sentence, understandable to a reader without context. If it can't, change it.
Update mode specifics: do all the newly added / changed paragraphs this time have corresponding source material or implementation basis? Purely "adding a sentence that sounds more complete" out of thin air is the beginning of drift.

Briefly report the self-check results to the user — if you found problems, say you found them and how you handled them (deleted / rewrote / added); don't treat it as an invisible "going through the motions" step.

Phase 5: User review

Paste the complete first draft to the user and prompt them to review. If the user gives feedback, revise, repeating until the user explicitly says "this doc is good". Only after the user gives the go-ahead do you enter Phase 6.

Phase 6: Write to disk + update index

new mode: write easysdd/requirements/{slug}.md，frontmatter status: current，last_reviewed fill in today's date
update mode: overwrite the existing file,last_reviewed update to today's date; if the structural changes are large, add an entry "YYYY-MM-DD: {one-sentence description}" to the 变更日志 section at the end of the document
index update: if under easysdd/requirements/ there is README.md or an index file, add a link line along the way. If not, don't force it—requirements is currently flat,ls is itself the index

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

Tone should be human, not PRD-speak—no field dumps, lecture-hall tone, or flashy headings; every paragraph must be understandable at a glance by a non-technical reader.
Do not write implementation details—the requirements document only covers "what / why / what problem it solves", not "how to build it". Any description involving implementation must be moved to architecture.
Do not make up user stories for the user—user stories must come from user material or traceable scenarios (existing features, user feedback, explore records). AI is not allowed to invent a "sounds reasonable" usage scenario out of thin air.
Single goal—only touch one document at a time.
Do not change code or the architecture doc—this skill only writes the requirements doc. If you find a problem with architecture, record it as an "observation item" and let the user decide whether to open another workflow to handle it.
Do not expand scope—do not extend to any issue outside the scope described by the user; just record it as an observation item.

Exit conditions

has locked a single mode (new / update) and a single target document
Phase 4 self-check checklist has been run item by item, and the handling results have been reported
The document frontmatter is complete,doc_type: requirement、pitch、status、last_reviewed are all filled in
The body has all four sections (user stories / why it is needed / how to solve it / boundaries)
Every user story can be imagined as a specific scenario; there is no filler like "as a user I hope the system is easy to use"
No implementation details have been stuffed into the requirements doc
pitch The fields read as if they could be used directly as promotional copy
update mode: if there are structural changes,变更日志 an entry has been added to the section
The user has explicitly passed review
No code / architecture doc / other spec was modified along the way
No out-of-scope extra document changes

Relationship with other workflows

Direction	Relationship
`easysdd-architecture` works with	requirement describes "why it should exist", architecture describes "how to build it"; in the architecture doc's frontmatter, use `implements: [req-slug]` to link back to the requirement it carries
`easysdd-feature-design` upstream	When a feature is about to add / modify a capability, first confirm that the corresponding requirement exists or trigger this skill to create it; a feature that is purely refactoring / technical debt does not force a req
`easysdd-feature-acceptance` downstream	If during acceptance it is found that a feature changed the boundary or user story of some capability → trigger this skill's `update` mode to refresh the corresponding req
`easysdd-onboarding` creator	During onboarding, create `easysdd/requirements/` Empty directory, to be filled in later by this skill

Common mistakes

Writing it as a pile of PRD fields: readers have to read cell by cell to piece together the full picture
Tone like lecturing: openings such as "This capability aims to provide..." should be thrown out immediately
Using metaphors in titles: "Let AI be your first reader when fixing bugs" < "Explore and analyze first when fixing bugs"
User stories too abstract: "As a user, I want the system to be easy to use"—delete it
Cramming in implementation details: "Implement Y by calling interface X" — that is the job of an architecture doc
No boundaries written: requirements will be misused and then disappoint
pitch Fields stuffed with technical jargon: cannot be extracted for use during promotion
Drafting multiple documents at once: users do not review deeply, and all are merged in roughly
Scope too large: one doc stuffed with multiple independent capabilities—split it
Adding sections out of thin air in update mode: the content will drift further and further from reality as it is written