What is the purpose of requirements-maintenance?

To keep requirements docs coherent, navigable, and aligned with implementation evidence by managing stories, links, conflicts, and changelog readiness.

How do I run conflict detection and derive a changelog?

Use the provided Python scripts: check_requirements_conflicts.py to detect conflicts and extract_requirements_changelog.py to generate changelog snippets; see the Command Gate and Commit sections.

What should be included in each story file?

User Story, Key Fields/Parameters, Acceptance Criteria, Evidence, Linked Tickets.

requirements-maintenance

Scanned

npx machina-cli add skill jt55401/requirements-skill/requirements-maintenance --openclaw

Files (1)

SKILL.md

2.7 KB

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 Story
- Key Fields/Parameters
- Acceptance Criteria
- Evidence
- Linked 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>

Source

git clone https://github.com/jt55401/requirements-skill/blob/main/.codex/skills/requirements-maintenance/SKILL.mdView on GitHub

Overview

Use this skill to keep requirements docs coherent, navigable, and aligned with implementation evidence. It covers story decomposition, link hygiene, conflict detection, and changelog-ready summaries.

How This Skill Works

Identify impacted area folders under <requirements-root> and edit stories one behavior per file. Refresh area indexes, run the conflict detection gate, and resolve issues; document intentional overlap when warnings are expected. Update changelog content when requested and provide commit-ready requirement summaries with traceable refs.

When to Use It

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

Quick Start

Step 1: Identify impacted area folders in <requirements-root/>.
Step 2: Edit story files (one behavior per file) and refresh area indexes.
Step 3: Run the conflict detection gate and produce commit-ready summaries with traceable refs.

Best Practices

Preserve 4-digit spaced numbering (0110, 0120, ...)
Keep one behavior per story file
Include these sections in each story: User Story, Key Fields/Parameters, Acceptance Criteria, Evidence, Linked Tickets
Always run the conflict detection gate before merging
Create changelog-ready content and traceable refs for commits

Example Use Cases

Add a new story for a single-behavior login flow and link it to related tickets
Break a vague 'user profile' requirement into separate search, edit, and view behaviors
Repair a broken link between a requirement and its linked ticket
Run check_requirements_conflicts.py --root <requirements-root> to surface overlaps
Generate and apply a changelog snippet using extract_requirements_changelog.py for HEAD

Frequently Asked Questions

Add this skill to your agents