mh-cto-sdlc-tdd-session

TDD Session

Mode: execution. The kickoff is done. The feedback loop is ready. This skill drives the tracer-bullet implementation cycle: one test → one behavior → repeat.

Elite character: TDD is not a test-first ceremony — it is a feedback engineering discipline. The loop is the skill. A tight, deterministic loop transforms debugging from archaeology into surgery. Every passing test is a verified behavior contract. Every refactor is safe because the test suite is the proof.

Contract with tdd-discipline.md: Every step in this skill embeds the TDD discipline reference. The checklist per cycle is not optional — it is the definition of "done for this behavior."

The Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Write code before the test? Delete it. Start over.

• Not "keep it as reference while writing the test" — that's still code-first. Delete means delete.
• Not "adapt it while writing tests" — same violation.
• Not "just this one behavior" — the exception weakens every future boundary.

Violating the letter of this law is violating the spirit of it.

The rationalization table and red flags are in tdd-discipline.md. Read them before beginning. Before claiming this session is complete, run the verification checklist in verification-discipline.md.

Step 1 — Confirm Context

Load the current story from .mh-state/stories/{story-id}/story.md.

Confirm:

• Feedback loop is ready (from story-kickoff)
• First failing test is identified
• Acceptance criteria are clear

If story status is not in-progress: "No story is in-progress. Run /mh-cto-sdlc-story-kickoff first."

Step 2 — Execute the Tracer Bullet Loop

For each behavior in the story's scope, execute the RED → GREEN → LOOP cycle:

RED phase:

• Write ONE test for ONE behavior
• The test must:
  • Describe behavior, not implementation detail
  • Use public interface only (not internal methods)
  • Be written to survive an internal refactor
• Run the test. Confirm it fails for the RIGHT reason (not a syntax error or import failure — a genuine assertion failure).
• "The test fails because: {specific failure message}. This is the correct failure."

GREEN phase:

• Write the MINIMUM code to make this test pass
• No speculative features
• No code not required by this test
• Run the test. It passes.
• "Test passes. Code written: {one sentence description — interface name, not file path}"

REFACTOR phase (after all tests for this behavior pass):

• Extract duplication if it exists
• Deepen modules (move complexity behind simpler interfaces) where warranted
• Apply SOLID principles where natural, not where forced
• Run tests after each refactor step
• Never refactor while RED

Per-behavior checklist:

• [ ] Test describes behavior, not implementation detail
• [ ] Test uses public interface only
• [ ] Test survives an internal refactor
• [ ] Code is minimum to pass this test
• [ ] No speculative features added
• [ ] Tests pass after refactor

Repeat for the next behavior. One behavior at a time.

Step 3 — Instrumentation Discipline

Every debug log added during this session must be tagged: [DEBUG-{short-hash}]

Example: [DEBUG-a4f2] token validation reached

Do not add untagged logs. Cleanup is a grep-and-delete operation.

Track all debug tags added in this session so cleanup is verifiable.

Step 4 — Validate Against Acceptance Criteria

After all behaviors are implemented:

For each acceptance criterion in the story's scope:

• [ ] Is this criterion verifiably met by the test suite?
• [ ] Does the corresponding E2E scenario pass (or will it pass once the full stack is assembled)?
• [ ] Is there a test that would fail if this criterion was violated?

If a criterion has no corresponding test: "AC-{id} '{criterion text}' has no corresponding test. Add the test before advancing to review."

Step 5 — Cleanup Checklist

Before declaring implementation complete:

• [ ] All [DEBUG-...] tags removed (grep for \[DEBUG- to verify)
• [ ] Throwaway harnesses and prototype files deleted
• [ ] Commit message drafted: states the root cause or the behavior delivered (the hypothesis that proved correct)
• [ ] Regression test exists for any bug fixed, or absence of correct seam is documented

Step 6 — TDD-Unready Story Flag

If at any point during implementation a story criterion proves untestable or ambiguous:

"Story criterion AC-{id} '{text}' is not testable as written: {specific reason}. Pausing implementation. Returning this story to create-story for revision."

Update sprint-status.yaml: story status → ready-for-dev. Clear session_state. Do not advance to review with an untestable criterion.

Red Flags — STOP Before Advancing

If any of these are true, do not advance to review:

• Any behavior was implemented before its failing test was written and watched fail
• Any test was written after its implementation (even "just to verify")
• The cleanup checklist in Step 5 was not run
• Any acceptance criterion has no corresponding test
• Debug tags were not grepped and removed
• You are about to say "done" or "complete" without running the test suite fresh in this turn

If any of these apply: address it before Step 7. Advancing with unchecked items is a false completion. See verification-discipline.md for the evidence-before-claims standard.

Step 7 — Advance to Review

When all behaviors are implemented, all criteria are tested, and cleanup is complete:

Update sprint-status.yaml: story status → review.

Update story.md dev-agent-record:

status: review
session_state: ~
last_updated: { YYYY-MM-DD }
implementation_notes: '{key decisions made during implementation — module names, pattern choices, tradeoffs}'

Step 8 — Present Summary

TDD Session complete.

Behaviors implemented: {N}

Tests written: {N} (unit: {N}, integration: {N})

Acceptance criteria verified: {N}/{N}

Debug tags cleaned: {list of removed tags}

Story advanced to: review

Next step: Run /mh-cto-sdlc-code-review to review this story before merging.