Requirements and Specifications Maintenance Skill

Systematic workflow for maintaining requirements and specification documents to ensure continued accuracy, traceability, and alignment with implementation.

CONTINUOUS IMPROVEMENT RULE

If you discover issues or improvements during execution, record them:

1. Activate skill:

   Skill: plan-marshall:manage-lessons

2. Record lesson with:
   • Component:

     {type: "skill", name: "cui-maintain-requirements", bundle: "pm-requirements"}

   • Category: bug | improvement | pattern | anti-pattern
   • Summary and detail of the finding

PARAMETERS

• scope - (Optional) Maintenance scope:

  • full

    - Complete requirements and specifications maintenance (default)

  • requirements

    - Focus on requirements documents only

  • specifications

    - Focus on specification documents only

  • references

    - Focus on cross-reference verification only
• scenario - (Optional) Specific maintenance scenario:

  • new-feature

    - Adding documentation for new functionality

  • deprecation

    - Handling deprecated or removed functionality

  • refactoring

    - Updating after code refactoring

CRITICAL CONSTRAINTS

Documentation Integrity

MUST:

• Document only existing or approved functionality
• Verify all code references resolve correctly
• Replace duplications with cross-references
• Maintain requirement ID stability (NEVER renumber)

MUST NOT:

• Document non-existent features (hallucinations)
• Copy content between documents
• Break cross-reference traceability
• Change requirement IDs

Deprecation Handling Protocol

Pre-1.0 projects:

• Update requirements directly
• Simply remove or update outdated content
• No deprecation markers needed

Post-1.0 projects - ASK USER:

• STOP and use AskUserQuestion tool
• Present options: Deprecate (mark but keep) or Remove (delete)
• Wait for user decision
• Apply chosen approach

Never remove post-1.0 requirements without user approval.

WORKFLOW

Step 0: Parameter Validation

• If

  scope

  specified: Use specified scope
• If NO

  scope

  : Default to full maintenance
• If

  scenario

  specified: Tailor workflow accordingly

Step 1: Load Requirements Standards

Skill: pm-requirements:requirements-maintenance
Skill: pm-requirements:requirements-documentation
Skill: pm-requirements:specification-documentation

This loads comprehensive requirements standards including:

• requirements-maintenance.md - Maintenance principles and integrity requirements
• requirements-documentation.md - Requirements creation patterns
• specification-documentation.md - Specification structure standards

On load failure: Report error and abort.

Step 2: Pre-Maintenance Discovery

2.1 Identify Documents:

Task:
  subagent_type: Explore
  model: sonnet
  description: Locate requirements and specification documents
  prompt: |
    Locate all requirements and specification documents in project.
    Search for:
    - Requirements.adoc (typically in doc/)
    - Specification documents (typically in doc/specifications/)
    - Related documentation files

    Return structured list with paths.

2.2 Load Maintenance Standards:

Verify standards loaded from skills, confirm understanding of:

• SMART requirements principles
• Integrity requirements (no hallucinations, no duplications, verified links)
• Deprecation handling rules (pre-1.0 vs post-1.0)
• Traceability requirements

Step 3: Requirements Analysis

[If scope = "requirements" OR scope = "full"]

3.1 Analyze Requirements State:

Task:
  subagent_type: Explore
  model: sonnet
  description: Identify requirements maintenance needs
  prompt: |
    Analyze requirements documents for issues.
    Apply detection criteria from pm-requirements:requirements-maintenance skill:
    - Missing/incomplete requirements
    - Outdated references
    - Broken cross-references
    - Inconsistent terminology
    - Duplicate information
    - Integrity violations (hallucinations, unverified references)

    Return structured analysis by category with severity.

3.2 Update Requirements:

Apply requirements updates following patterns from pm-requirements:requirements-documentation skill.

Apply maintenance rules from pm-requirements:requirements-maintenance skill:

• NEVER renumber requirement IDs
• Ensure SMART compliance
• Preserve rationale
• Update status indicators
• Maintain traceability

CRITICAL: Document only existing or approved functionality.

If scenario = "new-feature": Follow new-feature documentation pattern from requirements-documentation skill.

If scenario = "deprecation": Apply deprecation handling protocol (check version, ask user for post-1.0).

3.3 Verify Specification Alignment:

Verify requirements link to specifications correctly. Check:

• xref: links resolve
• Specifications exist
• Bidirectional traceability
• Implementation references valid

Step 4: Specification Maintenance

[If scope = "specifications" OR scope = "full"]

4.1 Analyze Specifications:

Analyze specification documents for issues:

• Alignment with requirements
• Accurate implementation references
• Complete behavioral descriptions
• Valid cross-references

4.2 Update Specifications:

Update specifications following patterns from pm-requirements:specification-documentation skill.

Apply maintenance rules:

• Maintain linkage to requirements
• Update implementation details
• Preserve specification IDs
• Keep examples current and valid

CRITICAL: Verify all code references exist.

If scenario = "refactoring": Update implementation references following refactoring patterns from requirements-maintenance skill.

Step 5: Cross-Reference Verification

[If scope = "references" OR scope = "full"]

5.1 Verify Document Links:

Verify all cross-references resolve correctly:

• xref: links point to existing sections
• Paths are current after restructuring
• Section IDs are correct
• No references to deleted documents

5.2 Validate Code References:

Validate all code references in documentation using Grep to verify:

• Referenced classes exist
• Method signatures correct
• Package names current
• Line numbers accurate (if specified)

CRITICAL: All code references must resolve to existing code.

Step 6: Integrity Verification

6.1 Check for Hallucinations:

For each requirement and specification:

1. Verify feature exists in code OR is in approved roadmap
2. Flag unverified documentation
3. If unverified content found: STOP, ASK USER, WAIT for decision

6.2 Eliminate Duplications:

Identify duplicate information across documents. For each duplication:

• Identify canonical location
• Replace duplicates with xref: links to canonical location

6.3 Final Link Verification:

Checklist:

• All xref: links resolve
• All code references verified
• All external links accessible
• No broken references remain

Step 7: Quality Verification

Run comprehensive quality checklist:

• Cross-References Validated (all links work)
• No Duplicate Information (cross-references used)
• Consistent Terminology (same terms for same concepts)
• Clear Traceability Maintained (complete requirement-to-implementation chain)
• No Hallucinated Functionality (all features verified)
• Integrity Maintained (documentation reflects reality)

If ANY check fails: Document failure, fix issue, re-run verification.

Step 8: Scenario-Specific Finalization

[If scenario parameter provided]

If scenario = "new-feature":

• Verify new requirements follow SMART principles
• Confirm specifications link to requirements
• Ensure traceability matrix updated

If scenario = "deprecation":

• Verify deprecation markers applied (if post-1.0 and user chose deprecate)
• OR confirm removals complete (if user chose remove)
• Check all references updated

If scenario = "refactoring":

• Verify all package/class name updates applied
• Confirm method signatures current
• Ensure examples compile with new structure

Step 9: Commit Changes

Review changes and create commit:

docs(requirements): [brief description of changes]

[Detailed description of maintenance performed]

- [Specific change 1]
- [Specific change 2]
- [Specific change 3]

Affected requirements: [list requirement IDs]
[Optional: Affected specifications: list spec IDs]
[Optional: Structural changes: describe]

Co-Authored-By: Claude <noreply@anthropic.com>

Step 10: Display Summary

Requirements Maintenance Summary

Scope: {scope parameter value}
Scenario: {scenario parameter value if provided}

Requirements Reviewed: {count}
Requirements Updated: {list of IDs}
New Requirements Added: {count if any}
Requirements Deprecated/Removed: {count if any}

Specifications Reviewed: {count}
Specifications Updated: {list}
Implementation References Corrected: {count}

Cross-References Fixed:
- Broken document links: {count}
- Broken code references: {count}
- New cross-references added: {count}

Integrity Checks:
- Hallucinations resolved: {count}
- Duplications removed: {count}
- Links verified: {total count}

Quality Verification: All checks passed
Commit Created: {commit hash}

ERROR HANDLING

Unverified Documentation Found:

1. Stop maintenance process
2. Document unverified content details
3. Ask user: "Is this documented feature planned or should it be removed?"
4. Wait for user decision
5. Proceed based on user choice

Broken Links Cannot Be Fixed:

1. Document broken link
2. Try to locate moved content
3. If found: Update link
4. If not found: Ask user for guidance
5. Remove link only with user approval

Conflicting Information:

1. Document both versions
2. Identify most authoritative source
3. Ask user which version is correct
4. Update to correct version
5. Replace duplicates with cross-references

USAGE EXAMPLES

# Complete maintenance
/cui-maintain-requirements scope=full

# Requirements only
/cui-maintain-requirements scope=requirements

# New feature documentation
/cui-maintain-requirements scope=full scenario=new-feature

# Handle deprecation (will ask user for post-1.0)
/cui-maintain-requirements scope=full scenario=deprecation

# After refactoring
/cui-maintain-requirements scope=specifications scenario=refactoring

Related

• pm-requirements:requirements-maintenance

  skill - Maintenance principles

• pm-requirements:requirements-documentation

  skill - Requirements patterns

• pm-requirements:specification-documentation

  skill - Specification patterns