executing-tdd-cycle

# Executing TDD Cycles ## Overview Transform a cycle task list into implemented code via strict red/green/refactor discipline. Parse tasks from `tasks.md`, write failing tests first, implement code to pass them, refactor, mark tasks complete, and produce a structured `cycle-report.md`. This skill governs both normal cycle execution and retry/fix modes. **Violating the letter of the rules is violating the spirit of the rules.** TDD discipline exists to catch failures before they compound. Every shortcut in this process is a regression waiting to happen. ## When to Use - Executing a cycle's task list from `tasks.md` - Retry after checkpoint failure (targeted rework) - Fix mode after final-validation failure (unconstrained by cycle boundaries) - Any task with `[EXTEND]` or `[MODIFY]` markers (invoke `brownfield-integration` skill alongside) - Writing cycle-report.md after cycle completion ## When NOT to Use - Running quality gates (lint, build, test suite) — handled by the verification skill - Parsing or evaluating checkpoint/validation reports — handled by the analysis layer - Deciding which cycle to execute next — determined by the instructions provided - Modifying DAG state or pass lifecycle — handled by the graph operations layer ## Core Process ### Cycle Execution Sequence Execute in strict order. No skipping steps. No reordering. **1. Parse Cycle Tasks** Extract the task list for the current cycle from `tasks.md`. See [references/TASK-PARSING.md](references/TASK-PARSING.md) for parsing rules. For each task, extract: - Task ID (`T{N}.{X}`) - Description - File path(s) in backticks - `[EXTEND]` or `[MODIFY]` markers - Sub-bullet details **2. Red Phase — Write Failing Tests** For each task that specifies a test: 1. Write the test file at the specified path 2. Run the test to verify it **fails** 3. Verify the failure reason matches expectations (not a syntax error, import error, or wrong assertion) 4. If the test passes without implementation, the test is not testing what you think — rewrite it **3. Green Phase — Implement Code** For each implementation task: 1. Write the minimum code to make the failing test pass 2. Run the test to verify it **passes** 3. Do not add features, abstractions, or optimizations the task did not request 4. For `[EXTEND]` tasks: read the existing file first, follow existing patterns (invoke `brownfield-integration` skill) 5. For `[MODIFY]` tasks: read the existing file first, change only what the task specifies (invoke `brownfield-integration` skill) **4. Refactor Phase** After tests pass: 1. Remove duplication introduced in this cycle only 2. Improve names if unclear 3. Do NOT refactor code from previous cycles 4. Do NOT add abstractions "for the future" 5. Re-run tests after refactoring to confirm they still pass **5. Mark Tasks Complete** Update `tasks.md`: change `- [ ]` to `- [x]` for each completed task in this cycle. **6. Write Cycle Report** Produce `cycle-report.md` following the format in [references/CYCLE-REPORT-FORMAT.md](references/CYCLE-REPORT-FORMAT.md). ### Progress Tracking - Mark each task `[x]` in `tasks.md` immediately after completing it - Write `cycle-report.md` with YAML frontmatter and prose sections - Frontmatter provides structured data for the checkpoint gate - Prose sections provide context for the State Analyst and carry_forward ### Retry Handling When dispatched after a checkpoint failure: 1. Read the checkpoint report to identify specific failures 2. Trace each failure to the responsible task(s) 3. Re-open failed tasks: change `- [x]` back to `- [ ]` in `tasks.md` 4. Execute only the re-opened tasks through the red/green/refactor cycle 5. Do NOT re-implement tasks that passed — they are done 6. Write a new `cycle-report.md` with updated attempt number ### Fix Mode When dispatched after final-validation failure: 1. Read the final-validation report to identify specific failures 2. Fix each failure — you are NOT constrained by cycle boundaries 3. May touch files from any cycle as needed to resolve failures 4. Scope strictly to reported failures — this is not a refactoring opportunity 5. Write `cycle-report.md` with `cycle: fix` in frontmatter ## Red Flags — STOP and Restart Properly If any of these thoughts arise, STOP immediately: - "The test already passes so I'll skip writing it first" - "I'll write all the code first and tests after" - "This task is trivial, no test needed" - "I'll refactor this existing code while I'm here" - "The task says EXTEND but I need to rewrite this" - "I'll add this helper/utility that will be useful later" - "The checkpoint will catch it if something's wrong" - "I know this works from the previous cycle" **All of these mean:** Rationalization in progress. Return to the execution sequence. Follow every step. **No exceptions:** - Not for "trivial" tasks - Not for "obvious" implementations - Not for "tight deadlines" - Not for "I already know this works" - Not even if the user says "just write the code" See [references/TDD-ANTI-RATIONALIZATION.md](references/TDD-ANTI-RATIONALIZATION.md) for the full rationalization table. ## Common Mistakes ### Mistake: Writing Tests After Implementation **What goes wrong:** Tests become retroactive justification. They pass because they were written to match the code, not because the code satisfies the requirement. **Fix:** Always write the test first. Run it. Verify it fails for the right reason. Then implement. ### Mistake: Full Cycle Re-Implementation on Retry **What goes wrong:** Working code gets rewritten, introducing new bugs. Token budget wasted on already-complete tasks. **Fix:** Trace failures to specific tasks. Re-open only those tasks. Leave passing code untouched. ### Mistake: Scope Creep During Refactor Phase **What goes wrong:** "While I'm here" changes accumulate. New bugs appear in code that was working. Cycle report doesn't reflect actual changes. **Fix:** Refactor phase is limited to code introduced in this cycle. Note improvement opportunities in the cycle report's "Notes for Next Cycle" section. ### Mistake: Skipping Failure Reason Verification **What goes wrong:** Test fails due to syntax error or wrong import, not because the assertion caught a missing implementation. Green phase "passes" the test by fixing the syntax, not by implementing the feature. **Fix:** After writing a failing test, verify the failure message matches your expectation. A `ModuleNotFoundError` is not a meaningful test failure. ## Reference Files - [references/CYCLE-REPORT-FORMAT.md](references/CYCLE-REPORT-FORMAT.md) — Structured YAML frontmatter schema and prose sections - [references/TASK-PARSING.md](references/TASK-PARSING.md) — Task pattern extraction, file paths, markers - [references/TDD-ANTI-RATIONALIZATION.md](references/TDD-ANTI-RATIONALIZATION.md) — Common shortcuts and why they fail