pi-dev-team 0.2.0

package/skills/test-design-advisor/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: test-design-advisor
+description: Worker skill — assess testability, recommend the right test-pyramid layer and test-double strategy, and propose a behavior-preserving refactor sequence to make hard-to-test code testable. Invoked by /test-design and /test-health; not user-invocable. For a user-facing entry point use /test-design (add --advise --path <file> for forward-design on a single unit).
+role: worker
+---
+
+# Test Design Advisor
+
+## Overview
+
+An **advisory** skill: it recommends how to test code and how to make untestable code testable. It does not write tests or refactor code — it produces a design the human (or `/build`) then implements. Use it before writing a test suite for an untested or hard-to-test module, or when a test is hard to write and you suspect the design is the cause.
+
+Grounded in these knowledge references: `knowledge/test-smells.md`, `knowledge/test-doubles.md`, `knowledge/test-pyramid.md` (layers + shapes), `knowledge/test-layer-gates.md` for behavior pre-gates, `knowledge/microservice-testing.md`, `knowledge/testability-patterns.md` for production-code seams, and `knowledge/test-strategy.md` for fixture and SUT-interaction strategy. For the xUnit pattern families it grounds in `knowledge/fixture-construction.md` (how the fixture is built/disposed), `knowledge/value-patterns.md` (Literal/Derived/Generated Value + Dummy Object for test data), `knowledge/result-verification.md` (assertion patterns), `knowledge/test-organization.md` (Four-Phase + suite structure), `knowledge/test-refactoring.md` (goals/principles + the test-side refactoring catalog), and `knowledge/test-automation-principles.md` (the goals/principles a recommendation must honor — the rubric behind every "why"). When the target is untested legacy code, it grounds the get-under-test-first sequence in `knowledge/dependency-breaking-techniques.md` (behavior-preserving seams) and `knowledge/legacy-test-strategy.md` (effect/pinch reasoning for where to place the tests). On match it overlays `knowledge/testing-techniques/` (specialized techniques), resolves tools from `knowledge/test-stack-profiles/<stack>.md`, and may adapt a worked template from `knowledge/test-matrix-examples/`.
+
+## Constraints
+
+- Advisory only. Do not edit production code or write test files — output a recommendation.
+- A hard-to-test design is a production-code problem. Recommend the seam (constructor injection, interface extraction), never a test workaround (reflection, `InternalsVisibleTo`, mocking concrete classes).
+- Prefer the lowest test-pyramid layer that can verify the behavior; prefer state verification and the simplest double.
+- Refactor sequences must be behavior-preserving and start with characterization tests when the code is currently untested.
+- Be concise: tables and ordered steps, not prose. No restating the source material — cite the knowledge file.
+- **Altitude boundary.** When a gate mandates application-level E2E/browser architecture, flag the seam (`→ cd-test-architecture`) and defer the harness/pipeline design to the `cd-test-architecture` skill — do not design the E2E harness here.
+- **Vocabulary (MinimumCD).** Use the six MinimumCD test types defined in `knowledge/cd-test-architecture.md` § *The Six Test Types*: **static analysis / unit / component / contract / integration / E2E**. **"Contract test"** is the primary term — use it. When the codebase or external context calls it a **"narrow integration test"**, gloss it once in the same sentence: `contract test (also called narrow integration test)`. Never use "narrow integration" alone. When the codebase uses different names for layers (e.g. "service test", "API test", "scenario test"), emit a **Terminology mapping** table at the top of the report and then use the MinimumCD term consistently from that point.
+- **Test type definitions.** When the report mentions any of {unit, component, contract, integration, E2E, static analysis, sociable unit, solitary unit, resilience}, define each term on first use — either inline as a one-line gloss or in a small **Test type definitions used in this report** block at the top. Definitions come verbatim from `knowledge/cd-test-architecture.md` § *The Six Test Types*.
+- **The pyramid is a cost heuristic, not a target shape** — canonical rule in `knowledge/cd-test-architecture.md#the-pyramid-is-a-cost-heuristic-not-a-target-shape`. No "current shape vs recommended shape" tables and no per-layer target counts; place each behavior at the lowest layer that can verify it.
+- **E2E justification gate** — canonical in `knowledge/cd-test-architecture.md#the-e2e-justification-gate`. Recommend E2E only when all four conditions hold, and surface the four-condition verdict in the E2E justification table (Output).
+
+## Parse Arguments
+
+Arguments: target file(s), module, or a description of the code to test. If no target is given, ask for one. Detect language **and framework/stack** (from manifests — `package.json`, `build.gradle`/`pom.xml`, `*.csproj`, `go.mod`, `requirements.txt`/`pyproject.toml`, and frontend deps like react/vue/htmx) so tool resolution can pick the right `test-stack-profiles/<stack>.md`. Detect whether the target crosses independently-deployable service boundaries (load `microservice-testing.md` only if so).
+
+## Steps
+
+### 1. Assess testability
+
+Read the target. For each unit, determine whether it can be constructed and driven through its public API with controlled inputs. Use the decision flow in `knowledge/testability-patterns.md`. Record blockers: static factories/singletons, new-ed-up dependencies, hidden global/clock/RNG access, concrete-class coupling, private logic with no public path.
+
+**Graph-assisted testability assessment.** Prefer CodeGraph/Repowise over raw `Grep`/`Read` for finding the unit's collaborators, its callers, and blast radius before recommending a seam — see [`knowledge/codegraph-vs-graphify.md`](../../knowledge/codegraph-vs-graphify.md) for tool selection and the fallback contract.
+
+### 1b. Behavior pre-gates (escalate the layer by failure mode)
+
+Before pyramid placement, run the gates in `knowledge/test-layer-gates.md`. They **escalate upward only** — never lower the Step 2 pick; silent when none fire:
+
+- **Gate A** user-facing dynamic → E2E alongside lower layers (state cost + amortization)
+- **Gate B** bug fix → regression at the discovery layer (no escalation above it)
+- **Gate C** HTMX/Alpine/Turbo swap → browser test REQUIRED for the seam
+- **Gate D** visual artifact → approval/screenshot (with a reference) or manual
+
+If dynamic-ness is ambiguous, state your assumption and ask **once** (batch ambiguities; offer "treat all as dynamic") — never escalate silently. When a gate mandates app-level E2E, flag it `→ cd-test-architecture` and defer the harness design there.
+
+### 2. Place each behavior on the pyramid
+
+Using `knowledge/test-pyramid.md`, assign each behavior to the lowest layer that can meaningfully verify it (unit / component / contract / integration / E2E — MinimumCD names per the Vocabulary constraint). Flag anything currently mis-layered. For service boundaries, apply contract testing per `knowledge/microservice-testing.md` instead of E2E. For any behavior placed at integration or E2E, the E2E justification gate (Constraints) MUST be satisfied and the four-condition verdict surfaced in the report.
+
+**Two-direction justification.** The placement table's *Why this layer* column carries a two-direction justification: when the pick is unit or component, explain why a higher layer would be redundant or cupcake-shaped duplication; when the pick is integration or E2E, explain why a contract or component test cannot cover the behavior. The advisor must articulate the trade-off rather than pattern-match a layer.
+
+**No target counts.** Do NOT emit a "current shape vs recommended shape" table or any per-layer target count. Per-behavior placement is the only valid output for layer recommendations (see the Constraints: *The pyramid is a cost heuristic, not a target shape*).
+
+**Redundancy check (business-critical only).** After placement, for any behavior determined business-critical (labelled, or confirm by asking), if it is covered at only one layer, flag it and name a second layer with a different failure mode (catches/misses table in `test-layer-gates.md`) plus a concrete recommendation.
+
+**Gate-column output schema.** In the *Pyramid placement* table the `Gate` column uses: `—` (no gate), `↑<layer>` (escalated), `→ cd-test-architecture` (E2E architecture deferred). When multiple gates fire, union the layers (no duplicate) and list each gate's cost once, with reconciliation guidance if the amortization advice differs.
+
+**Tool resolution (by detected stack).** After the layer is fixed, name the concrete tool. If the detected stack has a profile in `knowledge/test-stack-profiles/<stack>.md`, read it and fill the `Tool` column from its layer→tool map (e.g. Spring integration → MockMvc; SSR frontend → JSDOM+MSW, **not** a browser unit runner). If no profile matches, proceed with stack-agnostic guidance and **name the missing profile** in the report — never block on it.
+
+**Few-shot templates.** When building a multi-behavior matrix for a common stack, you *may* load a worked example from `knowledge/test-matrix-examples/` as a template and adapt its rows — never copy it verbatim.
+
+### 2b. Specialized technique overlay (on trigger match)
+
+Some behaviors break in a way no pyramid layer addresses. Consult `knowledge/testing-techniques/` and add a technique **only when its trigger matches** — silent otherwise. Each overlay note states the technique and its maintenance cost; it complements (does not replace) the layer pick.
+
+| Trigger | Overlay | File |
+|---------|---------|------|
+| Invariant/law holds for all inputs | property-based | `property-based.md` |
+| Parses untrusted/unstructured input | fuzz | `fuzz.md` |
+| Large text/structured artifact vs a reference | approval | `approval.md` |
+| Visual/CSS/layout fidelity matters | screenshot | `screenshot.md` |
+| Payload governed by a declared schema (OpenAPI/JSON Schema/Avro) | schema-validation | `schema-validation.md` |
+| Resilience claim under dependency failure | chaos | `chaos.md` |
+
+**Exclusion.** Do **not** add a contract-testing technique here. Consumer↔provider agreement across an owned service boundary routes to `knowledge/microservice-testing.md` (CDC) — never double-route.
+
+### 3. Choose doubles
+
+For each collaborator at each test, recommend the simplest double using the decision flow in `knowledge/test-doubles.md` (dummy/stub/spy/mock/fake) and whether to verify by state or behavior. Default to state verification + stub/fake; reserve mock/spy for true side-effect boundaries.
+
+### 3b. Recommend fixture and interaction strategy
+
+**Under `/test-design`**, the smell agent has already named the smell and its remedy family (via `remedyFamily`, per `knowledge/test-review-division-of-labor.md` § "test-smell-review ↔ test-design-advisor — remedy division"); this step supplies the specific remedy pattern from that family and its per-behavior application. When invoked standalone, this step supplies both the smell framing and the pattern.
+
+Using `knowledge/test-strategy.md`, recommend per test group: fixture design + lifecycle (default Minimal + Fresh; escalate to Immutable Shared → Shared only under measured speed pressure), how the test is driven (scripted default; data-driven when variation is purely data), and SUT interaction (front-door by default; Layer Test for layered code; Back Door Manipulation only when the front door obscures intent). Flag any reliance on a mutable Shared Fixture as an Interacting-Tests risk.
+
+For the construction **mechanics** that realize that strategy, recommend a specific pattern from `knowledge/fixture-construction.md` — Creation Method / Test Data Builder / Object Mother for building, the right setup location, and **Automated Teardown** for persistent fixtures — to fix fixture smells (Mystery Guest, General Fixture, Irrelevant Information, Test Code Duplication) at the root rather than only naming them.
+
+### 3c. Recommend verification and test structure
+
+**Under `/test-design`**, the smell agent has already named the smell and its remedy family (via `remedyFamily`, per `knowledge/test-review-division-of-labor.md` § "test-smell-review ↔ test-design-advisor — remedy division"); this step supplies the specific remedy pattern from that family (result-verification and test-organization patterns) and its per-behavior application.
+
+Using `knowledge/result-verification.md`, recommend the assertion pattern that fixes verification smells: **Expected Object** for field-by-field clutter, **Custom Assertion / Verification Method** for repeated complex comparisons or poor failure messages, **Guard Assertion** before a precondition-dependent assertion, **Delta Assertion** against a baseline for shared/persistent fixtures — and verify one logical condition per test.
+
+Using `knowledge/test-organization.md`, recommend test/suite structure: make the **Four-Phase Test** (Setup → Exercise → Verify → Teardown) visible, group **Testcase Class per Class / Feature / Fixture** when setups diverge, share via a **Test Utility Method / Helper** (composition) over a **Testcase Superclass** (inheritance), and collapse data-only duplication into a **Parameterized Test**.
+
+### 4. Propose a behavior-preserving refactor sequence (only if blockers or test smells exist)
+
+If Step 1 found blockers in **production** code, produce an ordered sequence that makes it testable without changing behavior:
+
+1. Add characterization tests around current behavior (if untested) — pin existing behavior first.
+2. Introduce the seam (the specific pattern from `testability-patterns.md`).
+3. Write the now-possible tests at the layer from Step 2.
+4. Refactor under green.
+
+When the smell is in the **test** itself (not production code), name the specific behavior-preserving move from `knowledge/test-refactoring.md` that removes the smell and shifts the test toward the violated goal/principle — e.g. *Inline Mystery Guest* → Fresh Fixture via Creation Method, *Replace General Fixture with Minimal Fixture*, *Introduce Expected Object*, *Extract Custom Assertion*, *Split Test*. Test refactorings are behavior-preserving and **characterization-first** when the target is untested.
+
+Each step names the pattern and the exact change required.
+
+### 5. Report
+
+Write the recommendation (see Output). Keep it actionable — every recommendation maps to a concrete next edit.
+
+## Output
+
+A concise advisory report (to chat for a single unit, or to `.dev-team-reports/test-design-<target>.md` for a module):
+
+```markdown
+## Test Design — <target>
+
+### Test type definitions used in this report
+<one-line glosses for every MinimumCD term used below; verbatim from
+`knowledge/cd-test-architecture.md` § The Six Test Types>
+
+### Terminology mapping (only if the codebase uses non-MinimumCD names)
+| Local name | MinimumCD term |
+
+### Testability
+| Unit | Testable as-is? | Blocker | Seam (testability-patterns.md) |
+
+### Pyramid placement
+| Behavior | Layer | Gate | Tool | Why this layer (not the one above or below) |
+
+(`Tool` from the stack profile, or `—` / "no profile: <stack>" when none matches.
+*Why this layer* MUST be two-direction: unit/component picks justify why higher
+would be redundant; integration/E2E picks justify why contract/component
+cannot cover the behavior.)
+
+### E2E justification (only when a behavior is placed at E2E)
+| Behavior | (1) Contract test ruled out — why | (2) Component test ruled out — why | (3) Resilience test ruled out — why | (4) User journey + multi-component rationale | Pipeline stage |
+
+### Technique overlay (only if a trigger fired)
+| Behavior | Technique | Cost note |
+
+### Double strategy
+| Test | Collaborator | Double | Verify by |
+
+### Refactor sequence (if blockers)
+1. <characterization tests> → 2. <seam> → 3. <tests> → 4. <refactor>
+
+### Next edit
+<the single concrete first action>
+```
+
+**Do NOT emit a "current shape vs recommended shape" table or any per-layer target count.** The pyramid is a cost heuristic; per-behavior placement is the only valid layer output. See Constraints.
+
+## Integration
+
+- Pairs with the `test-smell-review` agent (which *detects* smells) and the `farley-score` skill (which *scores* an existing suite). This skill *designs* tests forward.
+- For application-level test architecture (CD pipeline alignment, deterministic config-free CI gate, per-component UI/service/batch patterns), defer to the `cd-test-architecture` skill and its knowledge files (`cd-test-architecture.md`, `component-test-patterns.md`). This skill stays at unit/module altitude.
+- Hand the refactor sequence to `/plan` or `/build` for TDD implementation. This skill stops at the design.

package/skills/test-driven-development/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: test-driven-development
+description: Advisory reference for the Classic RED-GREEN-REFACTOR TDD discipline with hard gates — not a build cadence toggle. The plugin's single build cadence is Code-First Small Batches (docs/experiments/RECOMMENDATIONS.md Rec 3); /build does not dispatch into this skill. Use on explicit user request when someone wants test-first discipline for the code being written, or when reviewing code to verify TDD discipline was followed by hand.
+role: worker
+user-invocable: true
+---
+
+# Test-Driven Development
+
+## Overview
+
+Enforces strict RED-GREEN-REFACTOR discipline with verifiable gates. LLMs are especially prone to skipping tests or writing them after implementation — this skill exists because that tendency produces code that looks tested but isn't actually validated.
+
+**Positioning:** this is an **advisory methodology reference**, not a build cadence. `/build` runs a single cadence — Code-First Small Batches: implement one behavior, write its test in the same cycle, refactor on every green (`docs/experiments/RECOMMENDATIONS.md` Rec 3: test-first ordering by itself buys nothing; the per-green refactoring is the mechanism, and it is mandatory). `/build` never dispatches into this skill automatically. Use it only when a human explicitly asks for test-first discipline outside of `/build`, or when auditing existing code for TDD discipline after the fact. When applied, every rule below still holds — including the Iron Law and its hard gates.
+
+**Defect fixes are not covered by this advisory status.** General feature development under `/build` uses Code-First Small Batches and never requires the full RED-GREEN-REFACTOR cycle in this skill. Fixing a bug is different and is **mandatory, not optional**: always reproduce the defect with a failing test before writing the fix. That hard gate lives in `skills/systematic-debugging/SKILL.md` Phase 4, not here — this skill remains advisory-only for new-feature construction.
+
+## Iron Law
+
+**No production code without a failing test first.** If you didn't watch the test fail, you don't know if it tests the right thing. Code written before tests must be deleted and reimplemented from the test — no exceptions.
+
+## Constraints
+- Do not write implementation code without a failing test first
+- Do not move to the next unit of work until all tests pass
+- Do not skip the refactor step — it's where design quality happens
+- Do not rationalize exceptions to the cycle (see Rationalization Prevention below)
+- Before doubling any collaborator, check it against `${CLAUDE_PLUGIN_ROOT}/knowledge/internal-collaborator-doubling.md#the-three-blockers-exhaustive`'s blocker table
+
+## The Cycle
+
+Each unit of work follows three phases with hard gates between them:
+
+### 1. RED — Write a failing test
+- Write the smallest test that describes the next behavior
+- Use real code, not mocks, whenever avoidable
+- Run the test suite — **the new test must fail**
+- **Hard gate**: paste the failing test output. No output = no proceeding.
+- Verify the failure is for the expected reason (missing feature, not a typo or import error)
+- If the test passes without new code, the behavior already exists — pick a different test
+
+### 2. GREEN — Make it pass
+- Write the minimum implementation to make the failing test pass
+- Run the test suite — **all tests must pass** with no errors or warnings
+- **Hard gate**: paste the passing test output. No output = no proceeding.
+- Do not add behavior beyond what the test requires
+- Do not refactor yet
+
+### 3. REFACTOR — Review then clean up
+
+After GREEN, dispatch review agents **before** making any structural changes.
+
+#### 3a. Post-GREEN review
+
+1. **Always** — run `refactor-opportunity-review` on all changed files
+2. **When non-trivial** (any changed function exceeds 20 lines, nesting exceeds 3 levels, or more than one function was modified) — also run `structure-review` on the changed files
+3. Collect all `error` and `warning` findings from both agents — these are the refactor candidates for this cycle
+
+#### 3b. Bounded fix loop (max 3 iterations)
+
+Repeat until no `error`/`warning` findings remain, or 3 iterations have elapsed:
+
+1. Apply the highest-severity finding — smallest behavior-preserving change possible
+2. Run the test suite — **all tests must still pass**
+3. If tests break: undo the change immediately; mark the finding as untouchable; move to the next finding
+4. If tests pass: accept the change; move to the next finding
+
+After 3 iterations, stop. Remaining findings are noted for the next cycle or escalated to the human.
+
+#### 3c. Verify green
+
+Run the full test suite one final time after the fix loop:
+
+- **All tests must still pass** before leaving REFACTOR
+- Do not proceed to the next RED cycle with any test red
+
+Then return to RED for the next behavior.
+
+## Rationalization Prevention
+
+LLMs generate plausible excuses for skipping TDD. These are the common ones and why they're wrong:
+
+| Excuse | Reality |
+|--------|---------|
+| "I'll add tests after the implementation" | You won't. And if you do, you'll write tests that pass by definition — they test what you wrote, not what should work. |
+| "This is too simple to test" | Simple code breaks too. Testing takes 30 seconds. The one-line change that caused the most expensive bug looked simple too. |
+| "Writing the test first would be slower" | TDD is faster than debugging. It catches errors at the cheapest possible moment. |
+| "I need to see the implementation shape first" | That's called a spike. Do the spike, throw it away, then TDD the real implementation. |
+| "The test framework isn't set up yet" | Set it up. That's the first task, not a reason to skip testing. |
+| "I'm just refactoring, not adding behavior" | Then existing tests should pass throughout. If there are no existing tests, write characterization tests first. |
+| "This is glue code / config / boilerplate" | Glue code that breaks takes down the system. If it can break, it needs a test. |
+| "I already tested it manually" | Manual testing lacks systematic, re-runnable verification. It doesn't cover edge cases and you re-test every change. |
+| "Deleting my existing code is wasteful" | Sunk cost fallacy. Unverified code is technical debt, not an asset. |
+| "Let me keep my code as a reference and write tests first" | You'll adapt it instead of TDD-ing. That becomes testing-after with extra steps. |
+| "The test is hard to write — I'll come back to it" | Hard-to-test code is hard-to-use code. The test is telling you the design needs work. Listen to it. |
+| "TDD slows me down / I'm being pragmatic" | TDD is the pragmatic choice. Truly pragmatic means test-first because debugging costs more than testing. |
+
+If you catch yourself composing an excuse not on this list, it's still an excuse. Write the test first.
+
+## Red Flags Requiring Restart
+
+Stop immediately and restart from RED if you notice:
+- Writing implementation code before tests
+- Adding tests after implementation
+- Tests passing immediately without new implementation (testing existing behavior)
+- Tests deferred to "later"
+- Any rationalization beginning with "just this once"
+- Manual testing claims replacing automated verification
+- "Keep as reference" or "adapt existing code" language
+- Sunk cost justifications for keeping pre-test code
+
+**Response**: Delete the code written without tests. Start over with RED.
+
+**A failing test you can't explain is a debugging task, not a restart.** Do not delete code to escape an unexplained failure. Enter [Systematic Debugging](../systematic-debugging/SKILL.md) (reproduce → root cause); only once you understand *why* it failed do you decide whether the fix is code or a restart from RED.
+
+## Verification Checklist
+
+Before completing a unit of work:
+- [ ] Every new function/method has a test
+- [ ] Each test was watched failing before implementation
+- [ ] Each failure occurred for the expected reason (missing feature, not typo)
+- [ ] Minimal code written to pass each test
+- [ ] The whole suite passing with clean output (no errors, no warnings) — a red test anywhere is failure, not just the ones this change touched; "pre-existing / not my diff" does not clear it
+- [ ] Tests use real code (mocks only when unavoidable)
+- [ ] Edge cases and error conditions covered
+
+Missing any checkbox = TDD was skipped. Restart from RED.
+
+## Exception Permissions
+
+Ask your human partner before skipping TDD for:
+- Throwaway prototypes (spike-and-discard)
+- Generated code (scaffolding tools, codegen output)
+- Configuration files with no behavioral logic
+
+Even with permission, document the exception.
+
+## Anti-Pattern: Horizontal Slicing
+
+**DO NOT write all tests first, then all implementation.** This is "horizontal slicing" — treating RED as "write all tests" and GREEN as "write all code."
+
+This produces bad tests:
+- Tests written in bulk test *imagined* behavior, not *actual* behavior
+- You end up testing the *shape* of things (data structures, signatures) rather than user-facing behavior
+- Tests become insensitive to real changes — passing when behavior breaks, failing when behavior is fine
+- You outrun your headlights, committing to test structure before understanding the implementation
+
+**Correct approach: vertical slices via tracer bullets.** One test → one implementation → repeat. Each test responds to what you learned from the previous cycle.
+
+```
+WRONG (horizontal):
+  RED:   test1, test2, test3, test4, test5
+  GREEN: impl1, impl2, impl3, impl4, impl5
+
+RIGHT (vertical / tracer bullet):
+  RED→GREEN: test1→impl1
+  RED→GREEN: test2→impl2
+  RED→GREEN: test3→impl3
+```
+
+The first vertical slice is the **tracer bullet** — it proves the path works end-to-end before you invest in breadth. If the tracer bullet reveals a bad design assumption, you've wasted one cycle, not five.
+
+## Integration with Phases
+
+- **Phase 2 (Plan)**: Test strategy is part of the plan — identify what tests will be written for each unit
+- **Phase 3 (Implement)**: Every unit of work follows RED-GREEN-REFACTOR. The inline review checkpoint runs after GREEN, not during RED.
+- **Acceptance tests**: Feature file scenarios (Gherkin) define the outer loop. TDD operates within each scenario's implementation.
+
+## Output
+Verified RED-GREEN-REFACTOR cycle evidence: failing test output, passing test output, and refactored code with passing tests for each unit of work.

package/skills/test-health/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: test-health
+description: Project-wide test-strategy audit — derive the suite's shape and shape-vs-architecture fit, map coverage to the Agile Testing Quadrants, roll up coverage + mutation health, flag flaky tests and automation maturity, and produce an ordered improvement plan. Delegates CD-determinism + pipeline assessment to cd-test-architecture. Use when the user says "audit our tests", "how healthy is our test suite", "test strategy review", or runs /test-health. Advisory — writes a report, does not edit.
+role: worker
+user-invocable: true
+argument-hint: "[--path <dir>] [--pdf] [--no-mutation]"
+---
+
+# Test Health
+
+Role: worker. This command produces a strategic test-health report — it does
+not edit code or tests; fixes go to `/apply-fixes`, refactors to `/plan` /
+`/build`.
+
+## Overview
+
+An **advisory, project-wide** skill: it produces the *strategic-health* view of a test suite that a team needs periodically — the suite's **shape** vs. its architecture, **Agile Testing Quadrant** coverage, **coverage + mutation** health rolled up to ROI, flaky-test management, and **automation maturity** — then an ordered improvement plan. It complements, and does not duplicate, `cd-test-architecture`: that skill owns the CD-determinism + pipeline-placement assessment, which this skill **delegates to** rather than re-deriving.
+
+Grounded in: `knowledge/testing-quadrants.md`, `knowledge/test-pyramid.md` (shapes + shape↔architecture fit), `knowledge/test-automation-maturity.md`, `knowledge/test-smells.md` (project smells / flakiness), and `knowledge/test-automation-principles.md` (the goals/principles that frame *why* a project smell hurts — e.g. Developers Not Writing Tests, Frequent Debugging → lost Defect Localization). It calls the `cd-test-architecture`, `/test-design`, and `mutation-testing` skills and folds their results into the strategic rollup.
+
+## Constraints
+
+- **Advisory only.** Write a report; do not edit code or tests. Hand fixes to `/apply-fixes`, refactors to `/plan` / `/build`.
+- **Delegate, don't re-derive.** The architecture/pipeline section comes from `cd-test-architecture` — summarize its output, never restate or contradict its CD-determinism findings.
+- **Strategic altitude.** This is a suite-level diagnostic. Per-file findings belong to `test-review` / `test-smell-review`; per-unit design belongs to `test-design-advisor`. Point to them; don't reproduce them.
+- **No scoring reinvention.** Quantitative quality scoring and per-file design findings come from `/test-design` (Farley Score + test-review / test-smell-review) — consume them; summarize the themes and link to its report, don't re-derive or reproduce the per-file table.
+- **Be concise.** One report; findings as tables, each item mapped to a concrete next move. No restating the knowledge files — cite them.
+
+## Parse Arguments
+
+Target repo/subtree path (default: cwd). Detect the test runner, coverage tool, and CI config from manifests and `.github/`/`.gitlab-ci.yml`/etc.
+
+Optional:
+
+- `--path <dir>`: audit only this subtree (default: cwd).
+- `--pdf`: also render the report to a sibling PDF (Step 9).
+- `--no-mutation`: **skip the `mutation-testing` invocation in Step 5** and
+  render the report's mutation column as `not enabled for this run`. Everything
+  else in Step 5 (the `/test-design` dispatch and its roll-up) is unchanged.
+  Default **off** — an unflagged `/test-health` runs mutation ROI exactly as
+  before, because mutation health is a real part of the standalone strategic
+  audit. The flag exists for a caller that has already decided mutation work is
+  out of scope for its run and would otherwise pay for a measurement it then
+  discards: `/test-improve` Phase 1 passes it when `phase-0.md` recorded
+  mutation mode `off` (#1961). A skip is **not** a waiver and not a failure —
+  the target was never in scope for this run.
+
+## Steps
+
+### 1. Trivial-suite short-circuit
+
+If the suite is tiny (few test files), shows no shape pathology, and follows clear conventions, **stop here** and return a one-paragraph summary ("suite is small and healthy; nothing structural to fix; revisit when it grows") instead of the full diagnostic.
+
+### 2. Derive the test shape + architecture fit
+
+Inventory tests by layer (unit / integration / component / contract / E2E). Derive the actual **shape** and compare it to the shape the architecture *should* produce, using the *Other shapes* + *Shape ↔ architecture fit* tables in `test-pyramid.md`. Report the mismatch (e.g. tall pyramid over thin-glue code, or ice-cream cone), not the silhouette alone.
+
+**Graph-assisted inventory.** Prefer CodeGraph/Repowise over raw `Grep` for mapping test files to the architecture layers they exercise — see [`knowledge/codegraph-vs-graphify.md`](../../knowledge/codegraph-vs-graphify.md) for tool selection and the fallback contract.
+
+### 3. Quadrant coverage
+
+Classify coverage across the four quadrants (`testing-quadrants.md`) as strong / thin / empty, and for each gap name the **business impact** of leaving it empty (e.g. empty Q3 → no human catches confusing flows; empty Q4 → non-functional failures reach prod).
+
+**Gherkin scenarios as a Q2 signal.** Run `python3
+${CLAUDE_PLUGIN_ROOT}/scripts/detect_bdd_convention.py` (the same detection
+`/gherkin-derive` and `/plan` already use) to locate the project's
+`.feature` directory. When a directory is reported, enumerate its scenario
+titles (`Scenario:` / `Scenario Outline:` lines) and count them as an
+additional Q2 (business-facing) signal alongside any existing
+business-facing tests — a documented scenario counts toward Q2 strength
+whether or not it is yet bound to a runnable test; binding status feeds
+Step 7's gap classification, not this step's strong/thin/empty call. When
+`detect_bdd_convention.py` reports no signal, Q2's classification is
+unaffected — it falls back to the existing business-facing-test-based
+signal only, with no error and no placeholder text.
+
+### 4. Delegate architecture + pipeline
+
+Invoke `cd-test-architecture` on the target. Summarize its findings (which tests can't run in a clean pre-merge gate, target architecture, migration path) in one section — **do not re-derive**.
+
+### 5. Test-design + mutation health (ROI)
+
+Invoke `/test-design` on the target, passing the same scope this run was
+invoked with — the dispatch must be explicit so a subtree audit never
+inherits a whole-repo Farley Score:
+
+- `/test-health --path <dir>` → dispatch `/test-design --path <dir>`.
+- `/test-health` (unscoped) → dispatch `/test-design` with no scope flag.
+
+Consume its results: the scope-labelled **Farley Score** (`(all tests)` when
+unscoped, `(under <dir>)` when passing `--path`, or the empty-scope note
+`no in-scope test files` when the in-scope set is empty), the dominant
+`test-review` / `test-smell-review` themes (weak assertions,
+non-determinism, fixture/structure smells, testability blockers), and the
+advisor's testability verdicts. Then invoke `mutation-testing` on the
+**critical-logic** modules only (not the whole repo — that's the ROI
+framing).
+
+**`--no-mutation` skips that invocation entirely (#1961).** When the flag is
+set, do not run `mutation-testing`, do not estimate a mutation figure to stand
+in for it, and render the report's mutation content as `not enabled for this
+run`. The rest of this step is unaffected — `/test-design` still runs and its
+themes still feed the ordered plan (Step 8), which simply carries no
+mutation-hotspot input for this run. Without the flag (the default), invoke
+`mutation-testing` as above.
+
+Roll both up: where is coverage high but mutation-weak
+(assertions that don't catch bugs)? Where do test-design smells
+concentrate? Where is critical logic under-covered? Prioritize by risk,
+not by raw %. Both feed the ordered plan (Step 7) — summarize the themes
+and link to the `/test-design` report for per-file detail; do not
+reproduce it.
+
+### 6. Flaky-test + automation maturity
+
+Flag flakiness signals (`test-smells.md` project/behavior smells: order-dependence, unstubbed clock/RNG, real I/O at unit level) and a management recommendation (quarantine + fix, don't `retry`). Assess automation maturity with `test-automation-maturity.md`: report the rung and the single-point-of-change metric, scaled by suite size (graduated thresholds).
+
+### 7. Classify gaps + recommend removals
+
+Classify every gap the audit surfaces into one of three **actionable** classes, plus one **non-actionable** class reserved for behavior that doesn't exist yet (see Gherkin gaps below), so the improvement plan (Step 8) only ever plans work that delivers signal:
+
+| Class | Meaning | Action |
+| --- | --- | --- |
+| `NO_REFACTOR` | A test can be added against the code as it stands | Plan it |
+| `REFACTOR_REQUIRED` | Production code needs a testability change before a meaningful test is possible | Plan the production-code change first |
+| `LOW_VALUE` | Technically feasible but delivers no signal — **skip, never plan** | List for removal, not for work |
+| `NOT_IMPLEMENTED` | The scenario's behavior doesn't exist in production code at all — not a testability gap | Feature-gap call-out for the product backlog, never a test-improve target |
+
+A finding is `LOW_VALUE` only when **all three** hold:
+
+1. **No branching logic** — trivial getters/setters, pass-through constructors, framework boilerplate, or auto-generated code.
+2. **No observable outcome** — the only assertion possible is that a mock was called.
+3. **Coverage already provided** — a higher-layer test already exercises the same path.
+
+For existing tests that meet all three criteria, emit a **Recommended removals** table: the redundant test, the higher-layer test that already covers it, and a one-line rationale. These are the suite's `LOW_VALUE` tests — keeping them costs maintenance for no defect-localization gain.
+
+**Gherkin gaps (tag `gherkin-gap`).** A documented Gherkin scenario surfaced
+in Step 3 with no bound step-definition (`bdd-runner` mode) or cited xUnit
+test (`xunit-with-annotations` mode) classifies `NO_REFACTOR` when its
+behavior already exists in production code and a test can be added against
+it as-is. It classifies `REFACTOR_REQUIRED` when the behavior exists but
+needs a testability seam first (interface extraction, DI point, virtual
+method promotion) — the same kind of seam-only change `/test-improve`'s
+Phase 7 is scoped to perform.
+
+**When the scenario's behavior doesn't exist yet in production code at
+all, classify it `NOT_IMPLEMENTED` instead — neither `NO_REFACTOR` nor
+`REFACTOR_REQUIRED` applies.** Phase 7 accepts seam introductions only —
+implementing new behavior is explicitly out of its scope — so routing a
+`NOT_IMPLEMENTED` scenario through `REFACTOR_REQUIRED` would dead-end there
+with no seam to introduce. Tag it `gherkin-gap` as usual, mark it
+`NOT_IMPLEMENTED` in the Gap classification table's Class column, and carry
+it into Step 8's ordered improvement plan as a feature-gap call-out for the
+product backlog — never as a refactor-for-testability item, and never
+written as a Phase-5 Story or deferred to Phase 7 by `/test-improve`.
+
+**Discriminator: judge existence against the `Then` outcome, not the
+`Given`/`When` setup.** If no production code path can produce the asserted
+outcome, the behavior does not exist even when the surrounding
+`Given`/`When` code does. Split a partially-implemented Scenario Outline
+per example row — some rows can be `REFACTOR_REQUIRED` while others are
+`NOT_IMPLEMENTED`. When existence is genuinely ambiguous, default to
+`NOT_IMPLEMENTED`: an over-classified feature gap is inert and visible in
+the report, whereas an over-classified `REFACTOR_REQUIRED` dead-ends at
+Phase 7 with no seam to introduce.
+
+Use this exact wording for the finding's Meaning/Action for the
+`NO_REFACTOR`/`REFACTOR_REQUIRED` cases:
+
+> **Meaning:** "documented Gherkin scenario '<title>' has no bound step-definition or cited test yet." **Action:** "implement the missing binding/test before treating this area as low-risk."
+
+For the `NOT_IMPLEMENTED` case, use this wording instead — it must never
+tell the operator to add a binding/test, since there is no behavior yet to
+bind one to:
+
+> **Meaning:** "documented Gherkin scenario '<title>' describes behavior that does not exist in production code yet." **Action:** "implement the behavior via the product backlog; the binding/test follows once it exists — this is not a /test-improve target."
+
+A Gherkin gap can never qualify as `LOW_VALUE`: a documented scenario has an
+observable outcome by construction (its own `Then` steps assert one), so it
+always fails criterion 2 above. `NOT_IMPLEMENTED` and `LOW_VALUE` are
+mutually exclusive for the same reason `LOW_VALUE` never applies to a
+Gherkin gap.
+
+### 8. Ordered improvement plan
+
+Produce a risk-ordered, incremental plan — each item a concrete next move (which layer to add, which shape to correct, which quadrant to fill, which abstraction to extract, which weak-assertion or smell cluster to fix), driven by the test-design themes and mutation hotspots from Step 5. `LOW_VALUE` findings never appear here — they live only in the Recommended removals table.
+
+`NOT_IMPLEMENTED` findings never appear here either — no test-improvement move can close a scenario whose behavior doesn't exist yet, so it can never satisfy "a concrete next move." List them instead in a dedicated **Feature gaps (product backlog)** call-out beneath the ordered plan, and never count them in the risk ordering.
+
+### 9. Report
+
+Write `.dev-team-reports/test-health-<date>.md`.
+
+When `--pdf` was passed, render that report to a sibling PDF per
+`knowledge/report-pdf-integration.md` (additive; non-fatal if no engine):
+
+```bash
+sh "$CLAUDE_PLUGIN_ROOT/hooks/py.sh" "$CLAUDE_PLUGIN_ROOT/hooks/lib/report_pdf.py" .dev-team-reports/test-health-<date>.md
+```
+
+## Output
+
+For the header block and closing Provenance section, follow
+`knowledge/report-template.md`; the sections below are this skill's own
+body.
+
+```markdown
+# Test Health
+
+**Date**: <ISO 8601>
+**Target**: <repo>
+**Tool versions**: <coverage tool, mutation tool versions — or _Not applicable — <reason>._>
+**Scope**: <full repo | --path <dir>>
+
+## Test Health — <repo> (<date>)
+
+**Shape**: <derived> · **Expected for this architecture**: <expected> · **Fit**: <match|mismatch + why>
+
+### Quadrant coverage
+| Quadrant | Status | Gap impact |
+
+### Architecture & pipeline (via cd-test-architecture)
+<one-paragraph summary + link to its report>
+
+### Test-design & mutation health (via /test-design + mutation-testing)
+<When `--no-mutation` was passed, this section's mutation content reads
+`not enabled for this run` — never a number, never a waiver.>
+<Farley Score — render the scope-labelled value from `/test-design`
+verbatim (`(all tests)` when this run is unscoped, `(under <dir>)` when
+`--path` is set), or the literal `no in-scope test files` when the in-scope
+set was empty; do not synthesize a number. Top test-design themes ·
+mutation ROI hotspots · under-covered critical logic>
+
+### Gap classification
+| Gap | Class (NO_REFACTOR / REFACTOR_REQUIRED / LOW_VALUE / NOT_IMPLEMENTED) | Note |
+
+### Recommended removals (LOW_VALUE existing tests)
+| Test to remove | Covering test | Rationale |
+
+### Flakiness & automation maturity
+<flaky signals + management rec · maturity rung · single-point-of-change metric>
+
+### Improvement plan (ordered)
+1. <highest-leverage move> …
+
+### Feature gaps (product backlog)
+<NOT_IMPLEMENTED gherkin-gap findings only — never a numbered plan item;
+omit this section entirely when there are none>
+- <gap> — <one-line rationale for why the behavior doesn't exist yet>…
+
+## Provenance
+
+- Repository: `<repo path>`
+- Branch / SHA: `<branch>` / `<sha>`
+- Run parameters: `<flags — e.g. --path <dir>>`
+- `dev-team` plugin version: `<plugin_version>`
+```
+
+## Integration
+
+- **Front door** for periodic test-strategy review; the unified entry point that runs `cd-test-architecture` + `/test-design` + `mutation-testing` and rolls their results into one strategic view.
+- `/test-design` runs inside this flow (Step 5) and also stands alone for a focused per-file review. For *forward* design of a specific module, use `test-design-advisor`. This skill is the strategic rollup that consumes their output.