docs: fix requirements documentation traceability

[santi698]

This PR improves the traceability and consistency of requirement documentation by adding missing metadata fields and clarifying requirement types across all stakeholder and software requirements.

Changes

• Add missing "Requirement Type" and title to system health and settings requirements
• Annotate requirement types with descriptive comments

[github-actions]

Claude encountered an error —— View job

---

PR Review: Requirements Documentation Traceability

Reviewing changes to requirement documentation files...

Tasks

• Examine changed requirement files to understand the pattern
• Check for consistency across all 50 files
• Verify commit message format
• Review metadata completeness
• Check for any CLAUDE.md guidance on requirements
• Provide comprehensive feedback

[github-actions]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[github-actions]

Claude finished @santi698's task —— View job

---

PR Review: Requirements Documentation Traceability ✅

I've completed a comprehensive review of this PR which improves traceability of requirement documentation across 50 requirement files.

Tasks

• Examine sample requirement files to understand the change pattern
• Verify commit message format (conventional commits)
• Check all 50 files for consistency
• Verify metadata completeness across all requirements
• Check for any additional issues
• Provide comprehensive feedback

---

Summary

This PR successfully improves requirements traceability by:

1. ✅ Adding missing itemTitle fields to 3 system requirements
2. ✅ Adding descriptive comments to all Requirement type fields for clarity
3. ✅ Minor formatting improvements (line wrapping, blank line additions)

All changes are consistent, complete, and follow proper conventions. 🎉

---

Detailed Findings

✅ Commit Messages

All commits follow conventional commit format correctly:

• docs(requirements): add missing itemTitle to system health and settings requirements
• docs: annotate requirement type in requirement files with the actual mapped value
• docs: add missing "Requirement Type" to some requirements

✅ Metadata Completeness

Before this PR:

• 3 files missing itemTitle:
  • SWR_SYSTEM_CLI_HEALTH_1.md
  • SWR_SYSTEM_GUI_HEALTH_1.md
  • SWR_SYSTEM_GUI_SETTINGS_1.md
• All files had bare Requirement type values without explanatory comments

After this PR:

• ✅ All 50 requirement files now have itemTitle
• ✅ All 50 files have descriptive comments on Requirement type
• ✅ Consistent formatting across all files

✅ Requirement Type Annotations

The PR adds consistent, clear annotations to requirement types:

Stakeholder Requirements (9 files):

Requirement type: ENVIRONMENT # Stakeholder requirement (user)

Software Requirements (41 files):

Requirement type: FUNCTIONAL # Software requirement (user)
Requirement type: REGULATORY # Software requirement (system)

This mapping is correct and consistent:

• SHR-* files → ENVIRONMENT (stakeholder/user)
• SWR-* files → FUNCTIONAL (software/user) or REGULATORY (software/system)

✅ Formatting Improvements

Several files received minor formatting improvements:

• Cleaner line wrapping (e.g., SWR-APPLICATION-2-15.md)
• Added blank lines between YAML frontmatter and content (e.g., SWR-APPLICATION-2-12.md)
• More consistent spacing throughout

---

Verification Commands

I verified completeness with these commands:

# Verify all files have itemTitle (should return nothing)
grep -L "itemTitle:" requirements/*.md

# Verify all files have Requirement type (should return nothing)
grep -L "Requirement type:" requirements/*.md

# Check requirement type consistency
grep -h "Requirement type:" requirements/SHR-*.md | sort -u
# Result: Requirement type: ENVIRONMENT # Stakeholder requirement (user)

grep -h "Requirement type:" requirements/SWR*.md | sort -u
# Result: 
# Requirement type: FUNCTIONAL # Software requirement (user)
# Requirement type: REGULATORY # Software requirement (system)

# Verify all 50 files updated
git diff main...HEAD --name-only | grep "requirements/" | wc -l
# Result: 50

---

Coverage

Files updated: 50/50 (100%)

• 9 Stakeholder Requirements (SHR-*)
• 41 Software Requirements (SWR-*)

Changes per file:

• Most files: +1/-1 (adding comment to Requirement type)
• 3 system files: +2/+0 (adding itemTitle + Requirement type)
• A few files: +2/-1 or more (formatting improvements)

Total impact: +63 lines, -50 lines

---

Recommendations

✅ No blocking issues

This PR is ready to merge! All changes are:

• Consistent across all files
• Properly documented in commit messages
• Improving traceability as intended
• Non-breaking (documentation only)

💡 Optional Enhancement (Future PR)

Consider creating a requirements/README.md to document:

• Requirement type taxonomy (ENVIRONMENT, FUNCTIONAL, REGULATORY)
• Naming conventions (SHR-* vs SWR-*)
• Required metadata fields (itemId, itemTitle, itemType, Requirement type, etc.)
• Traceability relationships (itemHasParent)

This would help maintainers ensure consistency when adding new requirements.

---

Conclusion

Status: ✅ APPROVED

This PR successfully improves requirements documentation traceability by:

1. Completing missing metadata (itemTitle)
2. Clarifying requirement types with descriptive comments
3. Maintaining consistency across all 50 requirement files

The changes are minimal, focused, and achieve the stated goal of improving traceability and consistency. No issues found.

Great work @santi698! 🎉

---

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.