# Writing Good Requirements

Good requirements are clear, unambiguous, verifiable, and traceable. This guide covers characteristics, patterns, and common mistakes.

## Characteristics of Good Requirements (SMART)

| Characteristic | Meaning | Check |
|---|---|---|
| **Specific** | Clear and precise, no ambiguity | Could two people interpret differently? |
| **Measurable/Verifiable** | Can be tested or inspected to confirm satisfaction | How would we prove this is met? |
| **Achievable/Attainable** | Technically and economically feasible | Realistic given constraints? |
| **Relevant/Appropriate** | Traces to a need, appropriate level of detail | Does this solve the stated need? |
| **Traceable/Time-bound** | Can be traced and has clear scope | Linked to parent need/requirement? |

## The "Shall" Rule

Use **"shall"** for mandatory requirements. Avoid:
- **"will"** - often states facts, not requirements
- **"should"** - implies preference, not binding
- **"may"** - implies optional, unclear if required
- **"must"** - acceptable but "shall" is more common in standards

**Example:** "The system shall authenticate users via OAuth 2.0 before granting access."

## Requirements Writing Patterns

| Pattern | When to Use | Example |
|---|---|---|
| **Action-Oriented** | Functional requirements | "The system shall validate user input against schema X" |
| **Performance** | Quantifiable performance needs | "The system shall respond to search queries in < 200ms at p95" |
| **Interface** | Defining interfaces | "The system shall expose a REST API at /api/v1/..." |
| **Constraint** | Non-negotiable constraints | "The system shall not store plaintext passwords" |
| **Condition** | Behavior under conditions | "If authentication fails 3 times, the system shall lock the account for 15 minutes" |

## Common Anti-Patterns

| Anti-Pattern | Bad Example | Good Example |
|---|---|---|
| **Vague** | "The system shall be fast" | "The system shall load the dashboard in < 2 seconds on 4G" |
| **Unverifiable** | "The system shall be user-friendly" | "The system shall pass usability testing with SUS score > 80" |
| **Solution in requirement** | "The system shall use Redis for caching" | "The system shall cache frequently accessed data with < 10ms retrieval" (unless Redis is a constraint) |
| **Multiple requirements** | "The system shall login users and log all activity and send emails" | Split into separate requirements |
| **Negative-only** | "The system shall not crash" | Better to state positive behavior or specific reliability requirement |
| **Escape clauses** | "The system shall... if possible" | Remove or make explicit as a constraint/trade-off |

## Types of Requirements

| Type | Description | Example |
|---|---|---|
| **Functional (FR)** | What the system does | "The system shall generate a summary of uploaded documents" |
| **Performance** | How well it performs | "The system shall process 1000 requests/minute" |
| **Interface** | How it interacts | "The system shall integrate via MCP protocol" |
| **Security** | Security-related needs | "The system shall encrypt data at rest using AES-256" |
| **Reliability/Availability** | Uptime, fault tolerance | "The system shall achieve 99.9% uptime excluding scheduled maintenance" |
| **Usability** | User experience | "A new user shall complete onboarding in < 3 minutes" |
| **Maintainability** | Ease of changes | "The system shall have automated tests with > 80% coverage on critical paths" |
| **Portability** | Deployment flexibility | "The system shall run on Linux x86_64 and ARM64" |
| **Regulatory/Compliance** | Legal/compliance | "The system shall comply with GDPR data deletion requirements" |

## Requirements Checklist

For each requirement, verify:
- [ ] **Clear**: No ambiguous words (fast, easy, user-friendly, robust)
- [ ] **Singular**: One requirement per statement
- [ ] **Verifiable**: Can be verified by test, analysis, inspection, or demonstration
- [ ] **Feasible**: Achievable within constraints
- [ ] **Necessary**: Traces to a stakeholder need
- [ ] **Correct**: Accurately reflects the need
- [ ] **Complete**: Sufficient for design
- [ ] **Consistent**: No conflicts with other requirements
- [ ] **Traceable**: Has unique ID and trace links

## Verification Methods

| Method | Description | When to Use |
|---|---|---|
| **Inspection** | Visual examination of design/documents | Documents, interfaces, code structure |
| **Analysis** | Mathematical/modeling analysis | Performance predictions, safety analysis |
| **Demonstration** | Operation of system to show requirement met | Functional behavior, user workflows |
| **Test** | Controlled testing with measured results | Quantitative requirements (latency, accuracy) |

## Example: Agentic System Requirements

```text
REQ-001: The agent shall authenticate using the configured identity provider before executing tools.
REQ-002: The agent shall log all tool invocations with timestamp, user, tool name, and parameters.
REQ-003: The system shall return responses within 5 seconds at p95 for simple queries.
REQ-004: The agent shall refuse requests classified as harmful per the safety policy.
REQ-005: The system shall provide source citations for RAG-generated answers.
```

## Related Notes

- [[Requirements-Engineering/Needs-Vs-Requirements.md]] — From needs to requirements
- [[Requirements-Engineering/Requirements-Analysis-Traceability.md]] — Traceability matrices
- [[Verification-Validation/Verification-Methods.md]] — How to verify
- [[../SoftEngine/Testing/Test-Pyramid.md]] — Mapping to tests
- [[../AgenticEngineering/Evaluation/Metrics.md]] — Eval metrics as requirements

## Sources

* ISO/IEC/IEEE 29148:2018  
* INCOSE Systems Engineering Handbook  
* NASA Systems Engineering Handbook  
* MITRE Systems Engineering Guide  
* Kossiakoff et al. - *Systems Engineering Principles and Practice*