Unit Test Coverage Improvement

Improve unit test coverage for existing code. Requires /optimus:init to have set up test infrastructure (framework, coverage tooling, testing docs) first. Conservative by design — only adds new test files, never refactors or restructures existing source code. If code is untestable as-is, it flags it rather than changing it. Refactoring is the domain of /optimus:refactor.

Step 1: Pre-flight

Parse invocation arguments

Extract from the user's arguments:

1. deep flag (present/absent)
2. harness keyword after deep (present/absent)
3. A number immediately after deep or deep harness → iteration cap (optional, default 5, hard cap 10)
4. Everything else → scope instructions (optional path)

Examples:

• /optimus:unit-test → normal mode, full project
• /optimus:unit-test src/api → normal mode, scoped
• /optimus:unit-test deep → deep mode (5 iterations)
• /optimus:unit-test deep 3 → deep mode (3 iterations)
• /optimus:unit-test deep src/api → deep mode, scoped
• /optimus:unit-test deep harness → harness mode, 5 iterations
• /optimus:unit-test deep harness 5 "src/api" → harness mode, scoped

Harness mode detection

If system prompt contains HARNESS_MODE_ACTIVE: → Read $CLAUDE_PLUGIN_ROOT/references/coverage-harness-mode.md → Follow the "Unit-Test Phase Execution" section → Skip user confirmation (no AskUserQuestion) → Skip loops — run Steps 2–4 exactly once, then output structured JSON and stop

If harness keyword detected in arguments: → Read $CLAUDE_PLUGIN_ROOT/references/coverage-harness-mode.md Skill-Triggered Invocation section → Pass: max_cycles (from step 1 parsing), scope (from step 1 parsing) → The invocation section will resolve the Python environment, build the terminal command pointing to scripts/test-coverage-harness/main.py, present it, and stop → Do NOT proceed to Step 2

Pre-flight checks

Read $CLAUDE_PLUGIN_ROOT/skills/init/references/multi-repo-detection.md for workspace detection. If a multi-repo workspace is detected, process each repo independently: run Steps 1-5 inside each repo that has .claude/CLAUDE.md. Report results per repo. If no repos have been initialized, suggest running /optimus:init first from the workspace root.

Check that .claude/CLAUDE.md exists. If it doesn't, stop and recommend running /optimus:init first — the project needs baseline context before test generation can be effective.

Beyond the init check, identify which guideline documents are available — they directly affect the quality of everything this skill does:

Monorepo path note: Read the "Monorepo Scoping Rule" section of $CLAUDE_PLUGIN_ROOT/skills/init/references/constraint-doc-loading.md for doc layout and scoping rules. When generating tests for a subproject, load that subproject's testing.md, not another subproject's.

The skill operates differently depending on what exists:

• All three docs — matches existing conventions precisely
• CLAUDE.md + coding-guidelines (no testing.md) — derives conventions from the codebase
• CLAUDE.md only (no guidelines either) — still works, but with less project-specific guidance

Scope

Parse optional path argument (e.g., /optimus:unit-test src/api) to limit scope. If no path is specified, default to the full project.

For monorepos and multi-repo workspaces, detect project structure using the same approach as /optimus:init — reference $CLAUDE_PLUGIN_ROOT/skills/init/SKILL.md Step 1 for detection logic (multi-repo workspace detection, workspace configs, manifest scanning, supporting signals). Process each project/repo independently.

Interactive deep mode activation

If the deep flag was detected in argument parsing (and harness keyword was NOT), activate deep mode. Deep mode loops discovery-and-write cycles (Steps 2–4) until tests converge or the iteration cap is reached.

Clamp the parsed iteration cap: if it exceeds 10, clamp to 10 and warn: "Iteration cap clamped to 10 (maximum)." If it is less than 1, clamp to 1 and warn: "Iteration cap clamped to 1 (minimum)." Default is 5 when no number is given.

Before proceeding, check whether a test command is available (from .claude/CLAUDE.md). If no test command exists, deep mode's auto-approve loop has no safety net — fall back to normal mode and warn: "Deep mode requires a test command for safe auto-approve. Falling back to normal mode — re-run /optimus:init to set up test infrastructure first." Set deep-mode to false. Then continue with the standard single-pass flow.

If a test command is available, warn the user:

Deep mode runs up to [cap] iterative test-generation passes. Each iteration is a full discovery-and-write cycle — credit and time consumption multiplies with iteration count. Tests are generated automatically at each iteration without per-item approval. Untestable code that requires refactoring is flagged but not addressed; consider running /optimus:refactor testability first or /optimus:unit-test deep harness for an automated unit-test + refactor-testability loop. Each iteration also accumulates context — on large codebases, output quality may degrade in later iterations.

Test command: [test command from CLAUDE.md]

Then use AskUserQuestion — header "Deep mode", question "Proceed with deep mode?":

• Start deep mode — "Run iterative test-generation until converged (max [cap] iterations)"
• Normal mode — "Single pass with manual plan approval instead"

Tell the user: Tip: For large codebases or extended sessions, re-run with /optimus:unit-test deep harness to launch the external harness with fresh context per phase.

If the user did not invoke with deep, skip this step.

If the user selects Normal mode, set deep-mode to false and continue with the standard single-pass flow.

If deep mode is confirmed, set deep-mode to true and initialize:

• Counters: iteration-count = 1, total-added = 0, total-reverted = 0, accumulated-coverage-delta = 0
• accumulated-items = empty list — each entry records file (test file path), target (the file:function/class being tested — one entry per covered symbol, so convergence matching is exact-match on this string), iteration (which iteration added it), and status (pass | reverted — test failure | bug-found | abandoned)
• accumulated-untestable = empty list — items the analyzer classifies as not-testable-without-refactoring across iterations
• accumulated-bugs = empty list — bugs discovered by test failures across iterations

Define the [coverage-summary] placeholder once: when the coverage tool is available, render as <sign><abs(accumulated-coverage-delta)>pp where <sign> is + for values ≥ 0 and - for negative (e.g. +2.5pp, -1.0pp). When the coverage tool is unavailable, render as not measured. Every downstream use (iteration-context block, iteration report, progress summary, cumulative report) applies this same rendering.

Step 2: Discovery & Coverage Analysis (agent-assisted)

Delegate test infrastructure scanning, test execution, and coverage analysis to a reconnaissance agent to keep the main context clean for test writing.

For each subproject (or the single project):

Read $CLAUDE_PLUGIN_ROOT/skills/unit-test/agents/shared-constraints.md for agent constraint