---
title: "Requirements"
description: "Managing requirements, features, stories, and acceptance criteria in TraceRTM"
---

# Requirements

Requirements artifacts capture **what** the system should do. They form the foundation of traceability, serving as the source for design, implementation, and verification activities.

## Requirement Types

TraceRTM supports multiple levels of requirements:

| Level | Type | Example | Typical Source |
|-------|------|---------|----------------|
| Business | Need | "Increase customer retention" | Stakeholders |
| System | Requirement | "Support 10K concurrent users" | Business analysis |
| Software | Requirement | "API responds < 200ms" | Technical analysis |
| Feature | Feature | "User authentication" | Product backlog |
| Story | Story | "As a user, I can login" | Sprint backlog |
| Acceptance | Criterion | "Login < 2 seconds" | Definition of Done |

## Creating Requirements

### Basic Requirement

```python
from tracertm import TraceRTMClient

client = TraceRTMClient()

# Create a feature requirement
feature = client.create_item(
    title="User Authentication",
    item_type="feature",
    description="""
    Allow users to securely authenticate to the system.

    ## Scope
    - Email/password login
    - OAuth2 social login
    - Multi-factor authentication (optional)

    ## Out of Scope
    - Biometric authentication
    - Hardware tokens
    """,
    priority="high",
    metadata={
        "category": "security",
        "target_release": "v2.0",
        "stakeholder": "security_team"
    }
)
```

### User Story

```python
story = client.create_item(
    title="As a user, I can reset my forgotten password",
    item_type="story",
    description="""
    **User Story**
    As a registered user
    I want to reset my password
    So that I can regain access to my account

    **Background**
    Users forget passwords. Self-service reset reduces support tickets.
    """,
    metadata={
        "sprint": "Sprint-5",
        "story_points": 5,
        "assigned_to": "bob@company.com"
    }
)

# Link to parent feature
client.create_link(story.id, feature.id, "part_of")
```

### Acceptance Criteria

```python
# Create acceptance criteria as separate items
criteria = [
    ("Email sent within 30 seconds", "functional"),
    ("Reset link expires after 24 hours", "security"),
    ("Old password works until reset complete", "usability"),
    ("Account locked after 3 failed attempts", "security")
]

for title, category in criteria:
    ac = client.create_item(
        title=title,
        item_type="acceptance_criterion",
        metadata={"category": category}
    )
    client.create_link(ac.id, story.id, "criterion_of")
```

## CLI Usage

```bash
# Create requirement
tracertm create feature "User Authentication" \
  --description "Allow users to log in" \
  --priority high \
  --metadata '{"category": "security"}'

# Create story
tracertm create story "As a user, I can login" \
  --parent FEAT-001 \
  --metadata '{"sprint": "Sprint-5", "points": 5}'

# List requirements
tracertm list --type feature
tracertm list --type story --status draft

# Search requirements
tracertm search "authentication" --type feature,story

# Get requirement details
tracertm get FEAT-001 --show-links
```

## Requirement Attributes

### Standard Fields

```yaml
# Required fields
title: "User Authentication"
item_type: feature

# Common optional fields
description: "Detailed description..."
status: draft | ready | in_progress | done | blocked
priority: critical | high | medium | low

# Metadata for requirements
metadata:
  # Classification
  category: security | performance | usability | functional
  level: system | software | feature | story

  # Planning
  sprint: Sprint-5
  story_points: 5
  target_release: v2.0

  # Ownership
  assigned_to: alice@company.com
  stakeholder: product_team

  # Compliance
  regulatory_reference: ISO-27001-A.9
  safety_class: C

  # Custom tags
  tags: [auth, security, mvp]
```

### Requirement States

```yaml
# .tracertm/workflows/requirement.yaml
name: requirement
states:
  - draft        # Being written
  - review       # Under stakeholder review
  - approved     # Approved for implementation
  - in_progress  # Being implemented
  - done         # Implemented and verified
  - deferred     # Postponed
  - rejected     # Not approved

transitions:
  - from: draft
    to: review
    requires:
      - field: description
        not_empty: true
      - field: priority
        not_null: true

  - from: review
    to: approved
    requires:
      - approval:
          role: product_owner
```

## Traceability for Requirements

### Linking Requirements

```python
# Link requirement to business need
client.create_link(
    source_id=sw_req.id,
    target_id=business_need.id,
    link_type="derives_from"
)

# Link requirement to design
client.create_link(
    source_id=design.id,
    target_id=sw_req.id,
    link_type="realizes"
)

# Link requirement to test
client.create_link(
    source_id=test.id,
    target_id=sw_req.id,
    link_type="verifies"
)

# Link requirement to code
client.create_link(
    source_id=code.id,
    target_id=sw_req.id,
    link_type="implements"
)
```

### Traceability Matrix

```bash
# Generate requirement traceability matrix
tracertm report matrix --from feature --to test

# Output:
# Feature → Test Traceability Matrix
# ══════════════════════════════════════════════════
#
#              TEST-001  TEST-002  TEST-003  TEST-004
# FEAT-001        ✓         ✓
# FEAT-002                  ✓         ✓
# FEAT-003                            ✓         ✓
# FEAT-004        ⚠ No tests
#
# Coverage: 75% (3/4 features have tests)
```

### Coverage Analysis

```python
# Check requirement coverage
coverage = client.get_coverage(
    source_type="feature",
    target_type="test"
)

print(f"Coverage: {coverage.percentage}%")
print(f"Covered: {coverage.covered_count}/{coverage.total_count}")
print(f"Gaps: {[g.id for g in coverage.gaps]}")
```

## Requirements Hierarchy

### System to Software Decomposition

```
SYSTEM REQUIREMENT
├── SOFTWARE REQUIREMENT
│   ├── FEATURE
│   │   ├── STORY
│   │   │   ├── ACCEPTANCE CRITERION
│   │   │   └── ACCEPTANCE CRITERION
│   │   └── STORY
│   └── FEATURE
└── SOFTWARE REQUIREMENT
```

### Configuration

```yaml
# .tracertm/config.yaml
hierarchy:
  system_requirement:
    children: [software_requirement]

  software_requirement:
    parent: system_requirement
    children: [feature]

  feature:
    parent: software_requirement
    children: [story]

  story:
    parent: feature
    children: [acceptance_criterion, task]

  acceptance_criterion:
    parent: story
    terminal: true
```

### Working with Hierarchy

```python
# Create hierarchical requirements
sys_req = client.create_item(
    title="System shall support 10K concurrent users",
    item_type="system_requirement"
)

sw_req = client.create_item(
    title="Login API responds within 200ms under load",
    item_type="software_requirement",
    parent_id=sys_req.id
)

feature = client.create_item(
    title="User Authentication",
    item_type="feature",
    parent_id=sw_req.id
)

# Navigate hierarchy
children = client.get_children(sys_req.id)
ancestors = client.get_ancestors(feature.id)
tree = client.get_tree(sys_req.id, depth=4)
```

## Importing Requirements

### From CSV

```python
import csv
from tracertm import TraceRTMClient

client = TraceRTMClient()

with open("requirements.csv") as f:
    reader = csv.DictReader(f)
    for row in reader:
        client.create_item(
            title=row["title"],
            item_type="feature",
            description=row["description"],
            priority=row["priority"],
            metadata={
                "external_id": row["id"],
                "category": row["category"]
            }
        )
```

### From Jira

```python
from jira import JIRA
from tracertm import TraceRTMClient

jira = JIRA(server="https://company.atlassian.net", token_auth="...")
client = TraceRTMClient()

# Import epics and stories
for epic in jira.search_issues('type=Epic AND project=PROJ'):
    feature = client.create_item(
        title=epic.fields.summary,
        item_type="feature",
        description=epic.fields.description,
        metadata={
            "jira_key": epic.key,
            "jira_url": epic.permalink()
        }
    )

    # Import child stories
    for story in jira.search_issues(f'"Epic Link"={epic.key}'):
        client.create_item(
            title=story.fields.summary,
            item_type="story",
            parent_id=feature.id,
            metadata={
                "jira_key": story.key,
                "story_points": story.fields.customfield_10016
            }
        )
```

## Validation

### Required Fields

```yaml
# .tracertm/config.yaml
validation:
  feature:
    required_fields:
      - title
      - description
      - priority

    required_links:
      - link_type: verified_by
        target_type: test
        min_count: 1
        before_status: done
```

### Completeness Check

```bash
# Validate requirements completeness
tracertm validate --type feature

# Output:
# Feature Validation Report
# ═════════════════════════
#
# Completeness:
#   ✓ All features have descriptions (42/42)
#   ✓ All features have priorities (42/42)
#   ✗ 3 features missing acceptance criteria
#
# Traceability:
#   ✓ All features have tests (42/42)
#   ✗ 2 features missing code links
#
# Issues:
#   FEAT-015: Missing acceptance criteria
#   FEAT-021: Missing acceptance criteria
#   FEAT-033: Missing acceptance criteria
#   FEAT-042: No code linked
#   FEAT-089: No code linked
```

## Best Practices

### 1. Write SMART Requirements

```
S - Specific: Clear and unambiguous
M - Measurable: Verifiable criteria
A - Achievable: Technically feasible
R - Relevant: Aligned with goals
T - Testable: Can be verified
```

### 2. Include Acceptance Criteria

```python
# Every story should have acceptance criteria
story = client.create_item(
    title="As a user, I can login",
    item_type="story",
    metadata={
        "acceptance_criteria": [
            "Valid credentials return JWT token",
            "Invalid credentials return 401",
            "Locked account shows appropriate message",
            "Login form is accessible (WCAG 2.1)"
        ]
    }
)
```

### 3. Maintain Traceability

```python
# Link at creation time, not later
feature = client.create_item(title="Login", item_type="feature")

# Immediately link to parent
client.create_link(feature.id, epic.id, "part_of")

# Link tests as they're created
test = client.create_item(title="Test Login", item_type="test")
client.create_link(test.id, feature.id, "tests")
```

### 4. Use Consistent Terminology

```yaml
# Define terms in glossary
glossary:
  - term: "User"
    definition: "A person with valid credentials in the system"
  - term: "Authentication"
    definition: "The process of verifying user identity"
  - term: "Session"
    definition: "A time-limited authenticated state"
```

## Related Topics

- [Design](/docs/wiki/concepts/artifacts/design) - Design artifacts
- [Test Cases](/docs/wiki/concepts/artifacts/test-cases) - Verification
- [Traceability](/docs/wiki/concepts/traceability) - Linking artifacts
- [Coverage Analysis](/docs/getting-started/first-project/reports) - Gap detection

