Maintaining Requirements

Requirements evolve throughout a project's lifecycle. This chapter covers maintenance tasks that keep your requirements accurate and consistent.

Overview

Requiem provides tools for:

• Correcting HRIDs - Fixing parent references after renaming requirements
• Fingerprints and Change Detection - Understanding how Requiem tracks content changes
• Review Workflows - Managing reviews when requirements change (planned feature)

Common Maintenance Tasks

Regular Cleanup

Run req clean periodically to ensure consistency:

req clean

This command:

• Loads all requirements
• Validates frontmatter and format
• Corrects parent HRIDs if requirements were renamed
• Reports any errors or inconsistencies

Frequency: Run after major reorganizations or before releases.

After Renaming Requirements

If you rename requirement files (change HRIDs):

1. Rename the file:

mv USR-001.md USR-100.md

2. Update parent references:

req clean

3. Verify changes:

git diff

The clean command updates all parent HRIDs automatically.

After Editing Content

When requirement text changes:

1. Edit the markdown body
2. Save the file
3. Commit with a descriptive message:

git add USR-001.md
git commit -m "Update USR-001: clarify email validation requirement"

The fingerprint updates automatically when content changes, enabling change detection.

Managing Requirements at Scale

For projects with hundreds of requirements:

Use scripts: Automate repetitive tasks

# Example: Add a tag to all USR requirements
for file in USR-*.md; do
    # Add tag via sed or Python script
done

Use version control: Track changes over time

# See what requirements changed this sprint
git log --since="2 weeks ago" --name-only -- "*.md"

Use traceability: Understand impact of changes

# Find all children of a requirement
grep -r "uuid: <parent-uuid>" *.md

Maintenance Best Practices

1. Validate Before Committing

Always run req clean before committing changes:

req clean && git add -A && git commit -m "Update requirements"

This catches errors before they enter the repository.

2. Use Descriptive Commit Messages

Bad:

git commit -m "Update reqs"

Good:

git commit -m "Add USR-042: user data export requirement

Related to feature request #123. Establishes requirements
for CSV and JSON export formats."

3. Review Changes Carefully

Before committing requirement changes, review diffs:

git diff USR-001.md

Ensure:

• UUID hasn't changed (breaking traceability)
• Metadata is valid
• Content changes are intentional

4. Keep Requirements Current

Regular reviews: Schedule periodic requirement reviews

Update as needed: Don't let requirements become stale documentation

Archive obsolete requirements: Move to archived/ subdirectory rather than deleting

5. Document Maintenance Procedures

Create a CONTRIBUTING.md or similar:

# Requirements Maintenance

## Before Committing
1. Run `req clean`
2. Review diffs carefully
3. Don't modify UUIDs manually

## Renaming Requirements
1. Rename file
2. Run `req clean` to update parent references
3. Commit changes

## Adding Tags
Use YAML syntax in frontmatter...

Tools and Automation

Pre-commit Hooks

Automate validation with Git hooks:

#!/bin/bash
# .git/hooks/pre-commit

echo "Validating requirements..."
req clean

if [ $? -ne 0 ]; then
    echo "Error: Requirements validation failed"
    exit 1
fi

CI/CD Integration

Add requirement validation to CI:

# .github/workflows/requirements.yml
name: Validate Requirements

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Requiem
        run: cargo install requirements-manager
      - name: Validate requirements
        run: req clean
        working-directory: ./requirements

Scripts for Common Tasks

Find requirements without tests:

#!/bin/bash
# List USR requirements not linked by any TST requirement
comm -23 \
  <(ls USR-*.md | sed 's/.md//' | sort) \
  <(grep -oh "USR-[0-9]*" TST-*.md | sort -u)

Generate traceability report:

#!/bin/bash
# Show parent-child relationships
for file in *.md; do
    hrid=$(basename "$file" .md)
    parents=$(grep "hrid:" "$file" | awk '{print $2}')
    if [ -n "$parents" ]; then
        echo "$hrid -> $parents"
    fi
done

Error Recovery

Corrupted Frontmatter

If YAML becomes invalid:

1. Check syntax:

req clean  # Reports specific error

2. Fix manually or restore from Git:

git checkout HEAD -- USR-001.md

3. Use online YAML validator if needed

Duplicate UUIDs

If two requirements have the same UUID (serious error):

1. Requiem will panic with error message
2. Identify files with duplicate UUIDs
3. Manually assign new UUID to one:

uuidgen  # Generate new UUID
# Edit file, replace UUID

4. Verify:

req clean

Missing Parents

If a parent requirement is deleted but children still reference it:

1. Requiem reports error during req clean
2. Options:
   • Restore deleted parent
   • Remove parent reference from child
   • Link child to different parent

Merge Conflicts

When merging Git branches with requirement changes:

1. Resolve conflicts in frontmatter carefully:

   • UUIDs should never conflict (unique per requirement)
   • Timestamps: keep newer
   • Parents: merge both sets if both added parents

2. Resolve markdown body conflicts normally

3. After resolving:

req clean  # Validate merged result

Monitoring and Reporting

Requirement Statistics

Count requirements by kind:

ls USR-*.md | wc -l  # User requirements
ls SYS-*.md | wc -l  # System requirements

Change Tracking

Requirements changed in last month:

git log --since="1 month ago" --name-only --pretty=format: -- "*.md" | \
  sort -u | grep -E "^[A-Z]+-[0-9]+\.md$"

Coverage Analysis

Find requirements without children (potential gaps):

# Find USR requirements not referenced by any SYS requirement
comm -23 \
  <(ls USR-*.md | sed 's/.md//' | sort) \
  <(grep -roh "USR-[0-9]*" SYS-*.md | sort -u)

Next Steps

Dive deeper into specific maintenance topics:

• Correcting HRIDs - Using the req clean command
• Fingerprints - How change detection works
• Review Workflows - Managing reviews (planned)