easysdd-requirements

easysdd/requirements/

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

The value of requirement documents lies in being able to capture key points at a glance — user stories are placed at the front, pain points and solutions are each a short paragraph, and boundaries are listed as bullet points. Several common problems with AI-written requirement documents will undermine this "grasp key points at a glance" feature:

Written in PRD format (stacked fields) — readers have to read through each field piece by piece to get the full picture.
Tone is overly explanatory — like giving a lecture, not introducing something.
Fancy titles or metaphors are used — titles are like advertising slogans, and readers have to read half a paragraph to understand what the capability is.
Implementation details are stuffed into requirements — "Call YYY interface via XXX service", which belongs in architecture docs.

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

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

Applicable Scenarios

A capability / user scenario lacks a requirement document and needs to be filled in
A 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 and fill it in before proceeding

Not applicable:

The user wants to write "how to technically build this system" → redirect to
```
easysdd-architecture
```
The user wants to write a one-time feature solution → redirect to
```
easysdd-feature-design
```
The user wants to finalize a long-term specification / selection → redirect to
```
easysdd-decisions
```
The user wants to write "how to use" for external readers → redirect to
```
easysdd-guidedoc
```

Single-Target Rule

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

new: Draft a new requirement document (
```
easysdd/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 the AI drafts multiple documents at once, the user won't have the energy to review each one carefully, and in the end, either all will be roughly merged or all will be 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, it is not mandatory to have corresponding requirements. Just mark "No new capabilities added this time" in the corresponding position in feature-design, and don't force-write a requirement 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 (entire document / specific sections)

A requirement doc describes one capability. When the user says "Write all the requirements for this module", first clarify: how many independent capabilities does this module provide externally? Each independent capability gets its own doc; don't stuff multiple capabilities into one document.

Phase 2: Read Materials

Mandatory reading for all:

```
AGENTS.md
```
Other requirement documents under
```
easysdd/requirements/
```
(to determine "whether this document needs to reference them" / "whether there is overlap with any of them")
Materials provided by the user (oral descriptions, product ideas, user feedback, scattered requirement descriptions in existing feature solutions)

Read as needed:

Architecture docs that may carry this capability (
```
easysdd/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 (background of this capability may be recorded in explore / decision):
bash
```
python easysdd/tools/search-yaml.py --dir easysdd/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 the architecture docs in

implemented_by

is sufficient).

Phase 3: One-Time Drafting

Write a complete first draft according to the "Document Structure" below; don't spit out semi-finished products in batches. There are often cross-section contradictions between the four sections of user stories / pain points / solutions / boundaries (the scenario described in user stories doesn't match the path described in solutions), which can only be spotted 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 that AI tends to make by default:

Is the tone in plain language? — Read a paragraph aloud; does it sound like introducing something to a friend? Or like giving a lecture / writing a PRD? Rewrite if it's the latter.
Is the title straightforward? — The title directly states what the capability is; no metaphors, no fancy wording. "Explore and analyze first when fixing bugs" > "Let AI be your first reader when fixing bugs".
Are user stories specific enough? — Each user story should allow you to imagine a specific scenario. Empty phrases like "As a user, I want the system to be easy to use" are nonsense; delete them.
Have implementation details been stuffed in? — Requirement documents should not contain phrases like "Via X interface", "Call Y service", "Use Z algorithm". Move such content to the corresponding architecture doc.
Have boundaries been written? — Requirements without boundaries will be misused. At least include one "What it doesn't handle".
Can the pitch field be used as promotional copy? — The
```
pitch
```
in the frontmatter should be non-technical, one sentence, and understandable to readers without context. Rewrite if it can't be done.
Special check for update mode: Do all newly added / modified paragraphs have corresponding materials or implementation basis? Adding a "sounding 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); don't treat it as a "routine" invisible step.

Phase 5: User Review

Post the complete first draft to the user and prompt for review. Revise according to the user's feedback until the user clearly states "This doc is okay". Only proceed to Phase 6 after the user approves.

Phase 6: Finalize + Update Index

new mode: Write to
```
easysdd/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
```
easysdd/requirements/
```
, add a link. If not, it's not mandatory — requirements are currently flat, and
```
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 clearly stating 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 what}, instead of {how I'm struggling now}.
- ... (2-4 items, one per line)

## Why It's Needed

A short paragraph explaining the pain points when this capability doesn't exist. Written in a way that non-technical readers can understand. This content is directly promotional material — the more vividly pain points are described, the more compelling it will be when explaining what problems the system solves externally.

## How It Solves the Problem

A short paragraph explaining 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 doesn't 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 language, not PRD — stacked fields, 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 descriptions involving implementation must be moved to architecture docs.
Do not make up user stories for the user — User stories must come from user materials or traceable scenarios (existing features, user feedback, explore records). AI is not allowed to create a "sounding reasonable" 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 problems are found in architecture, record them as "observations" and let the user decide whether to start another workflow to handle them.
Do not diverge — Do not expand on issues outside the scope described by the user; just record them as observations.

Exit Conditions

Single mode (new / update) and single target document have been locked
Phase 4 self-check list has been gone through item by item, and handling results have been reported
Document frontmatter is complete, with
```
doc_type: requirement
```
,
```
pitch
```
,
```
status
```
,
```
last_reviewed
```
all filled in
All 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 nonsense like "As a user, I want the system to be easy to use"
No implementation details are stuffed into 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 clearly 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 `easysdd-architecture`	Requirements describe "why it's needed", architecture describes "how to build it"; the frontmatter of architecture docs uses `implements: [req-slug]` to link back to the requirements it carries
Upstream of `easysdd-feature-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; features for pure refactoring / technical debt do not require a mandatory requirement
Downstream of `easysdd-feature-acceptance`	If it is found during acceptance that a feature has changed the boundaries or user stories of a capability → trigger the `update` mode of this skill to refresh the corresponding requirement
Creator of `easysdd-onboarding`	Create an empty `easysdd/requirements/` directory during onboarding, which will be filled by this skill later

Common Mistakes

Written as a PRD field stack: Readers have to read through each field to get the full picture
Tone is like giving a lecture: Throw away openings like "This capability aims to provide..." immediately
Title uses metaphors: "Let AI be your first reader when fixing bugs" < "Explore and analyze first when fixing bugs"
User stories are too abstract: "As a user, I want the system to be easy to use" — delete it
Implementation details are stuffed in: "Implement Y by calling X interface" — this belongs in architecture docs
Boundaries are not written: Requirements will be misused leading to disappointment
Technical jargon is stuffed into the
```
pitch
```
field: Cannot be extracted for promotional use
Drafting multiple documents at once: User review is not in-depth, all are roughly merged
Scope is too large: Multiple independent capabilities are stuffed into one doc — split it
Adding paragraphs out of thin air in update mode: Content will drift further from reality

easysdd-requirements

NPX Install

Tags

SKILL.md Content (Chinese)

easysdd-requirements

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 Conditions

Relationship with Other Workflows

Common Mistakes