gh-reqvire-org-reqvire-reqvire-claude-plugin/commands/add-verification.md

---
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