From crucible
Audits existing tests for staleness, needed updates, or removal after code changes. Ensures test suite alignment post-modification in any language or framework.
npx claudepluginhub raddue/crucibleThis skill uses the workspace's default tool permissions.
<!-- CANONICAL: shared/dispatch-convention.md -->
Reviews test suites for coverage completeness, quality, and best practices. Checks happy/sad paths, edge cases, assertions, isolation, AAA patterns, and compliance with RSpec, Minitest, Jest, Playwright.
Audits test suite health by detecting flaky tests, slow tests, coverage gaps, and anti-patterns. Use for test audits, fixing flakiness, analyzing slowness, or suite improvements.
Traces codepaths in git diffs, maps to existing tests, scores coverage, visualizes gaps, and generates tests for uncovered paths in changed files.
Share bugs, ideas, or general feedback.
All subagent dispatches use disk-mediated dispatch. See shared/dispatch-convention.md for the full protocol.
Audits whether existing tests need updating, removal, or modification after code changes. Distinct from test-gap-writer (which adds NEW tests for missing coverage) — this skill reviews the EXISTING test suite's alignment with changed code.
Announce at start: "Running test alignment audit on [scope description]."
Skill type: Rigid -- follow exactly, no shortcuts.
Execution model: When this skill is running, YOU are the orchestrator. You dispatch the audit and fix agents, handle conditional logic, and return results to the caller. All references to "the orchestrator" in this document refer to you.
Technology-agnostic: This skill works with any programming language and test framework. Examples use generic patterns. The audit agent adapts its checks to whatever language and testing conventions are present in the project.
Code changes create three categories of test debt that pass silently:
Test-gap-writer handles a fourth category (missing tests for new behavior). This skill handles categories 1-3 (existing tests misaligned with changed behavior).
The skill receives from the caller:
git diff <base-sha>..<head-sha> or equivalent)./test-audit-prompt.md./test-fix-prompt.md. If the audit was split (step 1), dispatch one fix agent per audit batch sequentially (not in parallel) to isolate revert scope. Sequential execution prevents file clobber when multiple batches have findings in shared test utilities (helpers, fixtures, conftest). Each fix agent checks git status before starting to confirm the tree is in the expected state. A failure in one batch does not discard successful fixes from other batches.test: batch N alignment fixes) before dispatching the next batch. This ensures clean revert targets for subsequent batches and prevents revert clobber of prior successes. The caller may squash these commits per its own protocol.Dispatch: Agent tool (subagent_type: "general-purpose", model: opus)
The audit agent receives the code diff, affected test files (full source), and optional context. It checks three categories:
Category 1 — Tests to Update:
Category 2 — Tests to Delete:
Category 3 — Coincidence Tests (flag only, do not fix):
Evidence requirement: Every finding must reference specific test file, test name, and the line(s) in the diff that make the test problematic. No speculation.
If the audit agent reports findings in categories 1-2, dispatch a fix agent (Opus) that receives:
The fix agent has tool access to read current source files — it needs the actual current behavior (not just the diff) to write correct updated assertions.
The fix agent:
On success: Reports changes made (tests updated, tests deleted, all passing).
On failure: Reverts its own changes using git checkout + git clean (see test-fix-prompt.md), then verifies clean working tree with git status. Reports: "Attempted fix for [finding], reverted because [test failure details]. Manual intervention needed." This prevents broken test modifications from polluting the working tree. The caller decides next steps per its own protocol.
Precondition: The working tree must be clean when this skill starts. The caller should commit before invoking test-coverage (debugging's commit strategy handles this). In multi-batch mode, the orchestrator commits each successful batch before dispatching the next, maintaining the clean-tree invariant throughout. If uncommitted changes are detected, the fix agent reports this and does not proceed.
The skill returns a structured report to the caller:
## Test Alignment Audit Report
### Summary
- Tests audited: N
- Tests updated: N
- Tests deleted: N
- Coincidence tests flagged: N (require caller judgment)
- All modified tests passing: yes/no
- Fix agent reverts: N (if any fixes failed)
### Findings
#### Tests Updated
- `test_file::test_name` — assertion on line N expected OLD_VALUE, updated to NEW_VALUE. Diff ref: [changed line]
[repeat]
#### Tests Deleted
- `test_file::test_name` — tested removed code path [description]. Diff ref: [removed lines]
[repeat]
#### Coincidence Tests (flagged, not modified)
- `test_file::test_name` — exercises changed code but asserts on [unrelated property]. Consider updating assertion to verify [changed behavior].
[repeat]
#### Fix Failures (reverted)
- `test_file::test_name` — attempted [change], reverted because [failure reason]. Manual intervention needed.
[repeat]
### Test Run Results
- [PASS/FAIL] per modified test file
Invoke crucible:test-coverage with:
- Code diff: git diff <pre-debug-sha>..HEAD
- Affected test files: test files in subsystem identified during investigation
- Context: "Debugging fix for [hypothesis summary]"
Invoke crucible:test-coverage with:
- Code diff: git diff <pre-task-sha>..HEAD
- Affected test files: test files touched or related to task
- Context: "Build task N: [task description]"
Build's reviewer Pass 2 focuses on test quality (independence, determinism, edge cases, test level). Staleness detection is delegated to this skill, dispatched after the implementer addresses Pass 2 findings.
Invoke crucible:test-coverage with:
- Code diff: git diff <base-branch>..HEAD
- Affected test files: test files in the diff or test files that import changed modules
- Context: "Finish pre-merge audit for [branch description]"
When finish is called by build, build tells finish to skip Step 2.5 (test-coverage already ran per-task in Phase 3). This step only runs when finish is invoked standalone.
Invoke crucible:test-coverage with:
- Code diff: git diff <base>..HEAD
- Context: [description of changes]
The audit agent must NOT:
The fix agent must NOT:
./test-audit-prompt.md — Test audit agent dispatch./test-fix-prompt.md — Test fix agent dispatch (revert-on-failure, source file access)crucible:debugging (Phase 5 Step 2.5), crucible:build (Phase 3, after test quality review), crucible:finish (Step 2.5, pre-merge audit), standalone invocationcrucible:test-driven-development (writes tests during implementation), test-gap-writer (adds missing coverage for new behavior)crucible:quality-gate (this is a single-pass audit, not an iterative loop)