jt55401 Requirements Maintenance
Use this skill to keep requirements docs coherent, navigable, and aligned with implementation evidence.
When To Use
- Add or revise requirement stories
- Break down vague requirements into single-behavior stories
- Repair relative links between requirements and tickets
- Detect overlap, duplication, and contradictions before merge
- Prepare requirement changelog summaries from conventional commits
Path Setup
Choose paths before editing:
<requirements-register>: top-level register markdown<requirements-root>: requirements tree root<tickets-root>: ticket folder linked by requirement stories
For this repository's example:
<requirements-register>:examples/saas-webapp/requirements.md<requirements-root>:examples/saas-webapp/requirements<tickets-root>:examples/saas-webapp/tickets
Workflow
- Identify impacted area folder(s) in
<requirements-root>/. - Edit story files first (smallest unit, one behavior each).
- Refresh area indexes and navigation links.
- Run conflict detection gate.
- Resolve errors; document intentional overlap when warnings are expected.
- Update changelog content when requested.
- Provide commit-ready requirement summaries with traceable refs.
Authoring Rules
- Preserve 4-digit spaced numbering (
0110,0120, ...). - Keep one behavior per story file.
- Include these sections in each story:
User StoryKey Fields/ParametersAcceptance CriteriaEvidenceLinked Tickets
Command Gate
Run conflict detection:
python3 .claude/scripts/check_requirements_conflicts.py --root <requirements-root>
PR-focused mode:
python3 .claude/scripts/check_requirements_conflicts.py --root <requirements-root> --changed-only --range HEAD~1..HEAD
Generate changelog snippet:
python3 .claude/scripts/extract_requirements_changelog.py --range HEAD --changelog-file <requirements-root>/CHANGELOG.md
Apply changelog snippet:
python3 .claude/scripts/extract_requirements_changelog.py --range HEAD --changelog-file <requirements-root>/CHANGELOG.md --apply
Commit Convention
Use conventional commit subject:
docs(requirements-<area>): <short requirement summary>
Recommended footers:
Req-Refs: <ids/files>
Changelog: requirements
Req-Summary: <single sentence>