Initial commit
This commit is contained in:
Zhongwei Li
228
commands/add-verification.md
Normal file
228
commands/add-verification.md
Normal file
@@ -0,0 +1,228 @@
|
||||
---
|
||||
allowed-tools: Read, Edit, Bash(reqvire:*)
|
||||
argument-hint: [requirement-id]
|
||||
description: Add a verification for an existing requirement, checking if verification is needed based on requirement hierarchy
|
||||
model: claude-sonnet-4-5-20250929
|
||||
---
|
||||
|
||||
# Add Verification
|
||||
|
||||
Add a verification for an existing requirement following Reqvire's bottom roll-up verification philosophy.
|
||||
|
||||
## Current Model Context
|
||||
|
||||
- Total verifications: !`reqvire search --json | jq -r '.global_counters.verifications'`
|
||||
- Verification coverage: !`reqvire coverage --json | jq -r '.summary.leaf_requirements_coverage_percentage'`%
|
||||
- Unverified leaf requirements: !`reqvire coverage --json | jq -r '.summary.unverified_leaf_requirements'`
|
||||
|
||||
## User Request
|
||||
|
||||
${1:+Requirement ID: $1}
|
||||
${1:-The user will specify which requirement needs verification.}
|
||||
|
||||
## Steps
|
||||
|
||||
1. **Identify the requirement:**
|
||||
- Ask user which requirement needs verification if not provided
|
||||
- Get the requirement identifier or name
|
||||
|
||||
2. **Check if verification is needed:**
|
||||
```bash
|
||||
reqvire traces --filter-name="<requirement-name>"
|
||||
```
|
||||
|
||||
Analyze the trace tree:
|
||||
- **Leaf requirement** (no children): Needs direct verification
|
||||
- **Parent requirement** (has children): Verification rolls up from children - usually no direct verification needed
|
||||
|
||||
3. **Check current coverage:**
|
||||
```bash
|
||||
reqvire coverage --filter-name="<requirement-name>"
|
||||
```
|
||||
|
||||
4. **If leaf requirement needs verification:**
|
||||
|
||||
Choose verification type:
|
||||
- **verification** (or test-verification): Automated testing
|
||||
- **analysis-verification**: Mathematical/computational analysis
|
||||
- **inspection-verification**: Manual inspection/review
|
||||
- **demonstration-verification**: Operational demonstration
|
||||
|
||||
5. **Read all requirements in trace chain:**
|
||||
|
||||
For each requirement this verification will verify:
|
||||
```bash
|
||||
reqvire search --filter-id="<requirement-id>"
|
||||
```
|
||||
|
||||
Extract:
|
||||
- Requirement content (capabilities and constraints)
|
||||
- All requirements in derivedFrom chain up to root
|
||||
- Build complete understanding of what needs verification
|
||||
|
||||
6. **Draft verification content:**
|
||||
|
||||
Template for verification:
|
||||
```markdown
|
||||
### Verification Name
|
||||
|
||||
[Description of how ALL requirements in the trace chain will be verified]
|
||||
|
||||
#### Details
|
||||
|
||||
##### Acceptance Criteria
|
||||
- [Criterion for leaf requirement 1]
|
||||
- [Criterion for leaf requirement 2]
|
||||
- [Criterion that verifies parent capabilities through leaf tests]
|
||||
|
||||
##### Test Criteria
|
||||
- [How to test criterion 1]
|
||||
- [How to test criterion 2]
|
||||
- [Expected outcomes]
|
||||
|
||||
#### Metadata
|
||||
* type: test-verification
|
||||
|
||||
#### Relations
|
||||
* verify: [Leaf Requirement 1](../path/to/req1.md#leaf-requirement-1)
|
||||
* verify: [Leaf Requirement 2](../path/to/req2.md#leaf-requirement-2)
|
||||
* satisfiedBy: [test.sh](../../tests/test-name/test.sh)
|
||||
```
|
||||
|
||||
Note: Only test-verification type can have satisfiedBy relations to test files.
|
||||
|
||||
7. **Add verification using reqvire add command:**
|
||||
|
||||
```bash
|
||||
reqvire add "requirements/Verifications/<file>.md" <<'EOF'
|
||||
### Verification Name
|
||||
|
||||
[Description of verification approach]
|
||||
|
||||
#### Details
|
||||
|
||||
##### Acceptance Criteria
|
||||
- [What must be satisfied]
|
||||
- [Functional criteria]
|
||||
|
||||
##### Test Criteria
|
||||
- [How to verify]
|
||||
- [Expected behavior]
|
||||
|
||||
#### Metadata
|
||||
* type: test-verification
|
||||
|
||||
#### Relations
|
||||
* verify: [Requirement](../path.md#requirement)
|
||||
EOF
|
||||
```
|
||||
|
||||
Optional: Insert at specific position (0-based index):
|
||||
```bash
|
||||
reqvire add "requirements/Verifications/<file>.md" 0 <<'EOF'
|
||||
...
|
||||
EOF
|
||||
```
|
||||
|
||||
Alternative using pipe:
|
||||
```bash
|
||||
cat element.md | reqvire add "requirements/Verifications/<file>.md"
|
||||
```
|
||||
|
||||
The add command automatically:
|
||||
- Validates markdown format
|
||||
- Checks element name uniqueness
|
||||
- Validates relation format
|
||||
- Updates the file
|
||||
|
||||
8. **Update the requirements with verifiedBy relations:**
|
||||
Add `verifiedBy` relation to each verified requirement:
|
||||
```markdown
|
||||
#### Relations
|
||||
* derivedFrom: [Parent](...)
|
||||
* verifiedBy: [Verification Name](../Verifications/file.md#verification-name)
|
||||
```
|
||||
|
||||
9. **Check updated coverage:**
|
||||
```bash
|
||||
reqvire coverage --filter-name="<requirement-name>"
|
||||
```
|
||||
|
||||
10. **Verify roll-up and check for redundancies:**
|
||||
```bash
|
||||
reqvire traces --filter-name="<verification-name>"
|
||||
reqvire lint --json > /tmp/lint.json
|
||||
```
|
||||
|
||||
Check if verification creates redundant verify relations (verifying both leaf and parent).
|
||||
|
||||
## Element Manipulation
|
||||
|
||||
After adding verifications, you may need to reorganize:
|
||||
|
||||
**Move verification to different file:**
|
||||
```bash
|
||||
reqvire mv "<verification-name>" "requirements/Verifications/<file>.md"
|
||||
```
|
||||
|
||||
**Move verification with specific position (0-based index):**
|
||||
```bash
|
||||
reqvire mv "<verification-name>" "<target-file>" 0
|
||||
```
|
||||
|
||||
**Remove verification:**
|
||||
```bash
|
||||
reqvire rm "<verification-name>"
|
||||
```
|
||||
|
||||
## Decision Logic
|
||||
|
||||
**If parent requirement with children:**
|
||||
- Explain verification rolls up from children
|
||||
- Show trace tree demonstrating coverage
|
||||
- Usually no direct verification needed
|
||||
|
||||
**If leaf requirement without verification:**
|
||||
- Read ALL requirements in trace chain
|
||||
- Create verification with test criteria covering entire chain
|
||||
- Link to requirement(s)
|
||||
- Add test linkage ONLY if type is test-verification AND test exists
|
||||
|
||||
**If existing verification needs update:**
|
||||
- Read all requirements currently verified
|
||||
- Read all requirements in their trace chains
|
||||
- Update test criteria to cover all requirements comprehensively
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Read trace chain**: Always read full requirement hierarchy to understand scope
|
||||
- **Comprehensive criteria**: Test criteria must cover all verified requirements
|
||||
- **Verify leaf requirements**: Focus on leaf-level verification
|
||||
- **Roll-up coverage**: Parent requirements inherit from children
|
||||
- **Avoid redundancy**: Don't verify both leaf and parent directly
|
||||
- **Use traces**: Run `reqvire traces` to understand verification structure
|
||||
- **Test links for test-verification only**: Only test-verifications link to test files
|
||||
|
||||
## Verification Types
|
||||
|
||||
- **test-verification**: Links to automated test files via satisfiedBy
|
||||
- **analysis-verification**: No test linkage, verified through analysis
|
||||
- **inspection-verification**: No test linkage, verified through manual inspection
|
||||
- **demonstration-verification**: No test linkage, verified through demonstration
|
||||
|
||||
## Verification Philosophy
|
||||
|
||||
Reqvire uses **bottom roll-up verification**:
|
||||
1. Verify leaf requirements directly
|
||||
2. Parent requirements inherit coverage from children
|
||||
3. One verification can verify multiple leaf requirements
|
||||
4. Verification traces automatically propagate upward
|
||||
5. Test criteria must cover ALL requirements in the trace chain
|
||||
|
||||
## Notes
|
||||
|
||||
- Verifications go in `requirements/Verifications/` directory
|
||||
- Use two-space indentation for Relations entries
|
||||
- Always read full trace chain before writing test criteria
|
||||
- Run `reqvire lint --fix` after adding to remove redundancies
|
||||
- Check `reqvire coverage` to confirm improvement
|
||||
Reference in New Issue
Block a user