# Your First Requirements Project
In this chapter, we'll build a complete requirements hierarchy for a simple project: a task management application. You'll learn how to structure requirements across multiple levels and establish traceability.
## Planning the Hierarchy
A typical requirements hierarchy has multiple levels:
1. **User Requirements (USR)** - High-level needs from the user's perspective
2. **System Requirements (SYS)** - Technical specifications that satisfy user needs
3. **Software Requirements (SWR)** - Detailed implementation requirements (optional)
4. **Test Requirements (TST)** - Test cases that verify requirements (optional)
For our task app, we'll use USR and SYS levels.
## Setting Up the Project
Create and enter a new directory:
```bash
mkdir task-app-requirements
cd task-app-requirements
```
## Creating User Requirements
User requirements describe what users need, not how it's implemented.
```bash
req add USR # USR-001
req add USR # USR-002
req add USR # USR-003
```
Edit each file to add content:
**USR-001.md:**
```markdown
---
_version: '1'
uuid: <auto-generated>
created: <auto-generated>
---
# USR-001 Create Tasks
Users shall be able to create tasks with a title and description.
```
**USR-002.md:**
```markdown
---
_version: '1'
uuid: <auto-generated>
created: <auto-generated>
---
# USR-002 Mark Tasks Complete
Users shall be able to mark tasks as complete.
```
**USR-003.md:**
```markdown
---
_version: '1'
uuid: <auto-generated>
created: <auto-generated>
---
# USR-003 Filter Tasks
Users shall be able to filter tasks by completion status.
```
## Creating System Requirements
System requirements break down user requirements into technical specifications.
For `USR-001` (creating tasks), we need:
```bash
req add SYS --parents USR-001 # SYS-001
req add SYS --parents USR-001 # SYS-002
```
**SYS-001.md:**
```markdown
---
_version: '1'
uuid: <auto-generated>
created: <auto-generated>
parents:
- uuid: <USR-001 uuid>
fingerprint: <auto-generated>
hrid: USR-001
---
# SYS-001 Task Data Structure
The system shall provide a Task data structure with fields: id, title, description, completed, created_at.
```
**SYS-002.md:**
```markdown
---
_version: '1'
uuid: <auto-generated>
created: <auto-generated>
parents:
- uuid: <USR-001 uuid>
fingerprint: <auto-generated>
hrid: USR-001
---
# SYS-002 Task Title Validation
The system shall validate that task titles are non-empty strings with maximum 100 characters.
```
For `USR-002` (marking complete):
```bash
req add SYS --parents USR-002 # SYS-003
```
**SYS-003.md:**
```markdown
---
_version: '1'
uuid: <auto-generated>
created: <auto-generated>
parents:
- uuid: <USR-002 uuid>
fingerprint: <auto-generated>
hrid: USR-002
---
# SYS-003 Toggle Task Completion
The system shall provide a method to toggle the completed status of a task.
```
For `USR-003` (filtering):
```bash
req add SYS --parents USR-003 # SYS-004
```
**SYS-004.md:**
```markdown
---
_version: '1'
uuid: <auto-generated>
created: <auto-generated>
parents:
- uuid: <USR-003 uuid>
fingerprint: <auto-generated>
hrid: USR-003
---
# SYS-004 Filter Tasks by Status
The system shall provide a method to filter tasks returning only those matching the specified completion status.
```
## Creating Cross-Cutting Requirements
Some requirements affect multiple user needs. For example, persistence:
```bash
req add SYS --parents USR-001,USR-002,USR-003 # SYS-005
```
**SYS-005.md:**
```markdown
---
_version: '1'
uuid: <auto-generated>
created: <auto-generated>
parents:
- uuid: <USR-001 uuid>
fingerprint: <auto-generated>
hrid: USR-001
- uuid: <USR-002 uuid>
fingerprint: <auto-generated>
hrid: USR-002
- uuid: <USR-003 uuid>
fingerprint: <auto-generated>
hrid: USR-003
---
# SYS-005 Task Persistence
The system shall persist all tasks to disk and load them on startup.
```
This requirement has three parents because it affects creating, completing, and filtering tasks.
## Reviewing Your Requirements Structure
Your directory now contains:
```
task-app-requirements/
├── USR-001.md (Create tasks)
├── USR-002.md (Mark complete)
├── USR-003.md (Filter tasks)
├── SYS-001.md → USR-001 (Task data structure)
├── SYS-002.md → USR-001 (Title validation)
├── SYS-003.md → USR-002 (Toggle completed)
├── SYS-004.md → USR-003 (Filter method)
└── SYS-005.md → USR-001, USR-002, USR-003 (Persistence)
```
## Version Control Integration
Requirements are plain text, so they work great with Git:
```bash
git init
git add *.md
git commit -m "Initial requirements for task management app"
```
Every requirement change will now show up in your Git history with clear diffs:
```diff
--- a/USR-001.md
+++ b/USR-001.md
@@ -4,4 +4,4 @@
created: 2025-07-22T12:19:56.950194157Z
---
-Users shall be able to create tasks with a title and description.
+Users shall be able to create tasks with a title, description, and due date.
```
## Best Practices Demonstrated
This example shows several best practices:
1. **Start high-level** - Begin with user requirements before diving into technical details
2. **One concept per requirement** - Each requirement addresses a single, testable concept
3. **Use clear language** - Requirements use "shall" to indicate mandatory behavior
4. **Establish traceability** - Every system requirement traces to at least one user requirement
5. **Support multiple parents** - Cross-cutting concerns can satisfy multiple needs
## Next Steps
Now that you understand the basics, explore:
- [Core Concepts](../core-concepts.md) - Deeper dive into requirements management principles
- [Working with Requirements](../working-with-requirements.md) - Advanced features and techniques
- [Configuration](../configuration.md) - Customizing Requiem for your project
Continue reading to learn how Requiem supports advanced requirements management practices.