tdd git:20261103.b008b6fA

Immutable. This exact content never changes and is served at /api/v1/blob/b2cc807841c8cacb.

---
name: tdd
description: "Design focused contract tests, failing-before regressions or verification of critical properties; use for requested TDD, model checking and verification drift, with practical boundaries and explicit evidence limits."
---

# TDD

Follow the consuming project's instructions and requested scope; use the
[portable defaults](../orbyn-workflow/references/project-policy.md) only where guidance is missing.

Respect tests excluded by the current user, session or consumer policy; this skill
grants no production or live-provider authority.

## Do we need a unit test here?

Decide before writing one. Tests are for where they earn their place.

| Situation | Choice |
| --- | --- |
| Deterministic code where a silent break is costly: moving or deleting files, secrets, money, stored data, parsing, security boundaries, or a fixed bug that could return | Unit test |
| Agent behaviour and whole outcomes | An [answer-key](../orbyn-workflow/references/answer-key.md) check or an eval |
| Skill text and docs, thin glue, one-off scripts, or anything an existing test or type check already covers | Neither; UI gets a visual check instead |

Record the choice in one line in the task record or PR evidence, for example
`Tests: none, docs only` or `Tests: unit, deletes files`.

## Method

1. **Freeze the observed defect,** expected invariant and the smallest observable contract at a practical authorized test boundary. Use the [reproduction contract](../how/references/reproduction.md) for baseline, fixture and runner discovery.
2. **Write one regression** at the owning boundary, exercising the actual production path rather than a copy of the implementation. Assert state or externally meaningful behavior rather than private helper calls; [two-edit check](references/test-strategy.md#judge-a-test-by-two-edits). Keep mocks on unavailable effects at real effect/adaptor boundaries, away from private helper choreography.
3. **Run it against the unchanged candidate first.** Confirm the intended test actually ran; zero selected tests, an unrelated setup error or a skipped mode is not regression proof. Check that it fails for the reported contract violation, not a missing dependency or broken fixture. Retain failing attempts.
4. **Make the smallest coherent production correction,** then rerun the same case, directly affected controls and relevant adjacent cases. Never weaken assertions to obtain green.
5. **Extend one failing contract at a time** from observed behavior. Confirm the first signal catches the defect before writing more, rather than a speculative batch.
6. **Refactor only after the meaningful signal is green.** Internal reorganization should preserve useful behavior tests, so keep contract tests rather than coupling them to the new implementation.

For a stale version write, place the regression at the API/version boundary. Arrange an existing record and newer version, send the stale mutation, and assert both rejection and unchanged persisted data. A snapshot of the error string alone misses a write that succeeds before returning an error. Include a legitimate current-version control when it distinguishes an overbroad rejection. Add a UI check only when the changed user flow needs separate evidence and that check is authorized.

A model that reviews its own code repeats the blind spot that produced it, so its
"looks correct" is not evidence. Give every fixed bug an automated test, and make
it cover every path that can reach the bug, including the alternate ones (sandbox
and production, flag on and off, cached and fresh). Synthetic example: a field was
added to the production query but not the sandbox one; a test run over both modes
fails at once.

## When the ideal test is out of reach

- Baseline execution unavailable: record that limit. A passing new test without a demonstrated baseline failure is weaker regression evidence, so state that distinction and do not call it failing-before evidence.
- The practical test requires unrelated harness churn or unrealistic mocks: explain the limitation and use the closest authorized evidence.
- No production databases or unapproved live-provider calls. Production databases and paid providers require their own applicable authority. Read [development](../orbyn-workflow/references/project-policy.md#development-resources) for guarded database and package prerequisites.

## Read when needed

- A repair that retains a previously ignored value: the [propagated-value method](references/propagated-values.md).
- A critical invariant, event-order race, explicit formal verification request or stale verification model: [property verification](references/formal-verification.md) and its [drift review](references/verification-drift.md). Choose tools from the property and real code, demonstrate a failing control, and distinguish model results from implementation evidence. Skip the formal model for ordinary small UI edits.
- Requested test design: [test strategy](references/test-strategy.md) to select the real boundary, fixtures, failure controls and execution scope. A plan can be the requested output; this skill does not turn every test request into mandatory production edits.
- Model-powered application quality: pair deterministic permission/state tests with [task evaluations](../orbyn-ai-application/references/evaluations.md). A correct schema or one expected answer is not a reliability estimate; preserve held-out cases, repeated-trial failures and critical slices. Ordinary deterministic changes do not require live model calls.
- Clocks, async cleanup, readiness, module identity or runner legs that can hide the assertion: [test reliability](references/test-reliability.md). Preserve actual production/fixture boundaries and first-attempt evidence.
- Actual Expo/RN requested-screen, binary/device and native evidence: [mobile verification](references/mobile-verification.md). Deterministic fixtures and screenshots do not close missing platforms or paid-service cells.