cuioss Requirements and Specification Authoring Standards
Comprehensive standards for creating, structuring, and maintaining requirements and specification documents in CUI projects following SMART principles, ensuring complete traceability, and maintaining documentation integrity throughout the project lifecycle.
What This Skill Provides
This skill consolidates all standards for authoring requirements and specification documents:
- Requirements Format: SMART principles, ID schemes, numbering, and structure
- Specification Structure: Document organization, backtracking links, and traceability patterns
- Documentation Lifecycle: Pre-implementation, during implementation, and post-implementation practices
- Quality Standards: Clarity, completeness, consistency, and testability requirements
- Integrity Requirements: No hallucinations, no duplications, verified links
- Maintenance Standards: Adding, modifying, removing, and deprecating requirements
When to Activate
Use this skill when:
- Creating new requirements documents for projects
- Writing specification documents with proper structure
- Maintaining existing requirements and specifications
- Ensuring documentation integrity and quality
- Setting up traceability between requirements, specs, and code
- Handling requirement deprecation or removal
Workflow
1. Creating Requirements
When creating new requirements:
- Follow SMART principles (Specific, Measurable, Achievable, Relevant, Time-bound)
- Use consistent ID format:
[#PREFIX-NUM] - Structure with proper headings and bullet points
- Maintain sequential numbering (never reuse IDs)
- Link to specifications when created
2. Writing Specifications
When creating specifications:
- Create backtracking links to requirements:
_See Requirement link:../Requirements.adoc#REQ-ID[REQ-ID: Title]_ - Organize by component or functional area
- Use proper status indicators (PLANNED, IN PROGRESS, IMPLEMENTED)
- Link to implementation code when it exists
- Update as implementation progresses
3. Maintaining Documentation
When maintaining requirements/specifications:
- Verify no hallucinated functionality (all documented features must exist or be planned)
- Eliminate duplications (use cross-references instead)
- Verify all links are functional
- Update implementation status as code is written
- Handle deprecation appropriately (ask user for post-1.0 projects)
4. Ensuring Quality
Before finalizing documentation:
- Check all cross-references resolve correctly
- Verify consistent terminology throughout
- Ensure clear traceability from requirements to specs to code
- Validate SMART criteria for all requirements
- Confirm no duplicate information across documents
Standards Organization
Standards are organized into focused documents:
Core Authoring Standards
requirements-format-and-structure.md
- Requirement ID format and anchors
- Heading format and hierarchy
- Content organization patterns
- Bullet point structure
- Document header requirements
smart-requirements-principles.md
- SMART criteria definitions
- Specific requirements patterns
- Measurable criteria examples
- Achievable and relevant requirements
- Testability requirements
specification-structure-and-backtracking.md
- Specification document structure
- Main vs. individual specification files
- Backtracking link format and placement
- Multiple requirement references
- Path variations for cross-references
Lifecycle Management
documentation-lifecycle-management.md
- Pre-implementation specifications (detailed design, examples, expected API)
- During implementation updates (implementation links, decisions, notes)
- Post-implementation refinement (status updates, implementation links, removing redundancy)
- Transitioning between lifecycle phases
Quality and Integrity
integrity-and-quality-standards.md
- No hallucinations rule (verify all documented features)
- No duplications rule (use cross-references)
- Verified links requirement
- Consistency requirements
- Clarity and completeness standards
- Maintainability principles
maintenance-and-deprecation-handling.md
- Adding new requirements (numbering, format, linking)
- Modifying existing requirements (preserve IDs, update content)
- Removing requirements (never delete, deprecate instead)
- Pre-1.0 vs. post-1.0 deprecation handling
- Refactoring requirements (maintain IDs, update references)
Tool Access
This skill requires:
- Read - To review existing requirements and specifications
- Edit - To update existing documentation
- Write - To create new requirements and specification files
- Grep - To search for requirement IDs and verify consistency
- Glob - To find all requirements and specification files
Integration
This skill integrates with:
- pm-requirements:setup - Provides initial structure that authoring populates
- pm-requirements:planning - Planning tasks trace to requirements created here
- pm-requirements:traceability - Links authored specs to implementation code
- cui-documentation:cui-documentation - General AsciiDoc formatting standards
- pm-dev-java:javadoc - JavaDoc standards for referencing requirements
Anti-Patterns to Avoid
Over-specification in requirements:
- ❌ "The system must use a HashMap to store tokens"
- ✅ "The system must cache validated tokens for performance"
Vague requirements:
- ❌ "The system should be fast and secure"
- ✅ "Token validation must complete within 50ms for 95% of requests"
Implementation details in requirements:
- ❌ "The TokenValidator class must use jose4j library"
- ✅ "The system must validate JWT signatures according to RFC 7519"
Duplicating content across documents:
- ❌ Copying requirement text into specifications
- ✅ Using backtracking links to reference requirements
Hallucinated functionality:
- ❌ Documenting features that don't exist or aren't planned
- ✅ Verifying all documented features against code or approved plans
Quality Checklist
Before completing requirements/specification work:
- All requirements follow SMART principles
- All requirement IDs follow PREFIX-NUM format
- All specifications have backtracking links to requirements
- No hallucinated functionality documented
- No duplicate information across documents
- All cross-references verified and functional
- Consistent terminology throughout
- Clear traceability maintained
- Implementation status indicators current
- Documentation integrity validated
Related Standards
Within Bundle:
- setup - Initial structure creation
- planning - Task tracking linked to requirements
- traceability - Linking specs to implementation
External:
- cui-documentation:cui-documentation - AsciiDoc formatting
- pm-dev-java:javadoc - JavaDoc requirement references
- pm-workflow:git-workflow - Committing requirement changes