Nextreme Tdd

Nextreme TDD — The Extreme Red-Green-Refactor Engine

This skill produces behavior-pinned, red-proven, refactor-safe TDD cycles that survive review: opened in pytest, Vitest/Jest, go test, or cargo test without out-of-order code, bloated fixtures, or green-theater tests. Every cycle is a valid behavior → RED → GREEN → REFACTOR with disciplined naming, measured minimalism, and machine-checked order. You get three deliverables: the failing test (RED proof), the minimal implementation (GREEN), and the validation proof (verify_tdd.py log).

You are extreme and unbound inside the behavior — the user does not pick the test shape — you do, per behavior from content. A pure function gets a table-driven example; a stateful handler gets a characterization + invariant; an API boundary gets a contract + edge palette. If they hand you production code first, you don't lecture — you scaffold its characterization test. If they give you one sentence, you pin the behavior from scratch before a line of production code exists.

Why This Is Not Generic

Most TDD coaching is bounded: one paragraph, one example, no harness — so every run drifts into test-after, vague assertions, and fixtures that hide the behavior. Generic "write a test" prompts are order-blind: they generate code before proving RED, they assert any truthiness, they batch five behaviors in one test, and they never re-run.

This fuses the very core of the 4 best TDD systems on GitHub (2026) and refuses their bounds.

If the behavior wants a better test shape that no reference names (e.g., property-based shrink inside a unit), invent it — but keep it behavior-pinned, RED-proven, and verify_tdd.py clean.

Golden Code Quality Rules — ENFORCED

These are non-negotiable. Every test and every script this skill ships must pass them. Violation = task fails.

Keep code human-readable, small, and obvious. No AI slop.

• Names tell the truth — variables/functions reveal intent. No data, info, result, handler, manager, helper, utils, foo. A function that asserts tax rounding is assert_tax_rounds_half_up, not check_result.
• One job per unit — if you need "and" to describe what a function does, split it. A test that asserts parsing and persistence is two tests. Files own one domain.
• Guard clauses over nesting — early returns, fail fast. No pyramids, no else after return. Nesting past 2–3 levels is a signal to restructure.
• No duplication — never copy-paste. Third occurrence of the same assertion helper = must abstract. Two is coincidence, not a pattern.
• No dead weight — zero dead code, commented-out code, console.log, unused imports/vars. Delete, don't comment out.
• Types are contracts — no any, no silent as casts, narrow unknown explicitly. At an untyped boundary (JSON.parse, third-party API), a cast is allowed only alongside visible runtime validation.
• Errors never silent — every failure path is handled, returned, or logged with context. Never an empty catch, never a swallowed promise. A failed detect_framework logs what it looked for and where.
• No magic — no unexplained numbers or strings. Name every constant. No cryptic one-liners. MAX_ASSERTS_PER_TEST = 3 not 3.
• Explicit dependencies — no hidden globals, no surprise side effects. Inputs in, outputs out. Pure where possible.
• Readability > cleverness — code reads like prose: linear flow, consistent style, self-documenting. Comments explain why, not what.
• No premature abstraction — no wrappers, layers, or helpers you don't need today. YAGNI. Abstract on the real second pattern.
• Leave it cleaner, not bigger — boy-scout only on touched code.
• State assumptions, don't guess silently — if the spec is ambiguous, say what you assumed and why, in a comment or PR note.

Auto-rejected AI slop: placeholder TODO without a ticket, generic scaffolding, empty try/catch, lorem-ish names, duplicated boilerplate, over-engineered factories/managers, unvalidated as casts at boundaries, silent assumptions about ambiguous specs, inconsistent style within one file, and TDD-level slop: a test that never failed, an assertion on truthiness (expect(x).toBeTruthy()), a tautological assertion that recomputes the expected value (expect(add(a, b)).toBe(a + b)), a test at an unconfirmed seam (mocks internals, tests privates, verifies via side channel), five behaviors in one test, a fixture that hides the behavior, any in the test, production code committed before RED log, a weakened test between RED and GREEN (deleted assertion, added .skip, loosened matcher), a refactor without a green suite re-run.

Framework Selection — You Decide

All ship: scripts/detect_framework.py + scripts/scaffold_test.py + scripts/verify_tdd.py. You choose per repo — state the one-line justification (e.g., "found pyproject.toml → pytest" or "found package.json with vitest → Vitest").

Reference: references/framework-matrix.md — manifest → framework map, install, and RED/GREEN commands.

Core Workflow — Behavior-Pinned, Order-Enforced

Each step ends on a completion criterion. Do not proceed until it passes.

1. Triage — What Is This Behavior For?

Ask or infer: what user-visible behavior does this cycle lock down, who is the client, and what unit owns it (function, class, route handler)? Extract: behavior name (verb phrase), owning contract/file, and what's not in this cycle. If production code already exists, mark the order inverted — you will start with a characterization test, not a feature test.

Reference: references/test-patterns.md — behavior naming + scope.

Completion criterion: one sentence — "When <client> does <action>, <unit> shall <outcome>" — plus the target file/symbol; no production code written.

2. Detect — What Framework Owns This Repo?

Run the detector; don't guess.

python ${CLAUDE_SKILL_DIR}/scripts/detect_framework.py --json
# local clone:
python nextreme-tdd/scripts/detect_framework.py --json
# → { "framework": "pytest", "manifest": "pyproject.toml", "test_dir": "tests", "command": "python -m pytest -q" }
# flags: --manifest <path> (override), --framework pytest|vitest|jest|go|cargo (force)

It scans manifests (pyproject.toml, package.json, go.mod, Cargo.toml), lockfiles, and tests//src/ conventions. If ambiguous, it prints candidates and exits non-zero — you pick and pass --framework.

Reference: references/framework-matrix.md — detection rules + manual override.

Completion criterion: detector exits 0 with one framework + one GREEN command + one test path; or you logged the assumption ("no manifest, defaulting to pytest per *.py").

3. Pin — Name The One Behavior

Pin exactly one behavior for this cycle. Use the leading word behavior — every decision in this skill is "which behavior, what case of that behavior, what asserts that behavior." Write the behavior contract: inputs, outputs, invariants, and the edge palette this behavior earns (see reference). Confirm the seam (the public boundary the test observes — see references/test-patterns.md) with the user before RED; in fast mode state the assumed seam in one line.

• One behavior = one test file or one describe/Test block, not five.
• Name it truthfully: calculate_tax_rounds_half_up, not test1.
• If the repo already has the implementation, pin its observable behavior for a characterization test (input → output, no peeking at internals).

Reference: references/test-patterns.md — behavior contract template + edge palette (happy / edge / error / invariant).

Completion criterion: behavior contract written (inputs → outputs + invariants) and the file/symbol under test is named; the next step knows exactly what RED must prove.

4. RED — The Smallest Failing Test

Scaffold, then make it fail for the right reason.

python ${CLAUDE_SKILL_DIR}/scripts/scaffold_test.py --behavior "<behavior>" --case "<first-case>"
# → writes tests/test_<behavior>.py (or .test.ts / _test.go) from templates/

Edit the scaffold to the smallest assertion that captures the behavior. Run it and prove RED:

python -m pytest tests/test_<behavior>.py -q      # or vitest run --reporter=verbose / go test -run TestBehavior / cargo test
# expect: FAILED / unknown symbol / wrong result — not a typo

The failure must be the behavior gap (missing symbol or wrong value), not a syntax/import typo. Fix typos until the test fails honestly, then stop — don't "fix" it to green.

Reference: references/validation.md — what counts as honest RED.

Completion criterion: one test exists, it fails, you pasted the failure (unknown symbol or assertion diff), and verify_tdd.py --phase red would exit 0. No production code touched.

5. GREEN — The Smallest Passing Change

Write the minimal production code to turn that one test green. No extra branches, no speculative generalization — only what the failing assertion demands. The test file is frozen from here: if red persists, fix the implementation, never weaken the test (see references/validation.md §8). Watch for hardcoded values that pass one test and fail the next (if input == '1h30m' return 5400) — catch them now via triangulation, not three tests later. Run the full suite, not just the new test.

python -m pytest -q
# or vitest run --reporter=verbose
# or go test ./...
# or cargo test

Confirm: the new test passes and the suite is green. If the suite is red, fix — don't commit on red. If the fix feels clever, it's too big; shrink to the smallest that passes.

Completion criterion: the pinned test passes, the full suite is green (paste the GREEN log), and the diff is the smallest that achieves it. verify_tdd.py --phase green exits 0.

6. REFACTOR — Clean Under Green

Only now, with green protecting you, clean what this cycle touched: remove duplication you just introduced, name truths, drop dead weight, tighten types. After every tweak, re-run; stay green. Stop the moment the code is clean, not when it is clever. Do not add behavior in REFACTOR — if you see a new case, park it for the next behavior cycle.

Completion criterion: the suite stays green through every refactor tweak; duplication/dead weight from the cycle is gone; no new behavior added; verify_tdd.py --phase refactor exits 0 (green still, diff is net cleaner).

7. Verify — Prove The Order

Run the bundled verifier — it checks what eyes miss (order, not just color):

# skills.sh:
python ${CLAUDE_SKILL_DIR}/scripts/verify_tdd.py --strict
# local clone:
python nextreme-tdd/scripts/verify_tdd.py --strict
# flags:
# --phase red|green|refactor : check only that phase (CI-friendly)
# --since <sha>               : diff since sha (proves no prod before RED)
# --framework <name>          : override detection

It checks: RED log exists and is a behavior-gap failure (not typo), no production diff before RED timestamp, GREEN log is full-suite green, no any/truthiness-only assertions, assertions match the pinned behavior, and no batch-of-behaviors in one test (see references/validation.md).

Fix every error and rerun until clean. If code execution unavailable, use the manual checklist in references/validation.md.

Completion criterion: verify_tdd.py --strict exits 0 and you can show RED log + GREEN log + the behavior name in one glance.

8. Deliver — Behavior + Proof

Always:

1. The RED test — the smallest failing test that now passes (commit shows RED → GREEN).
2. The minimal implementation — the production diff that satisfied it.
3. The proof — RED log, GREEN log, verify_tdd.py output, and the one-line behavior sentence.

Commit every green cycle — small green commits are the save points later cycles reset to. Do not deliver a refactor as a "feature." Do not batch three behaviors into one cycle — one behavior per cycle, tracer bullets, not cannonballs.

Quick Picks — Starter Templates

Copy a template from templates/ and fill; do not start from zero. Each is valid, runnable, and uses the framework's idioms — not filler.

All templates are behavior-pinned (one behavior per file/describe), assertion-true (__behavior__ placeholder fails honestly), and framework-correct. See references/framework-matrix.md for where each template lands.

Troubleshooting — No Glitch Is "Weird — Ignore It"

Reference Files

• references/test-patterns.md — behavior contract template, edge palette (happy / edge / error / invariant), example vs property guidance, naming truthfully.
• references/framework-matrix.md — manifest → framework map, install, scaffold destinations, and RED/GREEN commands.
• references/validation.md — strict checklist: honest RED, no prod before RED, suite green, no any/truthiness, one behavior per test, batch detection, test-freeze.
• references/activation.md — hooks that make the loop fire unasked: prompt-eval reminder, post-change suite run, stop gate.
• scripts/detect_framework.py — repo → framework + test dir + command (manifest scan, --json, --framework override).
• scripts/scaffold_test.py — behavior + case → templated test file (framework-aware destination + __behavior__ placeholder that fails honestly).
• scripts/verify_tdd.py — order + quality gate: RED proof, no-prod-before-RED, suite green, assertion fidelity, batch guard.
• templates/ — 4 starters: python-pytest.test.py, typescript-vitest.test.ts, go.test.go, rust.test.rs (plus README.md).

Principles — The Nextreme Signature (Unbound, but Not Unruly)

• Behavior is the tracer bullet. One behavior per cycle, one tracer at a time. "Which behavior?" is answered, not shrugged — and the next cycle answers it again.
• RED before GREEN is law, not advice. If production code lands before RED proof, the cycle is void — the verifier fails it, not a human. Order is the contract.
• Smallest GREEN wins. The pass that teaches the least teaches the most — the refactor under green cover is where taste lives, not in a clever premature abstraction.
• No truthiness theater. An assertion that would pass for the wrong value is a failed test. Assert the behavior's value, shape, and error — not its existence.
• You decide the shape — but you justify. Every framework/template/assertion choice ties to one line about the behavior. "Why this case?" is answered, not vibed.
• No glitch is minor. One unproven RED / one truthy assertion / one batch-of-five test is a credibility leak. Zero is the bar.