Initial commit
This commit is contained in:
Zhongwei Li
334
commands/consolidate.md
Normal file
334
commands/consolidate.md
Normal file
@@ -0,0 +1,334 @@
|
||||
---
|
||||
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`
|
||||
Reference in New Issue
Block a user