test-driven-development

name	test-driven-development
description	Use when the task involves any code implementation, bug fix, refactor, feature, integration, automation, API, UI behavior, or data-change task where tests or executable verification can be written. Enforces APIVR Phase 3 test-first implementation with Red-Green-Refactor evidence gates and maps TDD shortcuts to APIVR evidence violations.
activation	Activate when the description trigger applies to the current task.
required_inputs	Task request, relevant repository context, constraints, and authority dependencies.
required_outputs	Skill-specific artifact, verification evidence, canonical verdict, and next action.
authority_dependencies	00_start_here/SOURCE_OF_TRUTH.md; 10_governance/APIVR_EXECUTION_LIFECYCLE.md; 10_governance/source_of_truth/Elite_Build_Goals_v3.md.
evidence_requirements	Executed checks or an honest Unknown, Not Run, or Blocked state for every material claim.

Test Driven Development

Use this skill during APIVR Phase 3 for code work.

Iron Law:

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

No production code change is allowed without a failing test or an explicitly documented evidence-first substitute approved by APIVR tier logic.

If production code was written before the failing test, stop and apply the delete-and-restart rule: preserve notes if useful, revert or quarantine the premature production change, write the failing test, watch it fail for the intended reason, and restart implementation from Red. Do not keep premature code as a reference, adapt it while writing tests, or call tests-after equivalent to TDD.

APIVR Integration

• Phase 1 Audit: identify behavior, risk, current coverage, and test surface.
• Phase 2 Plan: embed the failing test or executable verification in the plan.
• Phase 3 Implement: run Red-Green-Refactor.
• Phase 4 Audit Implementation: inspect tests for false confidence, weak assertions, skipped paths, and fixture abuse.
• Phase 5 Verify Implementation: run targeted and relevant broader checks.
• Phase 6 Re-Audit: confirm no collateral regression or unverified claim remains.

Red-Green-Refactor Evidence Cycle

flowchart LR
  R["RED: write focused failing test"] --> RV{"Failure proves missing behavior?"}
  RV -- "No" --> R
  RV -- "Yes, Verified" --> G["GREEN: smallest production change"]
  G --> GV{"Target test passes?"}
  GV -- "No" --> G
  GV -- "Yes, Verified" --> F["REFACTOR: improve safely"]
  F --> FV{"Relevant tests still pass?"}
  FV -- "No" --> G
  FV -- "Yes, Verified" --> A["APIVR Phase 4 audit"]

Evidence after each phase must use the kit evidence language: Verified, Likely, Suspected, Unknown, Not Run, or Blocked. If automation is genuinely non-applicable, record an applicability note plus the best available evidence state. Do not treat manual inspection as Verified automated behavior.

The Red phase is not complete until the failing test was actually run and observed failing for the intended reason. A test that passes immediately is not Red evidence. A test that errors because of a typo, broken setup, missing import, or invalid fixture is not Red evidence.

Public-Interface And Vertical Tracer Rule

Prefer tests that prove behavior through the public interface of the module, API, CLI, UI, or workflow. Avoid testing private implementation details unless the private surface is the only practical risk boundary.

For new features, start with a vertical tracer bullet: one thin behavior that crosses the real boundary and can fail for the right reason. Do not batch a large horizontal pile of tests before proving the first user/system behavior can go Red, Green, and Refactor.

Fix the bug, click through the page, then add a broad snapshot test. Write `rejects expired reset token` first, run it and observe failure, implement token expiry validation, rerun the targeted test, then run the auth regression suite.