Self-Correcting TDD Implementation Loop

Overview

Given a feature/bugfix spec, drive it to a hardened, CI-green PR through a closed test-driven development (TDD) loop: RECON → PLAN → per-slice RED → GREEN → REFACTOR → SLICE-LOOP → mandatory adversarial + security self-review (BLOCKING = hard gate) → VERIFIED PR → CAPTURE: looping until BOTH the full test suite AND the security checklist are green, each proven by a captured artifact, never by self-report.

The skill's contribution is the enforcer + iteration controller. It is self-contained; it composes nothing you must install. (Optional: if you run a skill ecosystem with dedicated TDD / planning / review skills, slot them into the matching stages below; the gates are identical either way.)

Iron Law

No slice advances on self-report. Every green verdict cites an externally-verifiable ARTIFACT, a captured exit code, a report file, or a git result.

A skill body is a prompt, not an enforcement boundary (no hook ships with this skill). A self-policed gate can be rationalized past, so bind every gate to an artifact you can re-read. "I checked and it's fine" is not a green verdict.

Violating the letter of the gates is violating the spirit of the gates. A green deploy, green CI, a stale LGTM, "I'm confident": each is necessary at most, never sufficient.

When to use

• Implementing a feature/bugfix from a spec that should land as a CI-green PR.
• Triggers: /tdd-loop, "implement this", "build this feature and open a PR", "self-correcting TDD", "autonomous implement loop".

When NOT to use:

• Pure research/audit with no code.
• An undecided idea ("should I build X?") → brainstorm/design first.
• A one-line mechanical edit → just do it; the loop is overhead.

Preconditions (refuse if unmet: recon first)

Run recon BEFORE any code. Refuse to proceed if preconditions fail: do not paper over a missing spec, a dirty tree, or an unknown base branch.

• recall: search your prior sessions / notes for lessons in this area before substantive work (if your harness has session search or a memory store).
• spec: scenarios + acceptance criteria exist. New or contract-visible behavior needs them; if absent, write or locate the spec first.
• clean worktree from the repo's current default branch (not a shared canonical checkout you also build in).
• declared checks known: the repo's test / lint / build commands (repo-local CLAUDE.md / AGENTS.md / CI). If none are declared, state that explicitly, and let it RAISE rigor (hand-roll a check), never lower it.

The loop (use your harness's canonical for each stage; do not reinvent)

0. RECON: recall prior lessons; investigate live state. Verify any root-cause/approach hypothesis against the actual code; no single-hypothesis lock-in (≥2 independent readings for any contested root cause before acting). Refuse if preconditions fail.
1. PLAN: vertical slices + the test seam(s), sequenced by dependency. Each slice is a tracer-bullet vertical slice (end-to-end through every layer it touches), NOT a horizontal layer.
2. RED: write ONE failing test for the next slice; run it; confirm it fails for the RIGHT reason. Distinguish a real RED from a FLAKE (re-run to confirm determinism). Not all tests up front: that horizontal slice is fake TDD.
3. GREEN: implement minimally until that one test passes; iterate edit→test.
4. REFACTOR: clean up while tests stay green.
5. SLICE-LOOP: repeat 2-4 one vertical slice at a time until the feature is complete. An unexpectedly-failing test routes BACK to root-cause investigation, never forward to a speculative patch.
6. ADVERSARIAL + SECURITY SELF-REVIEW (mandatory): see Enforcer gates + Security checklist. Feed the computed diff to the reviewer roles; BLOCKING findings are HARD GATES: fix, re-run the full suite, re-review. PLUS advisory computational sensors (mutation, behavioral, optional property-based) that RUN rather than read the diff: they surface findings for judgment but never hard-block.
7. VERIFIED PR: preflight (detect base branch, secret scan) → finish the branch → commit (passes the secret gate; never echo secrets; never force-push) → open the PR with test evidence + review summary → independent runtime verification (a green deploy/CI is not runtime proof).
8. CAPTURE: record the lessons so the next pass is cheaper.

Enforcer gates (hard-stop; each binds to an ARTIFACT)

The loop refuses to advance until the named artifact proves green. BLOCKING-as-hard-gate: the PR does not open while any BLOCKING finding is open OR the suite is red.

• Precondition gate: recon done vs the spec; refuse if preconditions fail.
• RED gate: the test is observed FAILING for the right reason, re-run to rule out a FLAKE (capture both runs). "Saw red once" is not enough.
• Slice gate: ONE RED→GREEN per vertical slice; an unexpected failure → root-cause investigation, not a forward patch.
• Review-ran gate: COMPUTE the diff yourself (git diff <base>...HEAD), assert it is NON-EMPTY and matches the slices touched, and feed THAT diff to the reviewers. An empty/clean reviewer result on a non-empty diff is a GATE FAILURE (re-run): "the engine actually ran against the actual diff" is a precondition of any green verdict.
• Security gate (BLOCKING-as-hard-gate): run the diff through the security checklist below; any BLOCKING finding blocks the PR. Loop-until clean.
• Secret gate: independently re-run your secret scanner on the staged set and assert successful exit AND a parseable report in the scanner's expected schema with zero findings. File existence (including a precreated empty file) is not clean evidence. Missing, empty, malformed, wrong-shaped or positive-finding reports block. A scanner that errors, times out, or runs outside the repo can fail OPEN, so a non-blocking advisory counts as NOT green here. Escape a false positive via the scanner's allow mechanism, never by bypassing the commit hook past a real finding.
• Completion gate: run the FULL test suite as the LAST action before the PR, capture its exit code to a file, and quote it. A non-zero, stale, or absent capture = not green. No "done" without independent runtime verification.

Computational sensor gates (ADVISORY, complement the inferential reviewers)

The reviewer roles above are inferential sensors: an LLM reading the diff. Complement them with computational sensors that actually RUN. These are advisory and severity-graded (WARNING / INFO), never hard gates: they surface findings for judgment and never stall the PR, and they ship advisory first (the advisory-then-blocking migration). Bind each verdict to a report artifact, not a self-assertion. A sensor that errors, times out, or cannot run is PENDING (an abstention), never a silent "clean", and PENDING never escalates to BLOCKING here.

• Mutation sensor. Run a bounded, changed-files-scoped mutation pass (mutmut, cosmic-ray, Stryker, or PIT, scoped to the slice's changed source) and read the result. A surviving mutant means a test too weak or non-asserting to notice the change. Coverage is an invalid quality proxy for agent-written tests; the mutation score is the corrective computational signal. Keep it bounded (changed-files scope, a mutant cap, per-run and total timeouts), because mutation testing is expensive. Surface surviving mutants, add the missing assertion when the finding is real, never stall the PR on it.
• Behavioral sensor. EXECUTE the artifact and judge its observed runtime behavior, because agents can "build to the test" and leave the real deliverable dead while the unit suite stays green. An interactive judge that runs the artifact resists the reward-hacking a static diff/test-reader does not. Declare ONE acceptance scenario as an explicit run command plus the observable outcome that proves it worked, run it, and read the result: ran (exit 0) but the expected outcome absent means a green suite over a dead or wrong deliverable. Rule of Two: this sensor executes the artifact's own untrusted code, so bound it (a hard timeout, a process-group kill so a forked grandchild cannot outlive it, a child env scrubbed of secret-shaped vars). Honest limit: a same-UID process can still read the parent env and network egress is not blocked, so for genuinely untrusted code run it under OS isolation (a container, a PID+mount namespace, or a dedicated low-privilege UID) or where the parent holds no secrets.
• Property-based sensor (optional). For the semantic-input bugs example-based tests miss, add property-based testing (Hypothesis, fast-check) over library-shaped pure functions. Test only properties a human DECLARED: auto-inferred properties carry a high false-positive tax, so a declared-only sensor avoids flagging correct code. Opt-in and advisory; scaffolding helps weaker agents and can distract a frontier model, so keep it optional.

Iteration controller: loop-until( full-suite green AND security-checklist green ), both proven by captured artifacts. Only then open the PR.

See references/ENFORCER.md for the runnable mechanics of every gate.

Security checklist (stage 6 must check each named bug class)

• fail-open: a gate/guard that defaults to ALLOW on error, exception, or timeout.
• path traversal: ../ escapes, unsanitized path joins, symlink escape, absolute-path injection.
• injection: shell / SQL / template; unescaped interpolation; unquoted expansion.
• secret-spill: including the secret-to-stdout prohibition: never echo plaintext secrets; redirect secret-bearing commands and check the exit status; read a single value without printing it.
• auditability: mutation without a receipt/log; non-idempotent operations; no rollback path.
• ID collisions: non-unique keys / slugs / filenames; races on shared identifiers.

Reviewer engines (roles, not products)

Dispatch the computed diff to (at least) two roles:

• a code-level SECURITY reviewer that encodes the six classes above, and
• an ADVERSARIAL / CORRECTNESS reviewer (logic, edge cases, state, error propagation, abuse / composition / cascade failures).

Use whatever diff-fed reviewer agents your harness provides. If you have none, run each role's checklist against the diff YOURSELF in a dedicated pass; the gate is that a reviewer (human, agent, or your own structured pass) actually saw the computed diff. A PR-scoped or "looks simple, skipping" review is NOT the pre-PR security engine: run security review on every diff, then any broader post-PR review as a complement.

Substrate (harness-agnostic)

Drive the per-slice and per-review fan-out with whatever your harness gives you, independent subagents, a deterministic workflow runner if you have one, or inline sequential work. Never assume a particular orchestrator is available; an un-orchestrated run MUST still complete end-to-end inline. The gates above are substrate-independent, they bind to artifacts either way.

Rails (baked in)

• Mandatory recon + refuse-if-preconditions-fail (above).
• No single-hypothesis lock-in: verify any root cause vs live state; ≥2 readings for a contested cause before acting.
• Full test suite + adversarial review before any commit/PR; BLOCKING = hard gate.
• Investigate the codebase directly: do not ask for context you can discover yourself.
• Never echo secrets to stdout: redirect secret-bearing commands + check the exit status.
• Concise output; write large artifacts to files incrementally: do not dump large blobs into the transcript.
• For the CODE the loop drives: a fresh worktree/branch off the repo's detected default branch (never a shared canonical checkout); never force-push; base branch detected from repo PR convention or git remote show origin, never assumed main.
• Severity-grade every finding BLOCKING / WARNING / INFO.

Red flags: STOP (you are rationalizing past a gate)

What it deliberately does NOT do

• Does NOT duplicate a post-push CI/review pipeline (that runs after push; this is the pre-PR gate, they complement).
• Does NOT add a secret-scan hook (your secret scanner already gates at commit time; assert its report rather than stacking a third layer).
• Does NOT claim done without independent runtime verification.

Boundary

This skill governs the pre-PR quality loop: whether the loop's gates are green and you may open the change as a PR. It is not a deploy-mechanics skill. Deploy targets, secret manager, worktree/branch specifics, and CI wiring defer to your project's own doctrine (your repo's AGENTS.md / CLAUDE.md). Route the how/where of deploy to your project's canonical process; this skill only decides whether you may call it ready.

References

• references/ENFORCER.md: base-branch detection, diff computation + non-empty assertion, the reviewer dispatch skeleton, the secret-scan fail-open → re-assert-clean gate, the suite-exit-code capture gate, and the backflow rule. Load when running the loop.