coverage-review

name	coverage-review
description	Run code coverage analysis and review gaps for severity and test suggestions
argument-hint	[diff|full] [path] [instructions]

Coverage Review

Run code coverage tools, parse results, and launch a reviewer agent to assess which gaps matter and suggest test improvements. The output is a local report; walk and act on it with /decaf-quality:resolve-coverage-review.

Argument Parsing

Parse $ARGUMENTS to determine:

1. Mode: diff (default) or full
2. Path: Optional file/directory to restrict scope
3. Instructions: Any additional review instructions

Mode	Scope	Use Case
diff (default)	Changed/new code only (git diff HEAD)	PR review, incremental work
full	All project files	Baseline assessment, release readiness

Execution Steps

Step 1: Read Coverage Configuration

Look for a ## Coverage section in the project's CLAUDE.md. Expected format is documented in:

@../../conventions/coverage-config.md

If no ## Coverage section is found, inform the user with the setup template from the convention file and exit:

No coverage configuration found in CLAUDE.md.

Add a ## Coverage section to your project's CLAUDE.md. See conventions/coverage-config.md for format and examples.

Step 2: Determine Scope

• diff mode: Get changed files from git diff HEAD --name-only. These files are the review scope. If no uncommitted changes, fall back to git diff HEAD~1..HEAD --name-only.
• full mode: All project source files are in scope.
• If a specific path argument is provided, further restrict scope to that path.

If scope is empty (no changed files in diff mode), inform the user and exit.

Step 3: Run Coverage

Execute the configured coverage command via Bash. Wait for completion.

# Run the command from CLAUDE.md ## Coverage section
<configured command>

If the command fails (non-zero exit), show the error output and exit:

Coverage command failed (exit code N):
<stderr/stdout>

Check that the command in your CLAUDE.md ## Coverage section is correct.

Step 4: Parse Coverage Report

Find the report file(s) at the configured report path using Glob. Read and parse based on format:

Cobertura XML

Extract <package> -> <class> -> <line> elements. Per-file: line-rate, branch-rate, uncovered line numbers.

LCOV

Parse SF:, DA:, BRDA:, BRF:, BRH: records. Per-file: line hits, branch hits, uncovered lines.

Clover XML

Extract <file> -> <line> elements. Per-file: covered/uncovered statements and branches.

For diff mode: Filter parsed data to only include files from the changed file list (Step 2). Match by file path suffix since coverage tools may use absolute or project-relative paths.

Extract per-file:

• Line coverage % and uncovered line ranges
• Branch coverage % and uncovered branch locations
• Whether file is above/below configured thresholds

Step 5: Build Gap Context

For each file with coverage gaps (below threshold, or with significant uncovered ranges):

1. Read source code of uncovered line ranges (include ~5 lines of surrounding context)
2. Classify uncovered code broadly: error/exception paths, security-sensitive code (auth, crypto, input validation), business logic / state transitions, data validation / boundary checks, boilerplate / trivial code
3. Rank files by gap severity potential: error paths and security code > complex business logic > data validation > simple/trivial code

Cap at top ~15 files to keep agent context manageable. Summarize the rest as a table:

## Additional Files Below Threshold (not sent to reviewer)

| File | Line % | Branch % | Status |
|------|--------|----------|--------|
| ... | ... | ... | ... |

Step 6: Launch Coverage Reviewer Agent

Launch decaf-quality:coverage-reviewer via the Task tool with the following prompt structure:

Review these code coverage gaps for severity and suggest test improvements.

## Project Coverage Summary
- Overall line coverage: XX% (threshold: YY%) — STATUS
- Overall branch coverage: XX% (threshold: YY%) — STATUS
- Files analyzed: N total, M below threshold

## Coverage Gaps (by priority)

### File: `path/to/file.cs` — 45% line, 30% branch
**Uncovered lines 45-62:**
```<language>
<source code of uncovered lines with surrounding context>

Classification: Error handling for payment failures

...

Additional Instructions

<any user-provided instructions from $ARGUMENTS>

The agent returns a JSON array of findings (severity Critical/High/Medium/Low, a `COVERAGE_*` category, a confidence anchor, and a runnable test suggestion) plus a Test Improvement Plan appendix.

**For `full` mode with many gaps** (more than 8 files below threshold): Consider launching 2 `decaf-quality:coverage-reviewer` agents in parallel, splitting the file list roughly in half by priority rank. Merge the results.

### Step 6.5: Apply the Confidence Gate

The agent reports findings at anchor ≥ 50. Apply the same noise floor as `code-review` (the Confidence Gate in `code-review-consolidation.md`), simplified for a single agent — there is no dedup, agreement promotion, or deterministic-claim safety net here:

- **Suppress** findings below anchor **75**.
- **Critical exception:** Critical findings at anchor 50 survive the gate — mark them as anchor 50 in the report.
- Record the suppressed count (by anchor) in the report's **Considered But Not Flagged** section, so the drop is visible.

Then split the survivors: **pre-existing** gaps (`pre_existing: true` — uncovered code this change did not touch) route to the **Pre-existing Gaps** section (informational, excluded from the verdict); the rest are the primary Gap Findings.

### Step 7: Generate Report

Create a timestamped report file in `.decaf/code-reviews/` at the repo root. Never overwrite existing reviews.

```bash
mkdir -p .decaf/code-reviews
FILENAME=".decaf/code-reviews/COVERAGE_REVIEW_$(date '+%Y-%m-%d_%H-%M-%S').md"

Report format:

# Coverage Review

**Mode**: diff | **Date**: YYYY-MM-DD
**Scope**: N files analyzed, M below threshold
**Overall**: XX% line (threshold: YY%), XX% branch (threshold: YY%)

## Summary

| Metric | Value | Threshold | Status |
|--------|-------|-----------|--------|
| Line coverage | 72% | 80% | Below |
| Branch coverage | 65% | 70% | Below |
| Changed lines covered | 45/60 (75%) | — | — |

**Verdict**: NEEDS_COVERAGE | ADEQUATE

- **NEEDS_COVERAGE**: Any metric below configured thresholds
- **ADEQUATE**: All metrics at or above thresholds

---

## Gap Findings

### #1 🔴 Critical: Uncovered error handling in PaymentProcessor.cs

| | |
|---|---|
| **File** | `src/PaymentProcessor.cs:45-62` |
| **Coverage** | 0% (18 lines) |
| **Category** | COVERAGE_ERROR_PATH |
| **Confidence** | 92 |

**Why it matters:** <agent's severity assessment>

**Suggested tests:**
- <specific test case suggestions from agent>

---

### #2 🟠 High: ...
...

---

## Coverage by File

| File | Line % | Branch % | Status | Uncovered Lines |
|------|--------|----------|--------|-----------------|
| `src/PaymentProcessor.cs` | 45% | 30% | Below | 45-62, 78-85 |
| `src/UserAuth.cs` | 70% | 55% | Below | 23-30 |
| `src/Utils.cs` | 95% | 90% | OK | — |

---

## Pre-existing Gaps (informational — excluded from verdict)

Uncovered gaps in code this change did not touch; listed only when Critical/High.

| File | Coverage | Category | Confidence | Why it matters |
|------|----------|----------|------------|----------------|
| `src/LegacyExporter.cs:120-145` | 0% | COVERAGE_LOW_VALUE | 60 | Dead-code candidate, retained from v1 |

---

## Considered But Not Flagged

- Suppressed by the confidence gate: N findings below anchor 75 (e.g. 3 at anchor 50, 2 at anchor 25/0).
- Agent dismissals: <gaps the coverage-reviewer examined and ruled out, with one-line reasons>.

Use literal Unicode severity icons (🔴🟠🟡🟢), never :shortcode: syntax.

Output Notification

After creating the report file, inform the user:

Coverage review complete: .decaf/code-reviews/COVERAGE_REVIEW_2026-02-27_14-30-45.md

Walk the gaps and write tests with: /decaf-quality:resolve-coverage-review

Example Usage

/decaf-quality:coverage-review                          # diff mode, changed files
/decaf-quality:coverage-review full                     # Full project coverage
/decaf-quality:coverage-review diff src/Payments/       # diff mode, specific path
/decaf-quality:coverage-review full focus on error paths # Full mode with instructions