majiayu000 Web Playground Requirements
Create Requirements documents that define success criteria aligned to Foundation anchors.
Prerequisites
Foundation must be verified before writing requirements.
Check .sdd/state.yaml:
documents:
foundation:
status: verified # must be verified
REQ ID Formats
| Level | Format | Example |
|---|---|---|
| Root | REQ-{NNN} |
REQ-001, REQ-002 |
| Package | REQ-{PKG}-{NNN} |
REQ-REACT-001, REQ-NEST-001 |
Instructions
1. Choose Level
- Root:
spec/requirements.md(cross-cutting requirements) - Package:
packages/{pkg}/spec/requirements.md(sample-specific)
2. Write Frontmatter
---
title: "{Package} Requirements"
version: 1.0.0
status: draft
depends_on:
- foundation.md@1.0.0 # or root::foundation.md@1.0.0 for packages
---
3. Write Each Requirement
## REQ-001: {Title}
{Description of what the system must do}
`@aligns-to:` {ANCHOR-NAME}
**Status:** draft
**Verification:** {How to verify this requirement is met}
4. Add Alignment Links
Every requirement must have @aligns-to linking to Foundation anchors.
Root requirements: Link to root anchors
`@aligns-to:` SCOPE-MONOREPO, QUALITY-TYPESCRIPT
Package requirements: Can link to root or package anchors
`@aligns-to:` PATTERN-HOOKS, root::QUALITY-TESTED
5. Build Coverage Matrix
Track which anchors are addressed:
## Coverage Matrix
| Anchor | Requirements |
|--------|--------------|
| SCOPE-MONOREPO | REQ-001 |
| QUALITY-TYPESCRIPT | REQ-001, REQ-003 |
| PATTERN-HOOKS | REQ-REACT-001, REQ-REACT-002 |
6. Update State
Claim ownership and update .sdd/state.yaml:
documents:
requirements: { status: draft, version: 1.0.0, owner: claude }
Example: Package Requirements
---
title: "React Sample Requirements"
version: 1.0.0
status: draft
depends_on:
- foundation.md@1.0.0
- root::foundation.md@1.0.0
---
# React Sample Requirements
## REQ-REACT-001: Todo CRUD Operations
User can create, read, update, and delete todo items.
`@aligns-to:` DEMO-TODO-APP, root::SCOPE-SHOWCASE
**Status:** draft
**Verification:**
- Create: new item appears in list
- Read: items persist across page reload (localStorage)
- Update: can edit item text, toggle completion
- Delete: item removed from list
---
## REQ-REACT-002: Hooks-Only State
All component state uses React hooks (useState, useReducer, useContext).
`@aligns-to:` PATTERN-HOOKS, TECH-REACT-18
**Status:** draft
**Verification:** No class components in codebase; grep for `extends Component` returns empty.
---
## Coverage Matrix
| Anchor | Requirements |
|--------|--------------|
| DEMO-TODO-APP | REQ-REACT-001 |
| PATTERN-HOOKS | REQ-REACT-002 |
| TECH-REACT-18 | REQ-REACT-002 |
| root::SCOPE-SHOWCASE | REQ-REACT-001 |
Verification
After writing requirements:
- Frontmatter has depends_on pointing to verified foundation
- Every REQ has unique ID in correct format
- Every REQ has
@aligns-towith valid anchor(s) - Cross-level refs use
root::prefix - Coverage matrix shows no unaddressed anchors
- Each REQ has verification criteria
Alignment Check
| Check | Pass | Fail |
|---|---|---|
| Coverage | Every anchor has >= 1 REQ | Anchor unaddressed |
| Scope | REQ within Foundation scope | Outside scope |
| Non-contradiction | Consistent with constraints | Violates constraint |
State Update
After all requirements verified:
documents:
requirements: { status: verified, version: 1.0.0, owner: human }
current_phase: design
Transfer ownership when complete. If blocked on scope decision, escalate:
escalations:
- id: ESC-001
description: "REQ-003 unclear if within scope"
status: pending
Next Phase
When requirements are verified, proceed to design:
- Create design items with
@deriveslinks to requirements - Document significant decisions as DEC-NNN
Reference
For full details: docs/sdd-guidelines.md sections 1.2, 2, 3