check-requirement-coverage

name	check-requirement-coverage
description	Homeostatic sensor detecting requirements without implementation or test coverage. Scans for REQ-* keys in requirements docs and checks if they have corresponding code and tests. Use to find coverage gaps.
allowed-tools	["Read","Grep","Glob"]

check-requirement-coverage

Skill Type: Sensor (Homeostasis) Purpose: Detect requirements without implementation or test coverage Prerequisites: Requirements exist in documentation

---

Agent Instructions

You are a Sensor in the homeostasis system. Your job is to detect deviations from the desired state.

Desired State: coverage = 100% (all requirements have code + tests)

Your goal is to find requirements without coverage and signal the deviation.

---

Workflow

Step 1: Find All Requirements

Search for REQ- keys* in requirements documentation:

# Find all requirement files
find docs/requirements -name "*.md" -type f

# Extract all REQ-* keys
grep -rho "REQ-[A-Z-]*-[0-9]*" docs/requirements/ | sort -u

Example output:

<REQ-ID>
<REQ-ID>
REQ-F-AUTH-003
<REQ-ID>
REQ-NFR-PERF-001
REQ-NFR-SEC-001
REQ-DATA-PII-001

---

Step 2: Check Implementation Coverage

For each REQ-*, search for implementation:

# Check if requirement has code implementation
grep -rn "# Implements: <REQ-ID>" src/

# Expected: At least 1 file with "# Implements: <REQ-ID>"

Coverage criteria:

• ✅ Covered: At least 1 file in src/ has # Implements: {REQ-KEY}
• ❌ Not covered: Zero files reference the requirement

Example:

<REQ-ID>:
  ✅ src/auth/login.py:23  # Implements: <REQ-ID>
  ✅ src/auth/validators.py:67  # Implements: <REQ-ID>, BR-001
  Result: COVERED (2 files)

REQ-F-PROFILE-001:
  ❌ No files found
  Result: NOT COVERED (implementation missing)

---

Step 3: Check Test Coverage

For each REQ-*, search for tests:

# Check if requirement has tests
grep -rn "# Validates: <REQ-ID>" tests/

# Also check BDD scenarios
grep -rn "# Validates: <REQ-ID>" features/

# Expected: At least 1 test file

Coverage criteria:

• ✅ Covered: At least 1 file in tests/ or features/ has # Validates: {REQ-KEY}
• ❌ Not covered: Zero test files reference the requirement

Example:

<REQ-ID>:
  ✅ tests/auth/test_login.py:15  # Validates: <REQ-ID>
  ✅ features/authentication.feature:8  # Validates: <REQ-ID>
  Result: COVERED (2 test files)

<REQ-ID>:
  ✅ src/payments/payment.py:45  # Implements: <REQ-ID>
  ❌ No test files found
  Result: COVERED (code) but NOT COVERED (tests) ⚠️

---

Step 4: Calculate Coverage Percentage

Formula:

implementation_coverage = (requirements_with_code / total_requirements) * 100
test_coverage = (requirements_with_tests / total_requirements) * 100
full_coverage = (requirements_with_both / total_requirements) * 100

Example:

Total Requirements: 42

Requirements with Code: 36/42 (86%)
Requirements with Tests: 32/42 (76%)
Requirements with Both: 30/42 (71%)

Coverage Status:
  ✅ Implementation: 86% (target: 80%) PASS
  ⚠️ Test: 76% (target: 80%) FAIL
  ⚠️ Full: 71% (target: 80%) FAIL

---

Step 5: Identify Coverage Gaps

Report requirements without coverage:

Gap Type 1: No Implementation:

Requirements Without Code (6):
├─ REQ-F-PROFILE-001 - User profile editing
├─ REQ-F-PROFILE-002 - Avatar upload
├─ REQ-F-NOTIF-001 - Email notifications
├─ REQ-F-NOTIF-002 - Push notifications
├─ REQ-NFR-PERF-002 - Database optimization
└─ REQ-DATA-LIN-001 - Data lineage tracking

Recommended Action: Implement these requirements using TDD workflow

Gap Type 2: Has Code, No Tests:

Requirements Without Tests (10):
├─ <REQ-ID> - Payment processing
│   Code: src/payments/payment.py:45
│   Missing: Unit tests
│
├─ REQ-F-CART-001 - Shopping cart
│   Code: src/cart/cart.py:23
│   Missing: Integration tests
│
└─ ... (8 more)

Recommended Action: Invoke 'generate-missing-tests' skill

Gap Type 3: Has Tests, No Code:

Requirements Without Implementation (4):
├─ REQ-F-SEARCH-001 - Product search
│   Tests: tests/search/test_search.py:15
│   Missing: Implementation (tests written first - RED phase)
│
└─ ... (3 more)

Status: ✅ This is OK (RED phase of TDD)
Action: Continue to GREEN phase

---

Output Format

When you detect coverage gaps:

[COVERAGE SENSOR - DEVIATION DETECTED]

Requirements Scanned: 42

Coverage Summary:
  Implementation: 36/42 (86%) ✅ PASS (≥80%)
  Tests: 32/42 (76%) ❌ FAIL (target: ≥80%)
  Full Coverage: 30/42 (71%) ❌ FAIL (target: ≥80%)

Homeostasis Deviation: Test coverage below 80%

Coverage Gaps by Type:

❌ No Implementation (6 requirements):
  1. REQ-F-PROFILE-001 - User profile editing
  2. REQ-F-PROFILE-002 - Avatar upload
  3. REQ-F-NOTIF-001 - Email notifications
  4. REQ-F-NOTIF-002 - Push notifications
  5. REQ-NFR-PERF-002 - Database optimization
  6. REQ-DATA-LIN-001 - Data lineage tracking

⚠️ No Tests (10 requirements):
  1. <REQ-ID> - Payment processing
     Code: src/payments/payment.py:45
  2. REQ-F-CART-001 - Shopping cart
     Code: src/cart/cart.py:23
  ... (8 more)

✅ Tests Without Implementation (4 requirements):
  1. REQ-F-SEARCH-001 - Product search
     Tests: tests/search/test_search.py:15
     Status: RED phase (OK - TDD in progress)
  ... (3 more)

Recommended Actions:
1. Invoke 'generate-missing-tests' skill for 10 requirements without tests
2. Implement 6 requirements without code (use 'tdd-workflow')
3. Continue TDD for 4 requirements in RED phase

Homeostasis Goal: coverage >= 80%
Current State: coverage = 71%
Deviation: -9% (needs correction)

---

Homeostasis Behavior

When deviation detected:

1. Report: Coverage below threshold
2. Signal: "Need tests for {REQ-KEYS}"
3. Recommend: Invoke generate-missing-tests actuator skill
4. Wait: User confirmation or auto-invoke if configured

When homeostasis achieved:

[COVERAGE SENSOR - HOMEOSTASIS ACHIEVED]

Requirements: 42
Coverage: 100% (42/42) ✅

All requirements have:
  ✅ Implementation
  ✅ Tests
  ✅ Traceability

Homeostasis Status: STABLE ✓

---

Prerequisites Check

None - this sensor can run anytime.

Recommended frequency:

• After each feature implementation
• Before commits (via pre-commit hook)
• Daily in CI/CD pipeline
• On-demand via /coverage-req slash command

---

Configuration

This skill respects configuration in .claude/plugins.yml:

plugins:
  - name: "@aisdlc/aisdlc-core"
    config:
      coverage:
        minimum_percentage: 80        # Fail if coverage < 80%
        require_implementation: true  # All REQ-* must have code
        require_tests: true           # All REQ-* must have tests
        auto_generate_missing: false  # Ask before generating tests
        exclude_patterns:
          - "REQ-DATA-*"              # Don't require tests for data reqs

---

Integration with Other Skills

TDD Workflow Integration

# Before starting TDD, check coverage
result = invoke_skill("check-requirement-coverage")

if result.has_gaps:
    # Report gaps to user
    print(f"Found {result.gap_count} requirements without coverage")

# After TDD, re-check coverage
result = invoke_skill("check-requirement-coverage")
if result.coverage >= 80:
    print("Coverage target achieved ✅")

Generate Missing Tests Integration

# Sensor detects gaps
gaps = invoke_skill("check-requirement-coverage")

if gaps.test_coverage < 80:
    # Actuator fixes gaps
    invoke_skill("generate-missing-tests", req_keys=gaps.missing_tests)

    # Re-check (should now be at homeostasis)
    new_gaps = invoke_skill("check-requirement-coverage")
    assert new_gaps.test_coverage >= 80  # Homeostasis achieved

---

Next Steps

After coverage check:

1. If gaps found → Recommend actuator skills (generate-missing-tests, tdd-workflow)
2. If homeostasis → Report success
3. If configured → Auto-invoke actuator skills

---

Notes

Why coverage detection?

• Prevents forgotten requirements: Ensures every REQ-* gets implemented
• Quality gate: Don't deploy without full coverage
• Continuous monitoring: Coverage can degrade over time
• Homeostasis principle: System self-corrects when coverage drops

Sensor characteristics:

• Read-only: Never modifies files (only reads)
• Fast: Lightweight grep operations
• Continuous: Can run frequently without impact
• Objective: Binary decision (covered or not)

Homeostasis Goal:

desired_state:
  implementation_coverage: >= 80%
  test_coverage: >= 80%
  full_coverage: >= 80%

"Excellence or nothing" 🔥