git:20260617.174aad8 to git:20260713.d210701

23 added, 38 removed. Audit A to A.

---

name: create-test

- description: "Use when user wants to create tests, generate test coverage, audit test quality, find untested code, or improve weak assertions. Use when user says write tests, test coverage, missing tests, or untested code."

+ description: "Define or implement regression proof for a project or business flow. Use for test strategy, black-box or deep-integration tests, business KPIs and thresholds, test audits, missing tests, or test implementation."

argument-hint: "[file-or-directory-or-goal]"

user-invocable: true

- allowed-tools: Glob, Grep, Read, Bash, Agent, Edit, Write, AskUserQuestion

+ allowed-tools: Glob, Grep, Read, Bash, Edit, Write, AskUserQuestion

---

- # Create Test — Intelligent Test Design

- ultrathink

- Apply [Iron Rules](../../shared/iron-rules.md) — Principle 3 (plain pytest before any library), 7 (TDD; tests must find bugs, not just exist), 8 (no claim without fresh test output).

- Plus: test through the public API, never the internals; strong assertions only (never `assertNotNull(x)` alone); prefer property-based over hardcoded cases; never modify source code (only test files, conftest, fixtures); match existing project conventions.

- ## Argument Routing

- Parse `$ARGUMENTS`. Use Glob/Bash to check if it matches existing paths:

- - **Existing file(s)/directory** → Mode B for those paths

- - **Natural-language goal** (not a path) → Mode A with the goal; direct analysis toward it

- - **No arguments** → Mode A on the full project

- ## Mode A: Strategic Analysis

- Read `references/explorer-prompt.md`. Spawn an analysis subagent (Agent tool) with its contents as the prompt. If `$ARGUMENTS` carries a goal, append it and instruct the subagent to prioritize strategies serving that objective and explain WHY each helps.

+ # Create Test

- Display the returned analysis inline. The user then selects items (→ Mode B each), asks a follow-up (answer from context), or skips.

+ Start with what must remain true for the user or business, not with files, coverage, or internal calls. Inspect the project for facts; ask only for business decisions that cannot be discovered.

- ## Mode B: Targeted Generation

+ ## Define the regression contract

- Read `references/testing-strategies.md`.

+ For the whole project or the requested flow, establish:

- ### Step 0: Verify Test Infrastructure

- Confirm the test framework is installed/configured; if missing, ask before setting up.

+ - actors, goals, and externally observable outcomes;

+ - business rules and invariants that must never change;

+ - critical paths plus rejection, timeout, retry, permission, concurrency, and partial-failure cases that matter;

+ - the current baseline and every intended behavior change;

+ - KPIs or operational signals, with measurement window, data set, acceptable variance, and a justified pass/fail threshold;

+ - systems crossed, production-like data needs, and evidence the available environment can actually provide.

- ### Step 1: Read and Understand

- Read the target completely. For **Python**, also consult `../python-dev/patterns.md` (Test taxonomy) for the team-canonical 4-tier layout and pytest/async/mock conventions.

+ Do not invent a metric or threshold to fill a blank. Record it as an open decision or blind spot.

- ### Step 2: Implementation Analysis

- Per public function/method/endpoint, identify: boundaries (every comparison/limit → N-1/N/N+1, type coercion points); state space (branches, error/fallback/retry/timeout paths, states unreachable from current tests); invariants (round-trip, idempotence, monotonicity, ordering; a simpler reference oracle); API surface (schemas, status branches, CRUD lifecycle, error formats).

+ ## Choose the proof

- ### Step 3: Strategy Selection

+ Prefer the highest boundary that gives reliable feedback:

- Map each characteristic to a strategy via `references/testing-strategies.md` (canonical selection table). For TDD / test-first, confirm with the user which public-API behaviors matter most before writing — concentrate on critical paths and complex logic, not every edge case.

+ 1. black-box tests through the public API, UI, job, event, or CLI;

+ 2. deep integration with the real database, queue, connector, or protocol;

+ 3. contract, replay, property, or characterization tests for narrower risks;

+ 4. unit tests for isolated rules where a wider test adds no confidence.

- Also read: `references/refactoring-workflow.md` if refactoring; `references/regression-detection.md` for regression-detection infrastructure.

+ Use mocks only beyond the boundary being verified. For database or migration work, read [integration patterns](references/integration-patterns.md).

- ### Step 4: Generate Tests

- Strong assertions only (check `references/weak-assertion-patterns.md`). For golden-fixture / characterization patterns generate BOTH the capture script and the regression test.

+ When asked only for strategy or an audit, return a concise contract, prioritized scenario map, proof method, and remaining blind spots. Judge existing tests by the outcomes and failures they would catch, not assertion counts or line coverage.

- ### Step 5: Run and Verify

- Run, read output, fix the TEST not the source on failure. **Mutation check** each critical assertion: temporarily set the expected value wrong, confirm the test FAILS, restore. A test that passes with a wrong value is tautological — rewrite it.

+ ## Implement when asked

- ### Step 6: Report

- List strategies applied and what each covered, and the functions/paths deliberately NOT tested with justification.

+ Follow the project's test layout and development loop. Add the smallest test that proves the next important scenario, observe RED, make only approved source changes, then observe GREEN. Assert business outcomes, persisted state, emitted events, metrics, and error contracts rather than implementation calls. Run the focused test and the relevant suite; report what is now proven and what remains outside the evidence boundary.