refine-tests
Reviews existing test code for conformance to the test-designing-guide and test-writing-guide, then applies the refinements. Use this skill when the user wants to review or refine existing test code so it follows the project's test design and writing conventions. Typically invoked as `/refine-tests <PATH>`.
Koji Hasegawa · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add nowsprinting/unity-coding-skills --skill refine-testsAbout this skill
name: refine-tests
description: >-
Reviews existing test code for conformance to the test-designing-guide and
test-writing-guide, then applies the refinements. Use this skill when the
user wants to review or refine existing test code so it follows the
project's test design and writing conventions.
Typically invoked as /refine-tests <PATH>.
argument-hint: "[file paths]"
license: Unlicense
metadata:
author: Koji Hasegawa
Reviews existing test code for conformance to the test-designing-guide and test-writing-guide, then applies the refinements.
Scope Check
This skill is for refining existing tests for conformance to the guides. If the request is out of scope, redirect:
- Adding tests for a new feature or spec change → use
/plan-featureinstead - A failing test, or a test that verifies incorrect behavior → use
/fix-buginstead
Input
One or more file path arguments. Resolve them to the concrete set of test files to review before proceeding.
If no path argument is given, use AskUserQuestion to ask the user for the targets. Do not derive targets from git status — that would silently widen the scope beyond what was requested.
Workflow
Recording implementation notes: Notes for this run go in /tmp/refine-tests-notes-$CLAUDE_CODE_SESSION_ID.md. Immediately before your first append in this run — and only then — delete that file if it exists (usually it will not), so this run starts from an empty one: the session id is shared by every /refine-tests run in the session, so an earlier run abandoned before Step 7 would otherwise leak its notes into this one.
While working through Steps 5–6, whenever one of the following occurs, immediately append a line to that file — do not wait until the end to reconstruct these from memory:
- A Finding was ambiguous, or proved wrong once applied, and you made a judgment call → Design decisions
- You intentionally departed from a Finding, and why → Deviations
- You considered alternatives and chose one, and why → Tradeoffs
- You changed production code — a method demoted to
private, a dead test-only seam removed, or any other production edit — and why → Production code changes
Append with Bash so the shell expands $CLAUDE_CODE_SESSION_ID — the Write tool cannot append and does not expand environment variables:
cat >> "/tmp/refine-tests-notes-$CLAUDE_CODE_SESSION_ID.md" <<'EOF'
- **Production code changes**: <one line>
EOF
When a step delegates to another skill (/simplify and /resolve-diagnostics in Step 6), append the note yourself from what it returns — they do not write to this file.
Step 1: Read the Target Tests
Launch Explore agent(s) to read the target test file(s) and the production code they exercise. Reading the production code is necessary to judge layer-appropriateness and structural-vs-spec-based issues.
Step 2: Conformance Review
Load the test-designing-guide and test-writing-guide skills. Apply all rules that are verifiable from the test code alone — no requirements document is available.
The following sections of test-designing-guide require requirements input or production-design changes and are out of scope:
- Section 5 (requirements coverage / traceability / same-layer witness)
- Section 6 (design-document output format)
- Section 7 (Testability Assessment — remedies require production-design changes)
Produce a Findings list. Each finding records:
- Location: file path + test method name
- Category: which guide + rule violated, or duplicate test (see Step 3)
- Concrete proposed change
Step 3: Duplicate Detection
Compare the target test files against each other and against other tests in the same test class.
A true duplicate has both of the following in common with another test:
- Same condition — identical setup / input
- Same assertion — identical observation / expected value
Do NOT flag tests that share only one:
- Different condition → not a duplicate
- Same condition but different assertion → not a duplicate
For each true duplicate pair, append a Finding to the Findings list from Step 2:
- Proposed change: delete the redundant test (the less accurately named one) and keep the more accurately named one. Name both explicitly.
- Do NOT propose merging same-condition tests into a single multi-assert test.
Exception — defer to Step 4: If one test in a duplicate pair is [Category("Internal")] and the other is a public-seam test, do not apply the name-quality tiebreaker here. Do not delete the public-seam test on naming grounds. Defer the pair to Step 4, which always keeps the public-seam test.
Step 4: Seam Redundancy — Internal-Method Tests
Test through the same seam production code uses. A [Category("Internal")] test exercises an internal method directly. For each such test in the targets, append Findings via two passes. Overriding rule: never trade coverage for a tidier seam; when in doubt, keep the test (and keep internal).
Layer scope: This step operates within the unit test layer only. Tests with [Category("Integration")] or [Category("VisualVerification")] applied run under different execution contexts and are not candidates for a covering test — do not consider them when searching for a public-seam test that covers the same scenario.
Pass 1 — classify each [Category("Internal")] test:
- A public-seam test already covers it (from the test code alone): a separate unit test asserts the same observable outcome for an equivalent scenario through a public method → Finding: delete the internal test, keep the public-seam test (name both).
- No public-seam test covers it — using the production code read in Step 1: a. Not fully observable through public — a public caller masks or only partially exposes the asserted outcome → keep the internal test; no Finding. "Cheap to extract" ≠ "observable publicly." b. **Sa