---
name: improve-tests
description: Improve a whole test suite by consolidating cross-file duplication and reducing execution cost while preserving coverage and defect detection.
---

## Goal

Improve the requested test suite as a whole, not just an individual test. Compare opportunities across files before changing the strongest supported scope. A scope is one coherent improvement batch, which may span many files; implement and verify batches sequentially. Preserve meaningful protection; a smaller suite is not better if defects become invisible.

### Definition of Done

- The requested suite's inventory, contracts, discovery gaps, fixed overall baseline, and cross-file opportunities are recorded.
- The selected batch has the strongest evidenced suite-level gain relative to effort and risk, and each change is verified before the next.
- Removed tests have retained assertions and representative defect detection or an authorized retired contract; unique failure and diagnostic protection remains.
- Comparable suite-wide discovery, skips, coverage scope, detection, runtime, and results support the reported change; fixtures and configured CI wiring match retained tests.
- Quality validation accepts the selected mode; achieved reduction, shortfall, and unverified gaps are explicit. An assessment makes no changes or test runs.

## Workflow

1. Resolve mode, authority, consumer rules, contracts, and the requested unit (test cases, test source lines, or measured suite runtime). Discover the repository's languages, native test commands, discovery rules, and available coverage tools; do not impose a test framework or toolchain to use this skill. Default to the whole repository suite unless the request narrows it. Freeze that suite's baseline revision, measurement unit, denominator, exclusions, discovery configuration, and available coverage instrumentation before editing; do not reset the overall baseline for each batch. Do not count newly skipped, undiscovered, or excluded tests as savings. In read-only mode, inspect through step 2, skip steps 3–4, then validate the assessment in step 5 without edits or test runs.
2. Inventory the requested suite across directories, packages, and configured runners before selecting a batch; reconcile native discovery with repository test files, recording ignored, skipped, generated, or undiscovered cases. Compare test files, assertions, fixtures, helpers, mocks, and setup across that inventory for duplicate protection and repeated cost. Read contracts, inputs, environments, failures, and diagnostic value before calling similar or identical files redundant. Inspect suite-level coverage gaps, shared-state flakiness, and runtime hotspots; a file count or one-test inspection is not a suite assessment. Use [Code test management](references/vstack/capabilities/code-test-management/REFERENCE.md) with mode and evidence to compare keep, improve, merge, replace, or remove. Rank cross-file and suite-level opportunities by observed cost, overlapping protection, defect risk, effort, and reach; in change mode take a cheap discriminating check when ranking is uncertain; in read-only mode propose it without execution. If the reference is missing, map contracts to actual assertions and distinct failure cases directly; similarity of names or line coverage alone does not establish redundancy.
3. In change mode, select one coherent batch, such as duplicate test files, repeated fixture setup, or an overlapping family of cases; do not restrict it arbitrarily to one test. Trace imports, configuration, and runner consumers before consolidating or deleting files, helpers, or fixtures. For preserved contracts, run retained replacements and a representative fault or negative control before deleting scoped cases. For an approved retired contract, verify the change and remaining consumers without inventing replacement coverage. Keep distinct boundary, denial, integration, recovery, and fast diagnostic checks. Diagnose flaky tests rather than silencing them; delete obsolete fixtures only after checking consumers. Retain a recoverable diff and preserve unrelated work.
4. In change mode, run affected and dependent tests after each batch; compare the final requested suite against its fixed baseline for discovery, skips, coverage denominators, detection, runtime, and diagnostics. Missing suite-wide execution or coverage evidence remains a gap and cannot support a whole-suite preservation claim. Where CI is configured, confirm it runs the retained checks and catches a plausible regression; otherwise prove detection through the native local runner without adding CI. Missing coverage tooling remains an evidence gap, not permission to weaken protection. Re-rank after this verified stage and continue only while a supported gain is worth its cost. Update only the owning test contract or fixture documentation needed to keep future maintenance clear.
5. For substantive work, including assessments, use [Quality validation](references/vstack/protocols/quality-validation.md) with mode, current candidate, and evidence; if unavailable, self-assess, obtain independent review and critique where required, triage findings, and renew affected verdicts directly. Rerun invalidated checks after repairs. Report `(baseline - current) / baseline × 100` against the original suite size, comparable suite runtime results, consolidated files and retained-protection mappings, target shortfall, and discovery or execution gaps. Stop rather than weaken detection to hit a percentage; assessment savings are projected, not achieved.