335 lines
10 KiB
Markdown
335 lines
10 KiB
Markdown
---
|
|
allowed-tools: Read, Edit, Bash(reqvire:*)
|
|
description: Consolidate refinement-only child requirements into their parent requirements' Details sections to improve model organization
|
|
model: claude-sonnet-4-5-20250929
|
|
---
|
|
|
|
# Consolidate Requirements Model
|
|
|
|
Consolidate child requirements that only refine their parents (without introducing new capabilities) into the parent requirement's Details section. This improves model readability by merging implementation-level details into their conceptual parents while maintaining full traceability.
|
|
|
|
## When to Use
|
|
|
|
Use this command when:
|
|
- Model has grown with many small refinement requirements
|
|
- Child requirements only elaborate on implementation details of parents
|
|
- You want to reduce model clutter while preserving all information
|
|
- Requirements are split via derivedFrom relations but don't add new capabilities
|
|
|
|
## Consolidation Heuristics
|
|
|
|
A child requirement is a candidate for consolidation if it meets **multiple** of these criteria:
|
|
|
|
1. **Very similar names to parent** - e.g., parent: "HTML Export", child: "HTML Export Verification" or "Export Related System Elements"
|
|
2. **Short content** - Less than 200 words of requirement text (excluding relations)
|
|
3. **No verifications** - Has no verifiedBy relations of its own
|
|
4. **Implementation-level details** - Mentions specific technical details, file formats, parameters, or procedural steps
|
|
5. **Leaf requirement** - No children of its own, derives from only one parent
|
|
6. **Procedural/step-by-step details** - Contains "how-to" information that expands on parent
|
|
7. **Refinement keywords** - Contains phrases like "shall support", "shall provide", "shall include", "formatting", "structure", "output", "options", "flags"
|
|
|
|
## Process Overview
|
|
|
|
The consolidation follows this systematic approach:
|
|
|
|
1. **Identify Candidates**: Find parent-child pairs where child is refinement-only
|
|
2. **Merge Content**: Move child requirement content into parent's Details section
|
|
3. **Move Relations**: Transfer all child relations (satisfiedBy, verifiedBy, etc.) to parent
|
|
4. **Remove Child**: Delete the child requirement element entirely
|
|
5. **Update References**: Find and update all references to child to point to parent
|
|
6. **Validate**: Ensure no broken relations after consolidation
|
|
|
|
## Steps
|
|
|
|
### 1. Analyze Model for Candidates
|
|
|
|
First, analyze the model to identify consolidation candidates:
|
|
|
|
```bash
|
|
# Remove diagrams to save tokens
|
|
reqvire remove-diagrams
|
|
|
|
# Get model structure
|
|
reqvire search --short --json > /tmp/search.json
|
|
```
|
|
|
|
Review the model structure and identify parent-child requirement pairs based on:
|
|
- derivedFrom relationships
|
|
- Requirement naming patterns
|
|
- Content length and complexity
|
|
- Presence of verifications
|
|
|
|
### 2. Review and Prioritize Candidates
|
|
|
|
For each candidate family, document:
|
|
- **Parent requirement**: File location, section, heading
|
|
- **Child requirements**: List of elements to consolidate
|
|
- **Justification**: Which heuristics apply (similar names, short content, etc.)
|
|
- **Relations to move**: All satisfiedBy, verifiedBy, trace relations from children
|
|
- **References to update**: Other elements that reference the children
|
|
|
|
Prioritize by:
|
|
- **High priority**: Clear refinement patterns, minimal relations, obvious implementation details
|
|
- **Medium priority**: Mixed signals, moderate impact
|
|
- **Low priority**: Substantial content, many verifications, borderline cases
|
|
|
|
### 3. Execute Consolidation (Per Requirement Family)
|
|
|
|
For each requirement family to consolidate:
|
|
|
|
#### 3.1 Read Parent and Children
|
|
|
|
```bash
|
|
# Read the parent requirement file
|
|
Read requirements/path/to/ParentFile.md
|
|
|
|
# Read sections containing children if in different files
|
|
Read requirements/path/to/ChildFile.md
|
|
```
|
|
|
|
#### 3.2 Create Enhanced Parent Details
|
|
|
|
Edit the parent requirement to add consolidated content from children:
|
|
|
|
**Structure for consolidated Details section:**
|
|
```markdown
|
|
#### Details
|
|
|
|
[Existing parent details content]
|
|
|
|
**[Child 1 Heading]:**
|
|
[Child 1 description and key details]
|
|
|
|
[Child 1 specific details as subsections or bullets]
|
|
|
|
**[Child 2 Heading]:**
|
|
[Child 2 description and key details]
|
|
|
|
[Child 2 specific details as subsections or bullets]
|
|
```
|
|
|
|
**Example:**
|
|
```markdown
|
|
#### Details
|
|
|
|
The system shall provide formatting capability...
|
|
|
|
**Excess Whitespace:**
|
|
- Detect and fix excess whitespace after element headers
|
|
- Maintain consistent formatting across all requirements documents
|
|
|
|
**Inconsistent Newlines:**
|
|
- Detect and fix excess or missing newlines before element headers
|
|
- Normalize to exactly two newlines before subsections
|
|
```
|
|
|
|
#### 3.3 Merge Relations to Parent
|
|
|
|
Add all relations from children to the parent's Relations section:
|
|
|
|
```markdown
|
|
#### Relations
|
|
* derivedFrom: [Existing Parent Relations]
|
|
* satisfiedBy: [parent-file.rs]
|
|
* satisfiedBy: [child1-file.rs] # Moved from Child 1
|
|
* satisfiedBy: [child2-file.rs] # Moved from Child 2
|
|
* verifiedBy: [Parent Verification]
|
|
* verifiedBy: [Child Verification] # Moved from Child 1
|
|
```
|
|
|
|
#### 3.4 Remove Child Requirements
|
|
|
|
Delete each child requirement entirely (full H3 section including heading, content, metadata, relations, separator):
|
|
|
|
```markdown
|
|
### Child Requirement Name
|
|
|
|
[DELETE THIS ENTIRE SECTION]
|
|
|
|
---
|
|
```
|
|
|
|
#### 3.5 Update References to Children
|
|
|
|
Search for any elements that reference the removed children:
|
|
|
|
```bash
|
|
# Search for references to the child
|
|
reqvire search --filter-name="Child.*Name" --json
|
|
```
|
|
|
|
For each reference found, update it to point to the parent:
|
|
|
|
**Before:**
|
|
```markdown
|
|
* verifiedBy: [Child Requirement](File.md#child-requirement)
|
|
```
|
|
|
|
**After:**
|
|
```markdown
|
|
* verifiedBy: [Parent Requirement](File.md#parent-requirement)
|
|
```
|
|
|
|
#### 3.6 Validate After Each Family
|
|
|
|
```bash
|
|
# Validate model after consolidating each family
|
|
reqvire validate
|
|
|
|
# If validation passes, continue to next family
|
|
# If validation fails, fix broken references before continuing
|
|
```
|
|
|
|
### 4. Final Validation and Formatting
|
|
|
|
After all consolidations:
|
|
|
|
```bash
|
|
# Validate entire model
|
|
reqvire validate
|
|
|
|
# Format all files
|
|
reqvire format --fix
|
|
|
|
# Regenerate diagrams
|
|
reqvire generate-diagrams
|
|
|
|
# Final validation
|
|
reqvire validate
|
|
```
|
|
|
|
## Consolidation Examples
|
|
|
|
### Example 1: Format Implementation Family
|
|
|
|
**Before Consolidation:**
|
|
```markdown
|
|
### Format Consistency Enforcement
|
|
The system shall provide formatting capability...
|
|
#### Relations
|
|
* derivedFrom: [Model Formatting]
|
|
|
|
---
|
|
|
|
### Excess Whitespace Format Implementation
|
|
Detect and fix excess whitespace...
|
|
#### Relations
|
|
* derivedFrom: [Format Consistency Enforcement]
|
|
* satisfiedBy: [format.rs]
|
|
|
|
---
|
|
|
|
### Missing Separators Format Implementation
|
|
Detect consecutive element sections...
|
|
#### Relations
|
|
* derivedFrom: [Format Consistency Enforcement]
|
|
* satisfiedBy: [format.rs]
|
|
```
|
|
|
|
**After Consolidation:**
|
|
```markdown
|
|
### Format Consistency Enforcement
|
|
The system shall provide formatting capability...
|
|
|
|
#### Details
|
|
**Excess Whitespace:**
|
|
- Detect and fix excess whitespace after element headers
|
|
- Maintain consistent formatting
|
|
|
|
**Missing Separators:**
|
|
- Detect consecutive element sections that lack separators
|
|
- Insert separators to maintain consistent visual separation
|
|
|
|
#### Relations
|
|
* derivedFrom: [Model Formatting]
|
|
* satisfiedBy: [format.rs]
|
|
```
|
|
|
|
### Example 2: CLI Options Family
|
|
|
|
**Before:**
|
|
```markdown
|
|
### CLI Traces Command
|
|
The system shall implement traces subcommand...
|
|
#### Relations
|
|
* derivedFrom: [Verification Trace Builder]
|
|
|
|
---
|
|
|
|
### CLI Traces Filter Options
|
|
Support filtering verification traces...
|
|
#### Relations
|
|
* derivedFrom: [CLI Traces Command]
|
|
|
|
---
|
|
|
|
### CLI Traces From-Folder Option
|
|
Support --from-folder option...
|
|
#### Relations
|
|
* derivedFrom: [CLI Traces Command]
|
|
```
|
|
|
|
**After:**
|
|
```markdown
|
|
### CLI Traces Command
|
|
The system shall implement traces subcommand...
|
|
|
|
#### Details
|
|
[Original command details]
|
|
|
|
**Filter Options:**
|
|
The system shall support filtering verification traces by:
|
|
- --filter-id=<id>: Filter by verification element ID
|
|
- --filter-name=<regex>: Filter by name pattern
|
|
- --filter-type=<type>: Filter by verification type
|
|
|
|
**From-Folder Option:**
|
|
Support --from-folder option that specifies relative path for portable links:
|
|
- Accept relative path parameter
|
|
- Adjust clickable links in diagrams to be relative
|
|
- Work with both Markdown and JSON output
|
|
|
|
#### Relations
|
|
* derivedFrom: [Verification Trace Builder]
|
|
* satisfiedBy: [cli.rs]
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
1. **Work incrementally**: Consolidate one requirement family at a time
|
|
2. **Validate frequently**: Run `reqvire validate` after each consolidation
|
|
3. **Preserve all information**: Don't lose any technical details during consolidation
|
|
4. **Maintain traceability**: Move ALL relations from children to parent
|
|
5. **Update references**: Search and fix all references to removed children
|
|
6. **Test thoroughly**: Ensure model validates and all links work after consolidation
|
|
7. **Document decisions**: Keep notes on which families were consolidated and why
|
|
|
|
## Anti-Patterns (When NOT to Consolidate)
|
|
|
|
Do NOT consolidate if:
|
|
- Child introduces **new functional capability** beyond parent
|
|
- Child has **extensive content** (>300 words) that would overwhelm parent Details
|
|
- Child has **many verifications** (3+) indicating significant independent functionality
|
|
- Child is referenced by **many other elements** as a key concept
|
|
- Child represents a **distinct abstraction level** (e.g., user requirement vs system requirement)
|
|
- There's **uncertainty** about whether child is truly refinement-only
|
|
|
|
## Expected Benefits
|
|
|
|
After consolidation, the model will have:
|
|
- **Reduced clutter**: Fewer top-level requirements to navigate
|
|
- **Better organization**: Implementation details nested under conceptual parents
|
|
- **Improved readability**: Related information grouped together
|
|
- **Maintained traceability**: All relations preserved through parent requirements
|
|
- **Cleaner structure**: Hierarchical organization matches conceptual dependencies
|
|
|
|
## Verification
|
|
|
|
After consolidation is complete, verify:
|
|
- ✅ Model validates with no errors: `reqvire validate`
|
|
- ✅ All relations are preserved (no missing targets)
|
|
- ✅ Verification coverage percentage unchanged or improved
|
|
- ✅ Test verifications still link correctly to requirements
|
|
- ✅ Diagrams generate without errors: `reqvire generate-diagrams`
|
|
- ✅ Documentation exports correctly: `reqvire export --html`
|