# BDD Framing for the TDD Loop

BDD is the reason this skill frames every test as a _behavior_. Dan North started replacing the word "test" with
"behaviour" because almost every misunderstanding of TDD traced back to the word "test" — where to start, what to test,
how much, what to name it, why a failure matters. The framing below is how `/tdd` answers those questions mechanically.

## Name tests for behavior, in the project's convention

A test name describes an observable behavior of the unit, not a method or an implementation detail. North's diagnostic:
if you cannot phrase the name as a sentence about what the thing _should do_, the behavior may belong elsewhere.
"should" also keeps the premise challengeable — when a behavior test fails, ask "should it? really?": is the code wrong,
or is the asserted behavior now out of date?

**Surface syntax follows the project, not a literal "should".** BDD governs the _focus_ (observable behavior), not the
spelling. If the project uses `it("...")`, `test_...`, `describe/it`, xUnit `TestXxx`, Go `TestXxx` with
`t.Run("when ...")`, or a discovered coding standard that mandates a naming pattern, use that. The discovered convention
and any coding standard always win over the word "should". What does not change: the name states a behavior and an
expected outcome, never an implementation step.

## Given-When-Then maps to Arrange-Act-Assert

A scenario is one test. The three clauses are the three phases of that test:

- **Given** — the state of the world before the behavior. The arrange/setup. Typically something that already happened.
  Commands that establish state.
- **When** — the one event or action under test. The act. Exactly one per scenario. If you need an "and" in the When,
  you probably have two scenarios.
- **Then** — the expected, observable outcome: the behavior the code _should_ produce, which for a fix to broken
  behavior is not what it produces today. The assert. It must be on an observable output: a return value, a visible
  effect, a message or record that leaves the unit (a raised exception is a valid observable output to assert when
  raising is the desired behavior). Never on internal or private state.

Keep scenarios declarative, not imperative. "When the customer requests cash" is a behavior. "When the user clicks
#submit then waits 200ms" is an implementation procedure that will break on every UI change without the behavior
changing. Declarative scenarios survive refactoring; imperative ones do not.

## Outside-in: the double loop

BDD-framed TDD is two nested loops:

- **Outer loop** — a failing acceptance test for a user-observable behavior at a system boundary, written from the
  perspective of someone using the system. Slow loop (a feature's worth of work). It goes green only when every inner
  behavior is implemented with real code.
- **Inner loop** — ordinary red-green-refactor that makes the acceptance test progressively pass.

The procedure for a user-facing item: write the failing acceptance test, identify the entry point that gets called
first, start implementing it, and when it needs a collaborator, introduce that collaborator as a test double at the call
site. The collaborator's interface is _discovered by what the caller needs_, not designed up front. When the entry
point's test passes, drop down and make the next mocked collaborator real. The acceptance test passing last, against
real implementations, is the proof no collaborator was forgotten.

Not every list item is user-facing. A pure utility or an internal algorithm has no meaningful acceptance boundary — the
inner loop alone is correct there. Making the outer loop conditional on whether the behavior is user-observable is
correct scaling, not a shortcut.

## Test doubles: mock commands, stub queries

The five doubles (Meszaros, via Fowler): dummy (passed, never used), fake (working but shortcut implementation), stub
(canned answers to queries), spy (a stub that records calls), mock (pre-programmed with expectations that form a
specification). Only mocks insist on behavior verification; the rest use state verification.

The working rule for the loop:

- **Stub a query.** The collaborator only feeds data the unit needs to produce its outcome. Assert on the resulting
  state/output, not on the call.
- **Mock a command / required collaboration.** The interaction _is_ the behavior under test (the unit must tell a
  collaborator to do something). Assert the interaction.

Default to real objects unless using the real thing is awkward (the classicist default). Over-mocking couples the test
to the implementation: mockist tests break on refactor even when behavior did not change, because they specify exact
calls and parameters that are not the behavior under test. If a mock is only there to feed a value, it should have been
a stub. If exact call order or parameters are not the behavior, do not assert on them.

## BDD-flavored failure modes

- **Gherkin/test that describes UI mechanics** ("clicks the button, fills the field") instead of behavior. Rewrite
  functionally: name the intent, not the clicks.
- **Asserting internal state** in the Then. Assert observable output only.
- **Asserting the current buggy behavior** in the Then — for a fix to broken behavior, asserting the error the bug
  raises instead of the desired correct outcome. The test passes while the bug is present and breaks when you fix it.
  Assert what the code should do. (This is not a ban on raise assertions: asserting a raise is correct when raising is
  the specified desired behavior.)
- **Imperative scenario** that encodes how instead of what. Make it declarative; logic changes should touch step
  definitions, not scenario text.
- **Testing the mock instead of the behavior** — asserting call mechanics that are not the behavior under test, so the
  test breaks on refactor with no behavior change. Demote the mock to a stub, or assert the observable outcome instead.
- **Back-filling scenarios from code.** Scenarios come from concrete examples of intended behavior, decided before the
  code, not reverse-engineered from what was written.

## Sources

- Dan North, "Introducing BDD" (dannorth.net): behaviour over "test", the should-sentence template, "should it?
  really?", "what's the next most important thing the system doesn't do?".
- Martin Fowler, "GivenWhenThen", "Mocks Aren't Stubs", "UnitTest" (martinfowler.com): GWT mapped to Arrange-Act-Assert;
  stub vs mock; classicist vs mockist; coupling risk of over-mocking.
- Steve Freeman & Nat Pryce, _Growing Object-Oriented Software, Guided by Tests_: the outer/inner double loop,
  discovering interfaces via mocks at the call site, acceptance test green only with real implementations.
- Cucumber Gherkin reference and "Writing better Gherkin": Given/When/Then semantics, observable-output rule,
  declarative over imperative.

# How an Agent Fakes TDD, and the Discipline That Catches It

## Contents

- 1. Writing the test and the production code together
- 2. Never seeing red
- 3. Whole-feature steps
- 4. Skipping the refactor
- 5. Asserting on implementation detail
- 6. Applying standards while going green
- 7. Keeping no test list
- 8. Refactoring into speculative abstraction
- 9. Asserting the bug instead of the fix
- 10. Making a test pass by changing code the ticket does not own
- The one check that catches most of these

An unguided coding agent reliably fakes TDD. The failure is rarely malice — it is the model optimizing for "tests are
green at the end" instead of "the tests drove the code". Each failure mode below has a symptom you can observe and a
gate in the SKILL body that catches it. When you feel the pull toward any of these, that pull is the signal the
discipline exists to resist.

## 1. Writing the test and the production code together

**Symptom.** The test file and the production file are created or edited in the same step, then the suite is run once
and is green on the first run. Red was never observed.

**Why it happens.** It is faster and reads as efficient. The model "knows" the implementation, so writing the failing
test first feels like theater.

**Discipline.** The observed-failure gate. Write only the test. Run it. Paste the real failure output. Only then write
production code. A first-run pass is a hard stop, not a success — diagnose why the test did not fail.

## 2. Never seeing red

**Symptom.** No test run is shown between writing a test and writing the code that satisfies it. The transcript jumps
from "here is the test" to "here is the implementation".

**Why it happens.** Running the suite mid-cycle feels like overhead when the outcome seems obvious.

**Discipline.** Every cycle shows two pasted runner outputs at minimum: the red run (test fails for the intended reason)
and the green run (new test passes, all prior tests still pass). Output is shown, never asserted from memory.

## 3. Whole-feature steps

**Symptom.** One cycle implements the entire feature, then a batch of tests is written to cover it. Or the test list is
converted into many tests at once and then made to pass together.

**Why it happens.** The model can hold the whole feature at once, so decomposing into one-behavior steps feels
artificially slow.

**Discipline.** Exactly one list item becomes exactly one test per loop. No more production code than that one test
requires. Everything else discovered goes on the list, deferred. A long red bar (many failing tests at once) is the
symptom; the cure is the one-step rule.

## 4. Skipping the refactor

**Symptom.** Cycles go red, green, red, green. Duplication and structure debt accumulate. Coding standards are never
applied because the test is already green and the model has moved on.

**Why it happens.** Green feels like done. This is the single most common way TDD is ruined, per Fowler.

**Discipline.** Refactor is a non-skippable named phase. Either you change something (remove duplication, apply the
standards deferred from green, conform to ADRs) or you state explicitly "no duplication, structure, or standards issue
this cycle". Silence is not allowed; "green, moving on" is the failure.

## 5. Asserting on implementation detail

**Symptom.** Tests assert internal state, exact private call sequences, or specific collaborator parameters that are not
the behavior under test. The tests pass review and then break on the next refactor with no behavior change.

**Why it happens.** Mocking everything and asserting calls is mechanical and looks thorough.

**Discipline.** Assert observable behavior through the public interface. Stub queries, mock only genuine required
collaborations. If a refactor that changes no behavior breaks a test, the test was asserting implementation — that is a
test defect, not a code defect.

## 6. Applying standards while going green

**Symptom.** During the green phase the model runs naming sweeps, extracts helpers, and reformats — adding code beyond
what the one test needs.

**Why it happens.** "Write clean code" is a strong prior and fires constantly.

**Discipline.** Green obeys only correctness and architectural-placement constraints (where the code lives, which
boundary it must use, which contract it must honor — violating these is wrong code, not deferrable mess). Stylistic and
structural standards are the refactor hat. Wearing it during green violates "no more code than is sufficient to pass the
test".

## 7. Keeping no test list

**Symptom.** Scenarios are implemented as they occur to the model, or forgotten entirely. Scope drifts. Speculative
cases get built because they came to mind.

**Why it happens.** The model holds context in the conversation instead of in an explicit artifact, so the list feels
redundant.

**Discipline.** The test list is a first-class, visible artifact. Discovered scenarios are appended and deferred, never
implemented in the current loop. Speculative scenarios are deferred with a reopen trigger (YAGNI), not built. The list
draining is the progress signal; the list ballooning past ~10 open items is a scope warning the skill flags and records
in its summary while continuing autonomously, not a reason to keep silently grinding through unbounded scope.

## 8. Refactoring into speculative abstraction

**Symptom.** The refactor step introduces an interface with one implementation, a configuration knob no caller sets, or
a generalization from a single example — all justified as "for future flexibility".

**Why it happens.** Refactor is read as "make it sophisticated" rather than "remove the duplication you just made".

**Discipline.** YAGNI is first-class in refactor. Duplication is a hint, not a command. Abstract only when two or more
concrete examples force it (Rule of Three / Triangulate). Speculative structure is a YAGNI candidate: defer it with the
trigger that would reopen it and tell the user. Refactor removes duplication; it does not add speculation.

## 9. Asserting the bug instead of the fix

**Symptom.** The work is a fix to existing broken behavior, and the test asserts the error the bug raises (or the wrong
value it returns) rather than the desired correct result. It passes on first run because the bug is still present, or it
goes red for a reason other than "correct behavior not produced". Either way the gate looks satisfied, and fixing the
code then breaks the test.

**Why it happens.** The model describes the behavior it observes now. For a bug the observable behavior today _is_ the
error, so "assert the observable outcome" reads as "assert that the error is raised".

**Discipline.** A regression test asserts the _desired correct_ behavior: it fails because the bug is present and passes
once the fix lands. A bug-fix test that is green before the fix is the tell — rewrite it, do not cross the item off. The
boundary: asserting that the code raises is the _right_ test when raising is the specified desired behavior (raise on
invalid input). The failure mode is asserting the error that _is_ the bug being fixed.

## 10. Making a test pass by changing code the ticket does not own

**Symptom.** A list item goes red exactly as designed, and green arrives by editing a shared library, engine, or package
that other applications consume. The observed-failure gate is satisfied, every test is green, and the branch carries a
production change the ticket never authorized. It often compounds: a later test leans on the new behavior for a
deterministic setup, so the out-of-scope change becomes load-bearing for work that could have arranged its own fixture.

**Why it happens.** The item usually arrives carrying authority. A test plan or an analysis agent found something real,
labeled it CRIT, and the label reads as permission. The red is genuine, the fix is small, and the finding is honest, so
every local signal says proceed. Nothing in the moment asks the one question that matters.

**Discipline.** The scope gate. A genuine red proves the behavior is missing, never that this build owns producing it.
Before every production edit, name the file you are about to change and test it against the scope boundary recorded in
Step 1. A severity label ranks a finding's importance and says nothing about whose ticket it belongs to; an item whose
own text names a production change as a prerequisite is that change wearing a test's clothes. Work the resolution
ladder: redesign the test so it does not need the out-of-scope behavior, defer the item as its own ticket, and escalate
only when the requested behavior cannot be delivered without it. A test that needs the change only to make a fixture
deterministic never reaches the second rung.

## The one check that catches most of these

Before every production-code edit, you must be able to point to a specific test that you ran and watched fail for the
intended reason in this loop, and to a scope boundary that contains the file you are about to change. If the first is
missing, you are in one of failure modes 1 through 9: stop and get back to red. If the second is missing, you are in
failure mode 10: stop and work the resolution ladder.

# The TDD Loop: Canon, Laws, and Gears

This is the canonical reference for the red-green-refactor mechanics the `/tdd` skill enforces. It is the single source
for the verbatim rules — the SKILL body links here rather than restating them.

## Robert C. Martin's Three Laws of TDD

Use this phrasing. It resolves the compile-vs-assertion question and the one-test-at-a-time question explicitly:

1. You are not allowed to write any production code unless it is to make a failing unit test pass.
2. You are not allowed to write any more of a unit test than is sufficient to fail; and compilation failures are
   failures.
3. You are not allowed to write any more production code than is sufficient to pass the one failing unit test.

The laws operate second-by-second. You iterate them roughly a dozen times before a single test is complete. You are
never more than a few unwritten lines from a run, and never more than one change from a green or red bar.

## Canon TDD (Kent Beck)

The reference loop. Deviations should be deliberate, not accidental:

1. Write a list of the test scenarios you want to cover.
2. Turn exactly one item on the list into an actual, concrete, runnable test.
3. Change the code to make the test (and all previous tests) pass, adding items to the list as you discover them.
4. Optionally refactor to improve the implementation design.
5. Until the list is empty, go back to step 2.

The test list is a first-class artifact. It starts with every operation you know you need and the null/degenerate
version of each. As you make tests pass, the implementation implies new tests and refactorings — write them on the list,
do not implement them now. Items left when the session ends are handled explicitly: continue them next session, or move
clearly out-of-scope refactorings to a "later" list. A test you can think of that might not work is never moved to
"later".

## The mantra

- **Red** — write a small test that does not work, and perhaps does not even compile at first.
- **Green** — make the test work quickly, committing whatever sins are necessary in the process (duplication, hard-coded
  values, ugliness).
- **Refactor** — eliminate the duplication created in just getting the test to work.

"Committing sins" means duplication and poor structure are tolerated _temporarily_, to be removed in refactor. It does
not mean writing code that violates an architectural boundary or a correctness contract — that is not a sin you clean up
later, it is the wrong code. This is why the `/tdd` skill honors correctness and placement standards during green but
defers stylistic and structural conformance to refactor.

## Two hats

Making a test pass and refactoring are different activities done at different times. "Make it run, then make it right."
Mixing refactoring into the make-it-pass step is the classic two-hats mistake. Refactor only when every test is green. A
structural change while a test is red is not a refactor.

## The observed-failure gate

The single highest-value invariant, derived from Law 1 + Law 2 + Beck's test-first ordering: no production-code change
is permitted unless a test has been run and observed to fail for the intended reason in this loop. A test that passes
the first time it is ever run was never red — that is a process violation signal, not a success. Diagnose it with the
three-cause check in the `/tdd` skill's Red step: the test does not exercise the behavior, the behavior already exists,
or — for a fix to broken behavior — the test asserts the current broken behavior (the error the bug raises) and so
passes while the bug is still present.

## Implementation gears (choosing step size)

TDD is not blind rule-following; it is choosing step size and feedback by conditions. Three gears, smallest step last:

- **Obvious Implementation (second gear).** You are certain how to implement the operation. Type the real code.
  Guardrail: if you start getting surprised by red bars, downshift immediately and take smaller steps.
- **Fake It (small step).** You have a broken test and are not certain. Return a constant. Once green, generalize the
  constant into an expression. The duplication between test and code is removed in refactor — this is why Fake It does
  not violate "no unneeded code".
- **Triangulate (smallest step).** You are really unsure of the right abstraction. Force it: add a second concrete
  example with different values so one parameter or branch cannot satisfy both, and let the two examples drive the
  generalization. Use only when genuinely unsure; otherwise Obvious Implementation or Fake It.

The tougher or less familiar the problem, the smaller the step. Reserve Obvious Implementation for genuinely simple,
certain operations.

## How much to test

Test count is driven by the confidence the code needs, not by a coverage number. If knowledge of the implementation
gives real confidence in the absence of a test, that test may not be worth writing. Tests that execute code but assert
nothing meaningful are not TDD tests — start each test from the assertion (Assert First) and derive the expected value
independently from the specification, never by pasting back the program's own output.

## Sources

- Kent Beck, _Test-Driven Development: By Example_ (2002): Test List, Implementation Strategies (Fake It, Triangulate,
  Obvious Implementation), Assert First, step size and feedback.
- Kent Beck, "Canon TDD" (tidyfirst.substack.com): the five-step loop and the named mistakes (two-hats, batch-converting
  the list, abstracting too soon).
- Robert C. Martin, "The Three Rules of TDD" and "The Cycles of TDD" (blog.cleancoder.com): the Three Laws and the
  nested cycle timescales.
- Martin Fowler, "Test Driven Development" and "Self Testing Code" (martinfowler.com): red-green-refactor summary;
  refactor is the most-skipped step; run the whole suite frequently.

# Choosing the Next Test: TPP and ZOMBIES

## Contents

- The Transformation Priority Premise (TPP)
- Using the ranking to pick the next test
- The decision-point rule
- ZOMBIES: the same idea as a concrete ordering
- How this composes with the rest of the loop
- Worked example: `sum(numbers)`
- Sources

This is the canonical reference for the test-selection heuristics the `/tdd` skill uses when it orders the test list
(Step 2) and picks the next item (Step 3). The loop tells you to write a failing test and make it pass. It does not tell
you which test to write next. The Transformation Priority Premise and ZOMBIES both answer exactly that question, and
they answer it the same way:

> Choose the next test that can be satisfied by the simplest transformation of the code.

The core principle (Robert C. Martin): **as the tests get more specific, the code gets more generic.** You steer that
progression by selecting tests in order of the transformation they demand — simplest first. These are test-selection
heuristics, applied while choosing what to test next. They are never a menu for hacking an implementation to green after
the test is chosen.

## The Transformation Priority Premise (TPP)

Transformations are the counterpart of refactorings: a refactoring changes structure without changing behavior; a
transformation changes behavior by generalizing structure. TPP ranks the transformations a new passing test can force on
the code, from simplest to most complex:

| #   | Transformation               | A test at this rank forces…                          |
| --- | ---------------------------- | ---------------------------------------------------- |
| 1   | `{} → nil`                   | code to exist at all, returning nil/null             |
| 2   | `nil → constant`             | a fixed constant value                               |
| 3   | `constant → constant+`       | a simple constant to become a more complex one       |
| 4   | `constant → scalar`          | a constant to become a variable or argument          |
| 5   | `statement → statements`     | more unconditional statements                        |
| 6   | `unconditional → if`         | the execution path to split with a conditional       |
| 7   | `scalar → array`             | a variable to become an array                        |
| 8   | `array → container`          | an array to become a richer container (list/map/set) |
| 9   | `statement → tail-recursion` | tail recursion                                       |
| 10  | `if → while`                 | a conditional to become a loop                       |
| 11  | `statement → recursion`      | general (non-tail) recursion                         |
| 12  | `expression → function`      | an expression to become a function or algorithm      |
| 13  | `variable → assignment`      | a variable's value to be reassigned or mutated       |
| 14  | `case`                       | a new case or else added to an existing conditional  |

This is the canonical fourteen-transformation list from the original article. Martin notes the ordering is
language-specific (in an imperative language you might rank iteration and assignment above recursion) and that "there
are likely others." He also frames it as a _premise_, not a theorem — an informal ranking, not a law. Treat the ranks as
a strong default and apply design judgment when several simplest-first paths exist.

## Using the ranking to pick the next test

- When several candidate tests remain on the list, **write the one whose passing requires the highest-priority
  (simplest) transformation**. A test that needs only `nil → constant` comes before one that needs `unconditional → if`,
  which comes before one that needs `if → while`.
- If the only test you can think of would force a low-priority transformation (a loop, recursion, a whole algorithm)
  early, that is the signal a **simpler test is missing** — find it, add it to the list, and write it first.
- When two candidates demand the same transformation, the ranking has no opinion. Break the tie toward the smaller input
  or the example the user supplied; either keeps the step small, and the loser stays on the list.
- The maintained test list is what makes this work: TPP selects by _scanning_ the behaviors not yet tested and comparing
  the transformations they would force. This is one more reason the test list is a first-class artifact.

Why select tests this way:

- **Simpler designs.** The code grows by the smallest generalization each cycle: a constant before a scalar, an `if`
  before a `while`.
- **Fewer impasses.** A premature low-priority test can force the implementation into a corner that a simpler ordering
  would have avoided.
- **Small, reversible steps.** Every green is one small transformation away from the last green, which keeps the loop's
  step size honest.

## The decision-point rule

TPP's sharpest use is at a decision point: when more than one transformation could make the current failing test pass,
prefer the one **higher on the list**. Martin demonstrates the stakes with a sort. At "two elements out of order" you
can compare-and-swap (an assignment, near the bottom of the list) or compare and return a new array (no assignment).
Follow the swap and you derive bubble sort; avoid the low-priority assignment and quicksort "almost falls out
inevitably." The same failing test, two transformations, two very different algorithms — the ranking is what tips you
toward the better one.

Bending the ranking is sometimes correct. When a transformation legitimately needs a helper to land (a recursive step
needs a function that takes the tail of a collection, say), taking that step is fine if it is the smallest _real_
increment available. The goal is the next smallest increment, not literal obedience to the table.

A single test may also legitimately force a small cluster of transformations at once — a loop usually brings an
accumulator assignment with it, and a new scalar often arrives inside a new conditional. Compare candidates by the
deepest-ranked transformation in the cluster each would force; the ranking still orders the tests even when no test maps
to exactly one row.

## ZOMBIES: the same idea as a concrete ordering

James Grenning's ZOMBIES mnemonic makes the simplest-first order memorable. **ZOM** (Zero, One, Many) is the core
progression; **BIES** covers what else to select for as you go:

| Letter | Stands for           | Choose a test that…                                                  |
| ------ | -------------------- | -------------------------------------------------------------------- |
| **Z**  | Zero                 | exercises the empty / zero / null case                               |
| **O**  | One                  | exercises exactly one element or occurrence                          |
| **M**  | Many / More          | exercises many — the test that forces the loop or collection         |
| **B**  | Boundary behaviors   | probes limits: first/last, off-by-one, min/max                       |
| **I**  | Interface definition | pins the smallest viable signature the caller needs                  |
| **E**  | Exceptional behavior | drives invalid input and failures at the public boundary             |
| **S**  | Simple               | keeps each scenario, and the step it implies, as simple as it can be |

Pick tests **Z → O → M** for the happy path. The interface (**I**) emerges from the very first test; boundaries and
exceptions (**B**, **E**) fill in once the core generalization exists. Never select a Many test before a One test has
forced the code to handle a single case — Zero → One → Many is exactly TPP's simplest-transformation-first ordering,
made concrete.

Rule of thumb: each test should add **one** small new behavior and demand the **smallest** possible generalization. If
the only remaining test forces a large leap, a smaller test is missing between it and the last green.

## How this composes with the rest of the loop

- **User value picks the behavior; TPP/ZOMBIES picks the test.** Step 2 orders the list outside-in by user value — the
  next _behavior_ is the most important thing the system does not yet do. When driving that behavior expands into
  several candidate tests (the zero case, the one case, the many case, the boundaries), simplest-transformation-first
  governs their order. The two orderings answer different questions and do not compete.
- **This is how you find Beck's "one step test."** Step 3 says to pick an item that teaches you something and that you
  can implement in one cycle. TPP and ZOMBIES are the deterministic way to find that item: the test needing the simplest
  transformation _is_ the one-step test.
- **The gears stay small because the tests were chosen small.** Fake It is `nil → constant`. Triangulate adds the second
  example that forces `constant → scalar`. A test chosen simplest-first bounds how much the green step can require; a
  test chosen too coarse is what forces Obvious Implementation on something that deserved smaller steps.
- **A first-run pass can mean the code has generalized.** When a chosen test passes on its first run, the
  observed-failure gate trips and one diagnosis is "the behavior already exists." In TPP terms the implementation has
  gone generic ahead of the tests — the loop or abstraction already covers this case. Cross the item off per the gate;
  the passing test stays as documentation of the boundary it confirms.

Diagnostic signals, all about test choice:

- _About to write a Many/loop test first?_ You skipped Zero and One. The Zero test needs only `nil → constant`.
- _The only test you can think of forces recursion or a `while`?_ A simpler test is missing; a One-case test usually
  drops the required transformation to `unconditional → if` or `statement → statements`.
- _A test forces a huge implementation leap?_ It is too coarse. Add a smaller test between it and the last green.
- _The implementation came out over-engineered?_ The test selected was too big. Back up and choose a simpler one.
- _The chosen test will not even run cleanly_ (a cascading error rather than a clean assertion failure)? Do not force
  it. Put it back on the list, pick an item that fails cleanly, and return to the deferred item once the code has caught
  up.

## Worked example: `sum(numbers)`

Each row is the next behavior chosen because it needs the simplest remaining transformation:

| Order | Behavior chosen (ZOMBIES)          | Transformation it drives (TPP)                              |
| ----- | ---------------------------------- | ----------------------------------------------------------- |
| 1     | **Z**ero — `sum([]) == 0`          | `nil → constant`: `return 0`, the simplest available        |
| 2     | **O**ne — `sum([5]) == 5`          | `constant → scalar`: read the single element                |
| 3     | **M**any — `sum([5, 3]) == 8`      | `if → while`: the first test that genuinely forces the loop |
| 4     | **B**oundary — `sum([-1, 1]) == 0` | none — confirms the generalization holds                    |
| 5     | **E**xception — `sum(None)` raises | `unconditional → if`: a guard at the public boundary        |

Each row adds exactly one behavior and uses the simplest transformation that keeps the suite green. Row 3 is where Many
forces the generic loop — and not a moment earlier. Row 4 is a confirming test: it passes without a production change,
which is the "behavior already exists" arm of the observed-failure gate doing its job.

## Sources

- Robert C. Martin, "The Transformation Priority Premise" (blog.cleancoder.com, 2013): transformations as the
  counterpart of refactorings, the fourteen-rank list, the language-specificity and premise-not-theorem caveats.
- Robert C. Martin, "Transformation Priority and Sorting" (blog.cleancoder.com, 2013): the decision-point rule and the
  bubble-sort vs quicksort demonstration.
- Robert C. Martin, "The Cycles of TDD" (blog.cleancoder.com, 2014): "as the tests get more specific, the code gets more
  generic."
- James Grenning, "TDD Guided by ZOMBIES" (blog.wingman-sw.com): the Zero, One, Many, Boundaries, Interface, Exceptions,
  Simple mnemonic and ordering.
- Jeff Langr, _Modern C++ Programming with Test-Driven Development_ (Pragmatic Bookshelf): the maintained test list as
  near-essential to TPP, bending the ranking for the smallest real increment, and deferring a test that will not fail
  cleanly.

#!/usr/bin/env bash
# Detect git state and infer test/lint/build commands from project manifests.
# Run ONCE in Step 1, only when CLAUDE.md / project-discovery.md did not
# resolve the commands. Per-cycle test runs do NOT use this script — they call
# the resolved test command directly so the loop is not interrupted by a
# per-invocation approval every cycle.
#
# Inference is a best-effort fallback. Emitted commands are suggestions for the
# user to confirm, not authority. Output is line-oriented key: value pairs.

# --- git state ---------------------------------------------------------------
if command -v git &>/dev/null && git rev-parse --is-inside-work-tree &>/dev/null; then
  echo "git-available: true"
  BRANCH=$(git branch --show-current)
  echo "branch: ${BRANCH:-none}"
  if git symbolic-ref --short refs/remotes/origin/HEAD &>/dev/null; then
    echo "default-branch: $(git symbolic-ref --short refs/remotes/origin/HEAD)"
  else
    echo "default-branch: none"
  fi
else
  echo "git-available: false"
  echo "branch: none"
  echo "default-branch: none"
fi

# --- manifest-inferred commands ----------------------------------------------
# First match wins per category. These are suggestions; the user confirms.
TEST_CMD=""
LINT_CMD=""
BUILD_CMD=""

if [ -f package.json ]; then
  echo "manifest: package.json"
  grep -q '"test"[[:space:]]*:' package.json && TEST_CMD="npm test"
  grep -q '"lint"[[:space:]]*:' package.json && LINT_CMD="npm run lint"
  grep -q '"build"[[:space:]]*:' package.json && BUILD_CMD="npm run build"
fi

if [ -z "$TEST_CMD" ] && { [ -f pyproject.toml ] || [ -f pytest.ini ] || [ -f setup.cfg ] || [ -f tox.ini ]; }; then
  echo "manifest: python (pyproject/pytest)"
  TEST_CMD="pytest"
fi

if [ -z "$TEST_CMD" ] && [ -f go.mod ]; then
  echo "manifest: go.mod"
  TEST_CMD="go test ./..."
  BUILD_CMD="go build ./..."
fi

if [ -z "$TEST_CMD" ] && [ -f Cargo.toml ]; then
  echo "manifest: Cargo.toml"
  TEST_CMD="cargo test"
  BUILD_CMD="cargo build"
fi

if [ -z "$TEST_CMD" ] && { [ -f Gemfile ] || [ -f Rakefile ] || [ -d spec ]; }; then
  echo "manifest: ruby (Gemfile/Rakefile)"
  if [ -d spec ]; then TEST_CMD="bundle exec rspec"; else TEST_CMD="bundle exec rake test"; fi
fi

if [ -z "$TEST_CMD" ] && [ -f mix.exs ]; then
  echo "manifest: mix.exs"
  TEST_CMD="mix test"
fi

if [ -z "$TEST_CMD" ] && { [ -f pom.xml ]; }; then
  echo "manifest: pom.xml"
  TEST_CMD="mvn test"
  BUILD_CMD="mvn package"
fi

if [ -z "$TEST_CMD" ] && { [ -f build.gradle ] || [ -f build.gradle.kts ]; }; then
  echo "manifest: gradle"
  TEST_CMD="gradle test"
  BUILD_CMD="gradle build"
fi

if [ -z "$TEST_CMD" ] && [ -n "$(find . -maxdepth 3 -name '*.csproj' -print -quit 2>/dev/null)" ]; then
  echo "manifest: dotnet (.csproj)"
  TEST_CMD="dotnet test"
  BUILD_CMD="dotnet build"
fi

# A Makefile with a test target is a common override regardless of language.
if [ -f Makefile ] && grep -qE '^test:' Makefile; then
  echo "manifest: Makefile (test target)"
  [ -z "$TEST_CMD" ] && TEST_CMD="make test"
  grep -qE '^lint:' Makefile && [ -z "$LINT_CMD" ] && LINT_CMD="make lint"
  grep -qE '^build:' Makefile && [ -z "$BUILD_CMD" ] && BUILD_CMD="make build"
fi

echo "inferred-test-command: ${TEST_CMD:-none}"
echo "inferred-lint-command: ${LINT_CMD:-none}"
echo "inferred-build-command: ${BUILD_CMD:-none}"