Adopt TDD approach in bugfix workflow

[eranco74]

Summary

Refactor the bugfix workflow to follow a Test-Driven Development approach: write a failing test before implementing the fix, rather than writing tests alongside the fix in the same phase.

Motivation

Currently, the /fix phase writes both the code fix and the tests together. This creates a subtle problem: when the agent already knows the fix, it tends to write tests that target the specific code change rather than the observable behavior. Tests written without knowledge of the fix are more durable — they survive refactors, catch regressions regardless of implementation approach, and serve as a stronger validation that the diagnosis is correct.

A failing test before the fix also acts as a diagnosis validator — if you can't write a failing test from the diagnosis alone, the diagnosis may be wrong or too vague.

Proposed Changes

New phase flow

Current:  /diagnose → /fix (code + tests) → /test (run & verify) → /review → lint → /document
Proposed: /diagnose → /plan → /test-red → /fix → /test-green → /review → lint → /document

New phases

/plan (between /diagnose and /fix)

• Reads root-cause.md and produces fix-plan.md with two clearly separated sections:
  • Test Strategy — describes the bug in behavioral terms: inputs, current (broken) behavior, correct behavior, test setup. Does NOT describe what code to change.
  • Fix Approach — describes the implementation: files to modify, code change strategy, alternatives considered.
• Separating these sections is key: /test-red reads only the Test Strategy, not the Fix Approach.

/test-red (replaces the test-writing part of the old /fix and /test)

• Reads only fix-plan.md § Test Strategy and root-cause.md
• Writes a regression test that captures the buggy behavior
• Runs the test — must fail (red). If it passes, the test doesn't actually catch the bug; rework it
• Does NOT read § Fix Approach

Modified phases

/fix — no longer writes tests

• Reads fix-plan.md § Fix Approach and the failing test from /test-red
• Implements the minimal fix to make the test pass (green)
• Still produces implementation-notes.md

/test-green (was /test) — no longer creates regression tests

• Runs the full test suite to catch regressions
• Adds additional edge-case tests if coverage gaps exist
• Still produces verification.md

Updated unattended phase loop

 | Order | Phase       | Skill file      | Done signal                              |
 |-------|-------------|-----------------|------------------------------------------|
 | 1     | /diagnose   | diagnose.md     | Root cause analysis written              |
-| 2     | /fix        | fix.md          | Code and test changes in working tree    |
-| 3     | /test       | test.md         | All tests pass; verification written     |
+| 2     | /plan       | plan.md         | Fix plan with test strategy + approach   |
+| 3     | /test-red   | test-red.md     | Failing test in working tree             |
+| 4     | /fix        | fix.md          | Code changes make test pass (green)      |
+| 5     | /test-green | test-green.md   | Full suite passes; verification written  |
 | ...   | /review     | review.md       | Review findings written                  |

Updated feedback loops

Loop	Trigger	Action
/test-red self-loop	Test passes (bad — doesn't catch the bug)	Rework test, re-run
/fix ↔ /test-green	Full suite fails	Rework fix, re-run full suite

Comparison

Concern	Current	TDD
When tests are written	During /fix, alongside code	During /test-red, before code
What informs tests	Root cause + fix implementation	Root cause + behavioral contract only
Proof test catches the bug	/test Step 1 tries to verify retroactively	/test-red — test must fail before fix exists
Number of phases	6	8
Feedback loops	1 (test↔fix)	2 (test-red self-loop, fix↔test-green)

Implementation

New/modified skill files:

• skills/plan.md — new
• skills/test-red.md — new
• skills/fix.md — remove test-writing steps
• skills/test.md → skills/test-green.md — remove test-creation steps, focus on full suite
• skills/unattended.md — update phase loop, feedback loops, and phase overrides
• skills/controller.md — add new phases to the workflow routing
• commands/plan.md, commands/test-red.md, commands/test-green.md — new command entry points

[adalton]

Thanks for the detailed write-up. The motivation is valid — tests written alongside the fix tend to mirror the implementation rather than the behavior, and proving a test catches the bug before the fix exists is a stronger guarantee. That said, I think the proposed solution is significantly more complex than it needs to be.

The TDD phase structure doesn't translate well to AI agents. TDD's red-green-refactor cycle exists because humans need a forcing function to think about requirements before jumping to code. An AI agent doesn't have that impulse — it does what the prompt tells it. Splitting into /test-red and /test-green phases borrows the ritual without the underlying reason the ritual works.

The information barrier is unenforceable. The proposal gates /test-red to only read the Test Strategy section of fix-plan.md, not the Fix Approach. But the diagnosis itself implies the fix for most bugs. "Off-by-one in the loop bound on line 42" — the agent already knows the fix. You can't un-know it by hiding a document section.

/plan is redundant with /diagnose. A good diagnosis already identifies what's broken, why, and what needs to change. If root-cause.md is missing behavioral contract language (inputs, broken output, expected output), that's a template problem in /diagnose, not a reason to add a reformatting phase.

/test-green is just running tests. Stripping test-creation out of /test and renaming it doesn't add value — it makes the phase thinner while adding a jargon name.

Going from 6 to 8 phases has real cost. Each phase transition is a context boundary with artifact I/O and re-orientation overhead. That cost applies to every bug, including trivial ones.

Counter-proposal

We can get the same quality improvement without adding phases:

1. Update /fix to enforce test-first ordering within the phase. Write the regression test first, run it, assert it fails, then implement the fix, run the test again and assert it passes. Same guarantee as /test-red → /fix, one phase instead of two.
2. Tighten the /diagnose output template to require behavioral contract language — inputs, current (broken) behavior, expected behavior — so the test-writing step in /fix has better source material.
3. Keep the phase count at 6. The lever here is prompt quality in the existing phases, not phase decomposition.