tomevault-io Requirement Writing Patterns
Write requirements that are clear, testable, and unambiguous. Good requirements prevent implementation confusion and reduce clarification cycles.
Quick Reference
The INVEST Criteria for User Stories
| Letter | Criterion | Test |
|---|---|---|
| I | Independent | Can be implemented without other stories |
| N | Negotiable | Details can be discussed, not locked |
| V | Valuable | Delivers user/business value |
| E | Estimable | Team can estimate effort |
| S | Small | Fits in one sprint/iteration |
| T | Testable | Has clear acceptance criteria |
Requirement Levels
| Level | Format | Use When |
|---|---|---|
| Epic | High-level capability | Planning roadmaps |
| Feature | User-facing functionality | Release planning |
| User Story | As a [role], I want [goal], so that [benefit] | Sprint planning |
| Acceptance Criterion | Given/When/Then | Implementation guidance |
Writing Testable Requirements
The "Shall" Pattern
For formal requirements, use "shall" for mandatory and "should" for recommended:
REQ-001: The system shall authenticate users via OAuth 2.0.
REQ-002: The system shall reject requests without valid tokens with HTTP 401.
REQ-003: The system should cache tokens for up to 1 hour.
The User Story Pattern
For agile contexts, use the standard format:
As a [specific role],
I want [concrete action],
So that [measurable benefit].
Good example:
As a registered user,
I want to reset my password via email link,
So that I can regain access within 5 minutes without contacting support.
Bad example:
As a user,
I want better security,
So that things work properly.
Acceptance Criteria (Given/When/Then)
Every requirement needs testable acceptance criteria:
**Given** a registered user with a valid email
**When** they request a password reset
**Then** they receive an email within 30 seconds
**And** the link expires after 24 hours
**And** clicking the link allows setting a new password
Ambiguity Markers to Avoid
These words indicate vague requirements that need refinement:
| Marker | Problem | Fix |
|---|---|---|
| "properly" | Undefined correctness | Specify exact behavior |
| "quickly" | No metric | Add time constraint (e.g., "<200ms") |
| "user-friendly" | Subjective | Define specific UX criteria |
| "secure" | Vague | List specific security controls |
| "etc." | Incomplete list | Enumerate all items or state "including but not limited to" |
| "appropriate" | Undefined standard | Specify the standard |
| "as needed" | Undefined trigger | Define when/what triggers |
| "may/might" | Uncertain scope | Decide: is it in scope or not? |
Requirement Identifiers
Use consistent ID schemes for traceability:
REQ-001 # Simple sequential
FR-001 # Functional requirement
NFR-001 # Non-functional requirement
SEC-001 # Security requirement
PERF-001 # Performance requirement
Constraints vs Requirements
Requirements = What the system must DO Constraints = Limits on HOW it's built
## Requirements
- REQ-001: System shall support 1000 concurrent users
## Constraints
- CON-001: Must use PostgreSQL 14+
- CON-002: Must deploy to AWS
- CON-003: Budget limit $500/month infrastructure
Common Anti-Patterns
| Anti-Pattern | Example | Fix |
|---|---|---|
| Solution masquerading as requirement | "Use Redis for caching" | "Response time < 100ms for cached data" |
| Compound requirement | "System shall authenticate and authorize" | Split into REQ-001 (auth) and REQ-002 (authz) |
| Unmeasurable quality | "System shall be fast" | "95th percentile latency < 200ms" |
| Missing actor | "Data shall be validated" | "System shall validate user input before storage" |
| Assumed knowledge | "Standard security practices" | List specific practices or reference standard |
Integration with SpecKit
When writing specs for /speckit.plan:
- Use REQ-XXX identifiers - Enables traceability to tasks
- Include acceptance criteria - Becomes task verification
- Mark unknowns as [TBD] -
/speckit.clarifywill find them - Group by domain - Enables domain-specific plans
Additional Resources
For detailed patterns and examples, see:
references/anti-patterns.md- Common mistakes with fixesreferences/examples.md- Complete requirement examples by domain
Verification Checklist
Before finalizing requirements:
- Every requirement has a unique identifier
- No vague adjectives (properly, quickly, appropriately)
- Each requirement is testable with clear criteria
- Requirements are independent (no hidden dependencies)
- Constraints are separated from requirements
- Unknowns are marked [TBD] for clarification
Converted and distributed by TomeVault — claim your Tome and manage your conversions.