Tdd Workflow

---
name: tdd-workflow
description: "Framework-agnostic test-driven development guidance for behavior-first unit and integration tests, test scaffolds, and minimal RED-GREEN-REFACTOR changes. Use when building a feature or fixing a bug test-first, writing a test scaffold, or reviewing test seams and mocks; reuse adequate test-first evidence and settled ownership. Not for: Playwright journey authoring or pure documentation or rename work. Explicit tdd-guide requirements remain binding. Output: a failing-test proof, minimal implementation/test change, scoped verification, and a concise TDD report."
metadata:
  dhpk-invocation-class: "implicit-eligible"
---

# Test-Driven Development

## Test-generation mode

When invoked with `test-generation`, inspect the named production seam and its
existing test conventions, then generate the smallest behavior-focused test
scaffold. The caller must review and run the generated test before claiming a
GREEN result. This is the canonical replacement for the retired
`/codex-test-gen` command; use an explicitly selected Codex backend only when
the caller requests one.

Use this skill to keep tests attached to observable behavior rather than
implementation details. Read [tests.md](tests.md) when writing or reviewing
assertions and [mocking.md](mocking.md) before introducing a test double.

Before choosing names or seams, read `CONTEXT.md` when the repository provides
one and respect nearby ADRs. Keep test vocabulary aligned with the project's
domain language rather than inventing test-only names.

## Standard TDD mode

Use this mode for `tdd-guide` and any task that owns test strategy:

1. Identify the public interface and the behavior that should be observable.
2. Confirm the seam from the user request, approved plan, or dispatcher brief.
3. Write one small test for that behavior and run it before implementation.
4. Confirm RED fails for the intended missing behavior, not a test/setup error.
5. Write only enough production code to make that test GREEN.
6. Run the scoped test again, then refactor only while it remains green.
7. Repeat one vertical slice at a time; run the applicable full suite at phase
   exit rather than broad speculative tests on every loop.

Choose inline implementation or a worker handback from ownership, coupling,
the settled test seam, and material risk. A file count alone does not decide
the route. Preserve any explicit higher-priority instruction or acceptance
requirement that governs the task.

Tests must assert return values, emitted state, or caller-visible side effects.
Do not test private methods, internal call counts, or a value through a side
channel that bypasses the public interface. Expected values must come from a
literal, worked example, or independent specification; never recompute them
with the same logic as the implementation.

### Seams and slicing rules

- Name the **public seams** before writing the test: API, command, event, or
  other caller-visible boundary. Keep tests at that seam unless a genuine
  external boundary requires a narrow adapter test.
- Use **independent expected values** from a literal example or specification;
  a test that calls the same helper to compute its expected result is
  tautological and cannot detect a shared defect.
- Build **vertical tracer bullets**: one failing behavior through the real
  boundary and minimal collaborators, then expand coverage around the same
  path.
- Keep the loop vertical: one test, one minimal implementation, then one
  refactor while green. Avoid writing a horizontal batch of imagined tests
  before the first behavior is understood.
- Avoid **horizontal slicing** (all models, then all services, then all
  controllers). It delays feedback and encourages implementation-coupled tests.
- Reject **implementation-coupled** assertions on private names, incidental
  call counts, or internal data shape. A **tautological** test is a test smell,
  not evidence of coverage.

## Fast-worker mode

Use this mode when `fast-worker`, `codex-fast-worker`, or `dhpk-agy-fast-worker`
receives an approved task spec or a proven RED/GREEN handback from the settled
test owner:

1. Treat the dispatcher's target files, behavior, and verification command as
   the pre-approved seam and contract. Do not pause for another seam approval.
2. Apply only the specified GREEN or test-scaffold change. Do not invent new
   behavior, broaden the file list, or start an independent RED strategy.
3. Keep each test focused on one observable outcome and mock only external or
   otherwise unavoidable system boundaries; see [mocking.md](mocking.md).
4. Run the task's scoped verification command yourself and report the exact
   result and edited files. Escalate ambiguity instead of guessing.

The fast-worker mode preserves the mechanical GREEN worker boundary: the
settled test owner supplies RED evidence, seam selection, and test strategy.
Reuse adequate existing RED/GREEN evidence from inline or worker work when it
covers the current behavior and public seam. Resolve an unsettled test seam or
runtime setup with `tdd-guide` when separate specialist expertise is needed,
before dependent implementation. In dhpk, `rules/execution-policy.md` owns
ownership and dispatch decisions.
If the specialist is unavailable, a capable settled owner may supply the
equivalent test-first outcome only when applicable instructions allow it;
otherwise report `BLOCKED` with the missing role, seam or runtime capability,
and the action needed to resume. Explicit Host, user, acceptance, or
higher-priority requirements for `tdd-guide` remain binding.

## Tautological tests considered harmful

A passing test is not evidence when it can share the production defect. Ask:
"If the implementation and this test contained the same bug, would the test
still pass?" If yes, replace the assertion before counting the test as
coverage. [tests.md](tests.md) owns the independent-oracle, discrimination,
and ownership rules and the rejection checklist.

## When NOT to Use

- Use `e2e-runner` for Playwright user journeys, browser fixtures, and live
  journey stabilization.
- Use `change-verdict` for a post-hoc coverage or acceptance-criteria audit.
- Skip the TDD loop for pure documentation, rename, formatting, or harness
  configuration tasks that do not change testable runtime behavior.
- Reuse adequate test-first evidence and settled ownership for business
  features and bugs; dispatch `tdd-guide` to resolve a missing specialist
  outcome or satisfy an explicit applicable requirement.

## Mocking boundary

Mock external APIs, databases when a test database is impractical, time/random
sources, and file systems only when necessary. Prefer dependency injection and
specific SDK-like interfaces. Do not mock application classes merely to assert
that an internal collaborator was called; test the behavior at the public seam.

## Output

Report:

```text
Phase: RED | GREEN | REFACTOR | GREEN-HANDOFF
Verdict: PASS | WARNING | FAIL
Verification: <command> -> PASS | FAIL
Test files:
- <path>
Implementation: <none | changed files>
Coverage: <percentage | unavailable>
Notes: <reason for handoff, warning, or skipped refactor>
```

For fast-worker dispatches, retain the worker's canonical report contract and
include the TDD-relevant test/verification result in its existing report.

## Verification

- [ ] The RED test failed for the intended reason, or the worker received a
  previously proven RED/GREEN handback.
- [ ] The test asserts observable behavior at an agreed public seam.
- [ ] Expected values are independently derived and mocks are boundary-only.
- [ ] The scoped verification command passes.
- [ ] The applicable suite is run at phase exit and the result is reported.

## References

- [tests.md](tests.md) — behavior-focused good/bad test shapes,
  implementation-coupling traps, independent oracles, discrimination, and the
  rejection checklist.
- [mocking.md](mocking.md) — boundary mocking and dependency-injection rules.