test-driven-development

name

test-driven-development

description

Test-driven development specialist for engineering-verification-loop. Use directly or when routed for Go/Python features, bug fixes, behavior-preserving refactors, legacy characterization, or behavior-affecting API, CI, performance, formal-correctness, and distributed changes that need auditable Red-Green-Refactor evidence, requirement-to-test traceability, regression scope, coverage, mutation, and flake controls. Not for formal proof, API compatibility analysis, profiling, distributed model checking, or CI log forensics.

Test-Driven Development

Operating Contract

Drive every observable behavior change through a recorded development cycle before accepting outer verification gates. Map requirements to acceptance criteria and stable test IDs, establish a valid Red or baseline Green, make the smallest behavior-preserving or behavior-producing edit, and finish with targeted and regression Green evidence.

Never manufacture Red by breaking imports, compilation, dependencies, fixtures, or the environment. Never make Green by changing the test selector, deleting or skipping the failing test, weakening its assertion, or accepting a zero-test run. Capture gate execution with evl run-gate; do not hand-author command outcomes that the runner can record.

Bind every auditable phase to immutable Git evidence. Base/candidate revisions and snapshot heads are real, resolvable 40/64-character hexadecimal commit IDs; each snapshot tree is the corresponding Git tree ID. WORKTREE is never valid Bundle 2.0 evidence.

Change Modes

Change	Required mode	Entry evidence	Exit evidence
Feature or bug fix	red_green_refactor	Expected assertion failure for the new behavior	Same targeted selector Green, refactor decision, then targeted, affected, and full regression Green
Covered refactor	green_refactor	Existing relevant tests Green	Refactor decision, then the same targeted, affected, and full regression scopes Green with unchanged observable behavior
Uncovered legacy refactor	characterization_refactor	Characterization tests capture current behavior and pass	Refactor decision, then targeted, affected, and full regression preserve the characterized behavior
Non-behavioral work	waived	Structured reason and changed-path evidence	Restricted conclusion only; do not claim behavioral readiness

Use a waiver only for documentation, metadata, generated output whose source is tested, or a time-boxed exploratory spike that will not ship. Treat configuration, migrations, dependency changes, generated-source changes, and test-only edits that alter coverage or assertions as potentially behavioral until demonstrated otherwise.

Workflow

1. Inspect requirements, changed paths, existing tests, public contracts, and project-native test commands.
2. Declare the change type, TDD mode, requirements, acceptance criteria, stable test IDs, test levels, selectors, and regression scope in the TDD plan.
3. Select the narrowest supported test level that observes the contract without coupling to implementation details: unit, component, integration, contract, e2e, property, fuzz, characterization, or benchmark. Add integration, contract, or end-to-end coverage when a unit test cannot cross the changed boundary.
4. Execute the mode:
   • feature/bugfix: add the test first and capture a valid Red;
   • covered refactor: capture baseline Green before production edits;
   • uncovered refactor: add passing characterization tests before production edits;
   • waiver: record the reason, paths, reviewer, expiry when applicable, and restricted conclusion.
5. Before Red executes, declare both the expected failure class and normalized signature. Run only native structured test argv after -- with evl run-gate; require the intended test ID to execute and fail with that predeclared contract.
6. Make the minimum implementation change that satisfies the acceptance criterion. Run the exact normalized targeted selector again and require a nonzero executed-test count, no unapproved skips, and Green.
7. Record refactoring as performed or not_needed. Do not add behavior during this step. For performed, capture the refactor phase by re-running the targeted tests; for not_needed, proceed to targeted regression with the decision recorded.
8. Run the declared affected suite and full regression suite. Preserve machine-readable test reports, coverage, mutation, and rerun artifacts when the project supports them.
9. Route additional risks through the outer specialists. A passed TDD cycle does not replace formal proof, compatibility, profiling, reproducibility, conformance, or distributed-model evidence.
10. Audit the final Evidence Bundle 2.0 with evl audit. Stop if any acceptance criterion, cycle phase, regression scope, or active outer risk lacks valid evidence.

Use the runner as evl run-gate --bundle BUNDLE --cycle ID --phase PHASE --adapter ADAPTER --selector SELECTOR [failure/refactor options] [--repeat N] [--attach KIND=PATH ...] -- COMMAND ARG.... Valid phases are red, green, baseline_green, refactor, targeted, affected, and full. For Red, also provide --expected-failure-class, --expected-signature, and one or more --expected-test values; Red cannot be repeated. Use --repeat 3 on a passing Green/regression phase to capture the initial attempt plus two flake reruns. Attach only reports produced by that execution. Read evl run-gate --help for all options. The project-native argv must appear only after --, and the runner must never execute a command string read from the bundle.

For every non-waived TDD cycle, use the native pytest or go adapter; generic cannot establish any TDD phase. Pytest requires explicit python -m pytest ... with an explicit verbose flag such as -vv; direct pytest shims are rejected, and the recorded selector must be an explicit argv item. Go requires go test -json -count=1; each declared Go selector/observed ID uses the emitted Package value as <Package>::<TestName>. A Go targeted phase must bind the declared test name through -run; affected and full phases must not use -run.

Valid Cycle Evidence

Require all of the following:

• Each acceptance criterion maps to at least one stable test ID, and every declared test maps back to a criterion.
• Red and targeted Green use the same normalized selector and identify the same test contract.
• Red occurs before the implementation snapshot and fails for the expected behavioral assertion, not collection, build, import, dependency, timeout, or environment failure.
• Red changes only tests and fixtures unless a structured compile-stub exception identifies the minimal non-behavioral production declaration.
• Green executes at least one test, reports no unapproved skips, and retains or strengthens the Red assertion. Green, baseline Green, refactor, and regression phases run at the clean candidate revision and must preserve an identical before/after snapshot.
• Refactor status is explicit, and targeted, affected, and full regression executions occur in order.
• Execution provenance records repository revision/tree, diff hash, argv, allowlisted environment, timing, exit code, report counts, artifact path, and artifact SHA-256. Each phase retains the runner-generated snapshot provenance artifact referenced by provenance.snapshot.evidence_ref. Its diff_base64 decodes to canonical JSON material containing structured tracked {path, status, worktree} entries and untracked file/symlink entries; the auditor recomputes changed_paths from that material.

Load references/red-green-refactor-policy.md when validating phase evidence or handling compile-stub and waiver exceptions.

Test Sufficiency

Cover the acceptance contract, not merely the edited lines. Include positive, negative, boundary, state-transition, error, and concurrency cases when relevant. Prefer deterministic inputs and controlled clocks/randomness; preserve a reproducible seed for generated tests.

For this skill pack's core Python runtime, enforce at least 90% line coverage, 85% branch coverage, and 100% diff coverage on new core code. Enforce an overall mutation score of at least 85%, with no surviving mutants in readiness or fail-closed branches. Record justified equivalent mutants explicitly. Require quality_checks with deterministic execution, at least two flake reruns, zero flake failures, zero weakened assertions, and supporting artifact references. For external projects, apply the repository's stricter policy or declare project-specific thresholds before implementation.

Attach standard JSON coverage and mutation reports whose values match test_sufficiency.results; raw HTML/XML/text output is not sufficient for the audit. Load references/test-sufficiency.md for the required report shapes.

Reject all-skipped runs, quarantined new behavior tests, unexplained flaky reruns, assertion deletion/weakening, reduced boundary coverage, and coverage drops hidden by excluding changed files. Load references/test-sufficiency.md for the complete gates and references/test-strategy.md for level and framework selection.

Specialist Composition

• dafny-verification: prove formal_correctness properties after acceptance criteria and a valid behavioral Red are defined, but before production implementation.
• property-based-differential-testing: broaden implementation alignment after a trusted oracle or model exists; preserve minimal counterexamples as regression tests.
• api-contract-compatibility: check public wire/schema compatibility in addition to consumer-observable TDD tests.
• ci-regression-forensics: classify and reproduce a CI failure first; count it as Red only when it is an intended behavioral test failure with a stable local reproduction.
• profiler-guided-optimization and algorithm-selection-benchmarking: measure first, preserve behavior through TDD, then assess performance.
• tla-distributed-model-checking: model protocol semantics; use TDD for concrete handlers and externally observable scenarios.
• model-implementation-conformance: demonstrate that handwritten Go/Python follows the verified model after Green.

A passed outer-risk entry must cite a qualifying structured specialist JSON report. A behavioral test-log can support the TDD cycle but never substitutes for proof that the outer specialist gate ran.

Boundaries

Own acceptance-example design, test-level selection, Red-Green-Refactor discipline, characterization, regression scope, and test sufficiency. Do not claim formal proof, public-contract compatibility, CI root cause, performance improvement, distributed safety/liveness, or model-to-implementation conformance without the relevant specialist gate.

Resources

• references/red-green-refactor-policy.md: valid phase evidence, snapshots, exceptions, and failure handling.
• references/test-strategy.md: Go/Python test levels, selectors, test doubles, and regression-scope guidance.
• references/test-sufficiency.md: coverage, mutation, flake, boundary, and assertion-strength gates.
• assets/templates/tdd-plan.md: requirement-to-test and cycle planning template.
• assets/templates/tdd-cycle-report.md: phase evidence and regression reporting template.
• assets/templates/tdd-waiver.md: restricted non-behavioral waiver template.
• evals/cases/: structured forward-evaluation cases for routing and fail-closed behavior.