Coverage Report

You are computing and reporting code coverage for the active track or a specific module. This complements the TDD workflow — TDD is the process (write test, implement, refactor), coverage is the measurement (how much code do those tests exercise).

Red Flags - STOP if you're:

• •Reporting coverage without actually running the coverage tool
• •Making up coverage percentages
• •Skipping uncovered line analysis
• •Not presenting the report for developer approval
• •Treating this as a replacement for TDD (it's not — TDD stays in /draft:implement)

Step 1: Load Context

1. •Read draft/tech-stack.md for test framework and language info
2. •Find active track from draft/tracks.md
3. •If track has architecture.md, identify current module for scoping
4. •Read draft/workflow.md for coverage target (default: 95%)

If no active track and no argument provided:

• •Tell user: "No active track. Provide a path or track ID, or run /draft:new-track first."

Step 2: Detect Coverage Tool

Auto-detect from tech stack:

Detection order:

1. •Check tech-stack.md for explicit testing section
2. •Check config files (jest.config.*, vitest.config.*, pytest.ini, setup.cfg, pyproject.toml, .nycrc)
3. •Check package.json scripts for coverage commands
4. •If not detectable, ask the developer which tool and command to use

Step 3: Determine Scope

Priority order:

1. •If argument provided (path or module name): use as scope filter
2. •If track has architecture.md with an in-progress module: scope to that module's files
3. •If active track exists: scope to files changed in the track (use git diff against base branch)
4. •Fallback: run coverage for entire project

Build the coverage command with the appropriate scope/filter flags.

Step 4: Run Coverage

1. •Execute the coverage command
2. •Capture full output
3. •If command fails:
   • •Check if dependencies are installed (test framework, coverage plugin)
   • •Suggest installation command
   • •Ask developer to fix and retry

Step 5: Parse and Present Report

Parse coverage output and present in a standardized format:

═══════════════════════════════════════════════════════════
                     COVERAGE REPORT
═══════════════════════════════════════════════════════════
Track: [track-id]
Module: [module name, if applicable]
Target: [from workflow.md, default 95%]

SUMMARY
─────────────────────────────────────────────────────────
Overall: 87.3% (target: 95%)  ← BELOW TARGET

PER-FILE BREAKDOWN
─────────────────────────────────────────────────────────
src/auth/middleware.ts    96.2%  PASS
src/auth/jwt.ts           72.1%  FAIL
src/auth/types.ts        100.0%  PASS

UNCOVERED LINES
─────────────────────────────────────────────────────────
src/auth/jwt.ts:45-52    Error handler for malformed token
src/auth/jwt.ts:78       Defensive null check (unreachable via public API)

═══════════════════════════════════════════════════════════

Step 6: Analyze Gaps

For files below target:

1. •Identify uncovered lines - List specific line ranges and what they contain
2. •Classify each gap:
   • •Testable - Can and should be covered. Suggest specific test to write.
   • •Defensive - Assertions, error handlers for impossible states. Acceptable to leave uncovered.
   • •Infrastructure - Framework boilerplate, main entry points. Usually acceptable.
3. •Suggest tests for testable gaps:
   code

   SUGGESTED TESTS
   ─────────────────────────────────────────────────────────
   1. Test malformed JWT token handling (jwt.ts:45-52)
      - Input: token with invalid signature
      - Expected: throws AuthError with code INVALID_TOKEN
   
   2. Test expired token rejection (jwt.ts:60-65)
      - Input: token with exp in the past
      - Expected: throws AuthError with code TOKEN_EXPIRED
   

Step 7: Developer Review

CHECKPOINT (MANDATORY)

STOP. Present the full coverage report and gap analysis.

Ask developer:

• •Accept current coverage? (if at or above target)
• •Write additional tests for testable gaps?
• •Justify and document acceptable uncovered lines?
• •Adjust coverage target for this track?

Wait for developer approval before recording results.

Step 8: Record Results

After developer approves:

1. •

   Update plan.md - Add coverage note to the relevant phase:

   markdown

   **Coverage:** 96.2% (target: 95%) - PASS
   - Uncovered: defensive null checks in jwt.ts (justified)
   

2. •

   Update architecture.md (if exists) - Add coverage to module status:

   markdown

   - **Status:** [x] Complete (Coverage: 96.2%)
   

3. •

   Update metadata.json - Add coverage field if not present:

   json

   {
     "coverage": {
       "overall": 96.2,
       "target": 95,
       "timestamp": "2025-01-15T10:30:00Z"
     }
   }
   

Completion

Announce:

Coverage report complete.

Overall: [percentage]% (target: [target]%)
Status: [PASS / BELOW TARGET]
Files analyzed: [count]
Gaps documented: [count testable] testable, [count justified] justified

Results recorded in:
- plan.md (phase notes)
- architecture.md (module status) [if applicable]
- metadata.json (coverage data)

Re-running Coverage

When coverage is run again on the same track/module:

1. •Compare with previous results
2. •Show delta: "Coverage improved from 87.3% to 96.2% (+8.9%)"
3. •Highlight newly covered lines
4. •Update all records with latest results