/unit-test

description: Improves unit test coverage — discovers testing gaps and writes new tests that follow project conventions. Requires /optimus:init to have set up test infrastructure. Conservative — only adds new tests, never modifies existing test logic or source code; untestable code is flagged for /optimus:refactor. For an automated multi-cycle coverage loop, use /optimus:deep coverage.
disable-model-invocation: true
argument-hint: "[path]"

Unit Test Coverage Improvement

Improve unit test coverage for existing code. An optional path argument scopes the run.

Step 1: Pre-flight

Inline harness mode detection

If your invocation prompt body contains `HARNESS_MODE_INLINE`, you are a single cycle (unit-test phase) inside the `/optimus:deep coverage` orchestrator. Read `$CLAUDE_PLUGIN_ROOT/references/coverage-harness-mode.md` and follow its "Unit-Test Phase Execution" section — that section governs which of the steps below run and how this run ends.

Prerequisites and project docs

If `git rev-parse --is-inside-work-tree` does not return `true`, read `$CLAUDE_PLUGIN_ROOT/skills/init/references/multi-repo-detection.md` and apply it. When it returns `true`, resolve the repository root with `git rev-parse --show-toplevel`, including in a linked worktree or subdirectory. In a multi-repo workspace, run Steps 1–5 independently inside each repo that has `.claude/CLAUDE.md` and report results per repo; if no repo is 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.

Load `.claude/CLAUDE.md`, `.claude/docs/coding-guidelines.md`, and `testing.md` where present; if `testing.md` is missing, derive testing conventions from existing test files. In a monorepo (read `$CLAUDE_PLUGIN_ROOT/skills/init/references/project-detection.md` if the structure is unclear), process each subproject independently and load that subproject's own `docs/testing.md` / `docs/` files — never another subproject's; shared guidelines come from root `.claude/docs/`.

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

`$CLAUDE_PLUGIN_ROOT/skills/unit-test/agents/test-infrastructure-analyzer.md` defines what this step has to produce. On a small or path-scoped project — roughly under 100 source files — **run it yourself**: surveying test files, framework, runner command and coverage tooling, then running the suite and coverage, is a handful of tool calls, and doing it inline keeps the file list you are about to write tests against in context.

Delegate when surveying the tree inline would flood this context: for each subproject (or the single project), launch one `general-purpose` agent with that prompt, prepended with the "Agent Constraints" section of `$CLAUDE_PLUGIN_ROOT/references/shared-agent-constraints.md`. Assemble the prompt per "Prompt assembly at dispatch time" in `$CLAUDE_PLUGIN_ROOT/references/agent-architecture.md`.

Present the Discovery Results and Coverage Analysis to the user.

Stop gates

**If no test framework is detected**, stop and report: "No test framework found. Run `/optimus:init` (or re-run it) to install a test framework and set up test infrastructure before using this skill. For a project with no code or detectable stack yet, pick **Scaffold new project** when init asks." Never generate tests without a working framework.

**If the test suite reports failures**, stop — this skill never fixes failing tests or build-level issues.

• **Fail - assertion** (tests compile and run, but some fail): print the quote below, then append a `### Bugs Discovered` section listing each failing test as `[test file] — [test name] — [one-line failure excerpt]` (prefix entries with repo name/path in multi-repo workspaces; omit the excerpt if the runner output did not expose it).

> Pre-existing tests are failing. A green baseline is required before adding new tests, and this skill does not modify existing tests or source code. Stay in this conversation and ask Claude to triage the failing tests listed in Bugs Discovered; once the baseline is green, re-run `/optimus:unit-test` in a fresh conversation.

• **Fail - build** (build/bootstrap failures): print the quote below and stop — no Bugs Discovered section (there are no per-test failures, only build errors).

> The test runner cannot start or test files fail to compile. These are build-level issues, not test logic, and `/optimus:init` owns that repair path. Run `/optimus:init` in a fresh conversation — its health check proposes minimal fixes and re-runs the suite. Once the build is healthy, re-run `/optimus:unit-test` in another fresh conversation.

Step 3: Test Generation Plan

Create a prioritized list, **capped at 10 items per run**: exported/public functions and classes → pure functions and utility modules → business logic with clear inputs/outputs → complex branching logic → internal/private helpers (test through the public API when possible).

**Skip** (flag in the summary, don't attempt): code untestable without refactoring, generated code, migration files, declarative configuration, thin wrappers with no logic.

Present the plan, then use `AskUserQuestion` — header "Plan", question "How would you like to proceed with the test generation plan?": **Approve all** (generate tests for all planned items) / **Selective** (ask which item numbers to proceed with) / **Skip** (no tests — keep the plan as reference).

Step 4: Test Writing

**Conservative constraint:** only add new tests — new files, or new cases appended to existing test files. Never modify existing test logic or source code. If a function can't be tested without changing its signature or extracting dependencies, flag it in the summary instead of changing it.

Test-writing rules:

• Write tests that read like the existing tests. `testing.md` and `coding-guidelines.md` gov