/skill-coverage-audit

name: skill-coverage-audit
description: "Trace codepaths in diffs, map against tests, auto-generate missing coverage — use before shipping PRs"
disable-model-invocation: true

> **Host: Codex CLI** — This skill was designed for Claude Code and adapted for Codex. > Cross-reference commands use installed skill names in Codex rather than `/octo:*` slash commands. > Use the active Codex shell and subagent tools. Do not claim a provider, model, or host subagent is available until the current session exposes it. > For host tool equivalents, see `skills/blocks/codex-host-adapter.md`.

Test Coverage Audit

Artifact consistency before implementation

When invoked at a spec/plan/tasks boundary, use the feature boundary adapter rather than this skill's code-test generation mode. It automatically runs bounded deterministic checks for coverage, declared paths, stable IDs, explicit terminology/enums/counts and verified policy references. A single artifact skips analysis; a clean pass costs no seat. Reports are advisory and quote the original sources. Escalation uses at most one independent seat, and unavailable or failed semantic review leaves the deterministic results usable.

Overview

Trace every codepath in a diff, map each path against existing tests, visualize coverage gaps, and auto-generate tests for uncovered paths.

**Core principle:** Trace codepaths in changed files -> Map against existing tests -> Score coverage quality -> Generate tests for gaps -> Report before/after counts.

Caps and Limits

These hard limits prevent runaway analysis:

• **30 code paths max** per audit. If a diff yields more than 30, prioritize by complexity and risk (error paths, security-sensitive branches, public API surfaces first).
• **20 tests generated max** per audit. Focus on highest-impact gaps first.
• **2-minute per-test exploration cap.** If understanding a single test path takes longer than 2 minutes, mark it as "needs manual review" and move on.

Phase 1: Codepath Tracing

Step 1: Identify Changed Files

Determine the diff scope. Use the most relevant source:

# PR diff
git diff --name-only main...HEAD

# Staged changes
git diff --name-only --cached

# Last commit
git diff --name-only HEAD~1..HEAD

Filter to source code files only (exclude configs, docs, generated files).

Step 2: Trace Data Flow Through Every Branch

For each changed file, you MUST trace:

1. **Conditionals** -- Every `if/else`, `switch/case`, ternary, and pattern match. Each branch is a separate codepath. 2. **Error paths** -- Every `catch`, `throw`, error return, validation failure, and early return with error. WHY: Error paths are the most common source of untested bugs. 3. **Function calls** -- Every function invoked from changed code. Trace one level deep into callees to identify integration boundaries. 4. **Loop boundaries** -- Empty collection, single item, and multi-item paths through loops. 5. **Guard clauses** -- Every early return, null check, and permission gate.

Step 3: Build the Codepath Inventory

Produce a structured inventory:

## Codepath Inventory: [filename]

| # | Path Description | Type | Risk |
|---|-----------------|------|------|
| 1 | validateUser() happy path | conditional | low |
| 2 | validateUser() missing email | error | medium |
| 3 | validateUser() invalid format | error | medium |
| 4 | processOrder() empty cart guard | guard | high |
| 5 | processOrder() payment timeout | error | high |
| 6 | processOrder() success | conditional | low |

**Type categories:** `conditional`, `error`, `guard`, `loop-boundary`, `integration`, `async`

**Risk assessment:** `high` = user-facing failure or data loss, `medium` = degraded behavior, `low` = cosmetic or logging

Phase 2: Test Mapping and Quality Scoring

Step 1: Search for Existing Tests

For each file in the diff, search the test directory for related tests:

# Find test files that reference the changed file or its exports
# Search by filename pattern
find tests/ -name "*[changed_file_stem]*" -type f

# Search by import/require of the changed module
grep -rl "import.*from.*[module_name]" tests/
grep -rl "require.*[module_name]" tests/

# Search by function name references
grep -rl "[function_name]" tests/

Step 2: Score Test Quality

For each codepath, assess existing test coverage with this rubric:

| Rating | Meaning | Criteria | |--------|---------|----------| | ★★★ | Behavior + edge cases tested | Tests assert behavior AND cover boundary conditions, error cases, and edge inputs | | ★★ | Happy path tested | Tests cover the success path but miss error branches or edge cases | | ★ | Smoke test only | Test exists but only checks the function runs without error (no meaningful assertions) | | ☆ | No test found | No test references this codepath at all |

Step 3: Produce Coverage Map

Map each codepath to its test coverage:

## Coverage Map: [filename]

| # | Codepath | Test File | Rating | Notes |
|---|----------|-----------|--------|-------|
| 1 | validateUser() happy path | test-user.sh:42 | ★★★ | Asserts valid + invalid inputs |
| 2 | validateUser() missing email | test-user.sh:58 | ★★ | Tests missing, not malformed |
| 3 | validateUser() invalid format | -- | ☆ | No test for format validation |
| 4 | processOrder() empty cart guard | -- | ☆ | Guard clause untested |
| 5 | processOrder() payment timeout | test-orders.sh:30 | ★ | Checks no crash, no assertions |
| 6 | processOrder() success | test-orders.sh:15 | ★★★ | Full integration test |

Phase 3: Coverage Diagram

After completing the map, produce an ASCII coverage summary. This is the primary output artifact.

COVERAGE: 5/12 paths tested (42%)
  Code paths: 3/5 (60%)
  User flows: 2/7 (29%)
GAPS: 7 paths need tests

Break down by category:

BY TYPE:
  conditional:  3/4 tested (75%)  ████████░░
  error:        1/5 tested (20%)  ██░░░░░░░░
  guard:        0/2 tested  (0%)  ░░░░░░░░░░