Menu
A scoped TDD discipline. Use for unit tests inside a slice during checkpointed-build. Adds two mandatory steps beyond GREEN — BUDGET and ORACLE — and treats TDD as one tool in a larger spiral, not the whole methodology.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Replaces brainstorming for feature design. Produces a design where every claim is paired with an experiment that would prove it wrong, and the cheapest such experiment runs before the design is approved. Refuses to run until prove-it-prototype has produced agreement between probe and oracle.
REQUIRED before prove-it-prototype when a feature request originates from a human in natural language. Interrogates the requester one question at a time until every vague noun is resolved, every success criterion is measurable, every edge case has an explicit decision, every "TBD" is closed, and the requester has signed off in their own words. Refuses to proceed until the artifact has zero hand-waving.
REQUIRED before any design or plan when adding a feature to a system you did not personally write. Build a 30-50 line probe that produces the proposed feature's output against the real codebase, define an independent oracle that computes the same answer a different way, and refuse to proceed until probe and oracle agree.
Replaces executing-plans. Executes slices one at a time. After each slice, runs the slice's stress fixture AND the prove-it-prototype oracle against the binary AND the budget check. If any of those fail, STOPS and surfaces the drift to the user. Treats the plan as a hypothesis, not a contract.
Use when responding to PR review feedback (human or bot) before applying any changes. Treats each finding as a hypothesis to verify, not an instruction to follow. Decides per finding whether the bug claim is real AND whether the proposed fix is right AND whether to accept, modify, or reject. Refuses to apply changes without per-finding verification.
Replaces writing-plans. Decomposes a falsifiable design into small slices, each with mandatory complexity budget, scale budget, stress fixture, and oracle. Refuses to run until falsifiable-design has produced an approved design with a passing cheapest-falsifier.
| name | tdd-scoped |
| description | A scoped TDD discipline. Use for unit tests inside a slice during checkpointed-build. Adds two mandatory steps beyond GREEN — BUDGET and ORACLE — and treats TDD as one tool in a larger spiral, not the whole methodology. |
TDD is fine for what it actually does. It is not, by itself, a software engineering methodology. We use it as one gear in the loop. We do not let it pretend to be the whole machine.
Verifying that a single function does what its caller expects, when called with inputs you've enumerated. A check on the unit's correctness against the unit's contract. Important. Limited.
falsifiable-design.)prove-it-prototype.)budgeted-plan.)checkpointed-build.)If you think "I have unit tests, therefore the feature works," you are misusing the tool. Unit tests proving things they don't prove is how features ship with the wrong algorithm.
RED → GREEN → BUDGET → ORACLE → REFACTOR
The two new gates (BUDGET, ORACLE) are mandatory between GREEN and REFACTOR. Without them, you have not finished the test. You have made it pass.
Inside a slice during checkpointed-build, for any new function or any modified behavior of an existing function. The slice's contract (claim, fixture, oracle, budget) comes from budgeted-plan and is in scope for the entire cycle.
Write the simplest implementation that makes the test pass. Minimal is fine here. The minimal implementation is allowed to be inefficient, ugly, or hyper-specific to this test. It is not allowed to be wrong.
Watch the test pass. Watch other tests still pass. Mandatory.
The slice has a loop budget and possibly a wall-clock budget from budgeted-plan. Now that the test passes, check:
time/hyperfine/equivalent. Does it fit?If no: REWRITE. The minimal implementation is wrong because it's over budget. Pick an algorithm that fits. Rerun the test. Rerun BUDGET.
This is the step "minimal code" alone gets wrong. "Minimal" optimizes for the test passing. "Minimal within budget" optimizes for the slice's contract. The contract is the goal.
Rebuild the binary. Run the prove-it-prototype probe again. Compare to its oracle.
If they still agree: proceed.
If they drift: the implementation that just passed its unit test broke the slice's correctness contract. The unit test was passing for the wrong reason. STOP. Surface to the user via the checkpointed-build halt protocol.
This is the gate that catches "the unit test is fine but the integration is wrong." It exists because the test universe and the real universe are different universes.
After BUDGET and ORACLE both pass: clean up. Remove duplication. Improve names. Extract helpers. Keep tests green. Keep budget. Keep oracle agreement.
If this cycle changed a function's semantics (return type, error conditions, what "no match" means, etc.), explicitly ask: does the function's name still describe its behavior?
Examples that should trigger a rename:
search_by_name that used to return "first match" but now returns "unique match or None" — the name no longer signals the contract. Rename to search_unique_by_name or find_unambiguous_by_name.parse_X that used to panic on malformed input but now returns Result — rename to try_parse_X.get_X that used to assume cache presence but now does I/O — rename to load_X or fetch_X.Renaming costs one signature change plus N call-site updates. Not renaming costs every future reader assuming the wrong contract from the name and being surprised by the behavior. The first cost is bounded and now; the second is unbounded over time.
If the name still fits, say so out loud (in a commit message or comment) so future-you knows the question was asked.
When renaming, use the impact-analysis step from checkpointed-build a-1 to enumerate every call site. Static-analysis tool first (e.g. tethys callers <Type::method> or your IDE's find-usages), grep as the safety net. Update every site in the same commit. A rename committed with stale call sites is a half-rename, which is worse than no rename: future grep for the new name misses the old call sites, and future grep for the old name shows phantoms.
Then move to the next test in this slice, or close the slice and advance.
The standard TDD skill says:
"Need to explore first" → Fine. Throw away exploration, start with TDD.
Wrong. Exploration was prove-it-prototype. You do not throw the probe away. You promote it to the persistent oracle. The probe stays. The agreement stays. TDD runs on top of the probe, not in place of it.
The standard TDD skill says:
Minimal code. Just enough to pass.
Insufficient. "Just enough to pass the unit test" is not the bar. The bar is "just enough to pass the unit test, fit the slice's budget, and keep the oracle agreement." Three conditions, all required.
The standard TDD skill says:
Tests use real code (mocks only if unavoidable).
Correct but incomplete. "Real code" here means "real code in the test fixture." The fixture is still a fixture. It is not production data. Unit tests using real code against a tiny fixture still cannot tell you anything about production-scale behavior. That's what BUDGET and ORACLE are for.
Beyond the standard "every function tested, watched it fail, watched it pass":
debug_assert! for sanity-hint)If you cannot check all six, the slice is not done. Do not commit.
A scoped version of TDD that does its actual job — unit-level correctness — without pretending to do jobs it can't do. It is one gear in the gilfoyle loop. It does not turn the wheel by itself.
For each test cycle: a failing test that became passing, an implementation that fits the budget, and a re-confirmed oracle agreement. If any of those three is missing, the cycle didn't finish. Finish it.