TDD Enforcer

Scope work before coding. Write tests before implementation.

Iron Law: NO IMPLEMENTATION UNTIL SCOPE IS DEFINED AND TEST FAILS

When to Use

Answer IN ORDER. Stop at first match:

1. Implementing new feature? → Use this skill
2. Fixing bug? → Use this skill
3. Adding enhancement? → Use this skill
4. Refactoring? → Use this skill
5. Research/investigation only? → Skip this skill

Phase 0: TRIAGE

Purpose: Determine work level and ensure scope exists.

Source of truth: See Story 1 in .safeword-project/specs/feature-stateful-bdd-flow.md for full detection algorithm rationale.

Step 1: Identify Level

Work levels:

Follow this decision tree. Stop at first match:

Is this explicitly a bug fix, typo, or config change?
├─ Yes → patch (direct fix, no test unless regression-prone)
└─ No ↓

Does request mention "feature", "add", "implement", "support", "build"?
├─ No → task (TDD with E2E test)
└─ Yes ↓

Will it require 3+ files AND (new state OR multiple user flows)?
├─ Yes → feature (BDD) — hand off to safeword-bdd skill
└─ No / Unsure ↓

Can ONE E2E test cover the observable change?
├─ Yes → task (TDD with E2E test)
└─ No → feature (BDD) — hand off to safeword-bdd skill

Fallback: task. User can `/bdd` to override.

Detection signals:

Examples:

Announcement (always):

After detection, announce:

• patch: "Patch. Fixing directly."
• task: "Task. Writing tests first. /bdd to override."
• feature: "Feature. Defining behaviors first. /tdd to override."

Step 2: Check/Create Artifacts

Locations:

• Specs: .safeword/planning/specs/
• Test definitions: .safeword/planning/test-definitions/

Templates:

• feature: @./.safeword/templates/feature-spec-template.md
• task/patch: @./.safeword/templates/task-spec-template.md
• Test Definitions: @./.safeword/templates/test-definitions-feature.md

Exit Criteria

• Level identified (patch/task/feature)
• Spec exists with "Out of Scope" defined
• feature: Test definitions file exists
• task: Test scenarios in spec
• patch: Existing test coverage confirmed

Work Log

Think hard. Keep notes.

Before starting Phase 1, create or open a work log:

Location: .safeword/logs/{artifact-type}-{slug}.md

One artifact = one log. If log exists, append a new session.

Behaviors:

1. Re-read the log before each phase transition
2. Log findings as you discover them
3. Note dead ends so you don't repeat them

Template: @./.safeword/templates/work-log-template.md

Test List (once per slice)

Before starting RED/GREEN/REFACTOR, write the tests you expect for this slice.

Micro-Design (if 2+ new files)

Sketch function signatures and data shapes. 10 lines max—more means you need a design doc first.

Spike (if uncertain)

Phase 1: RED

Iron Law: NO IMPLEMENTATION UNTIL TEST FAILS FOR THE RIGHT REASON

Protocol:

1. Pick ONE test from spec (task) or test definitions (feature)
2. Write test code
3. Run test
4. Verify: fails because behavior missing (not syntax error)
5. Commit: test: [behavior]

For patch: No new test needed. Confirm existing tests pass, then proceed to Phase 2.

Exit Criteria:

• Test written and executed
• Test fails for RIGHT reason (behavior missing)
• Committed: test: [behavior]

Red Flags → STOP:

Phase 2: GREEN

Iron Law: ONLY WRITE CODE THE TEST REQUIRES

Protocol:

1. Write minimal code to pass test
2. Run test → verify pass
3. Commit: feat: or fix:

Exit Criteria:

• Test passes
• No extra code
• No hardcoded/mock values
• Committed

Verification Gate

Before claiming GREEN: Evidence before claims, always.

✅ CORRECT                          ❌ WRONG
─────────────────────────────────   ─────────────────────────────────
Run: bun run test                   "Tests should pass now"
Output: ✓ 34/34 tests pass          "I'm confident this works"
Claim: "All tests pass"             "Tests pass" (no output shown)

The Rule: If you haven't run the verification command in this response, you cannot claim it passes.

Red Flags → STOP:

Anti-Pattern: Mock Implementations

LLMs sometimes hardcode values to pass tests. This is not TDD.

// ❌ BAD - Hardcoded to pass test
function calculateDiscount(amount, tier) {
  return 80; // Passes test but isn't real
}

// ✅ GOOD - Actual logic
function calculateDiscount(amount, tier) {
  if (tier === 'VIP') return amount * 0.8;
  return amount;
}

Fix mocks immediately. The next test cycle will catch them, but they're technical debt.

Phase 3: REFACTOR

Purpose: Improve code structure while keeping behavior identical.

Iron Law: TESTS MUST PASS BEFORE AND AFTER EVERY CHANGE

When to Refactor

Protocol

1. Verify GREEN: Run tests → must pass
2. Pick ONE refactoring from table above
3. Make the change
4. Verify still GREEN: Run tests → must pass
5. Commit: refactor: [what improved]
6. Repeat if more smells exist

Exit Criteria

• Tests pass before AND after each change
• Code cleaner (or no changes needed)
• Each refactoring committed separately

NOT Allowed

Revert Protocol

If tests fail after refactoring:

git checkout -- <changed-files>

Then: Try a smaller refactoring, or skip and move to Phase 4.

Phase 4: ITERATE

More tests in spec/test-definitions?
├─ Yes → Return to Phase 1
└─ No → All "Done When" / AC checked?
        ├─ Yes → Complete
        └─ No → Update spec, return to Phase 0

For feature: Update test definition status (✅/⏭️/❌/🔴) as tests pass.

Quick Reference

Examples

feature ("Add VIP discount"): Phase 0: feature → create spec + test defs → Phase 1: write test → FAIL → commit → Phase 2: implement → PASS → commit → Phase 3: clean up → Phase 4: more tests? → repeat

task ("Fix login timeout"): Phase 0: task → create task spec → Phase 1: write failing test → commit → Phase 2: fix → PASS → commit → Phase 3: clean up if needed → Phase 4: done

patch ("Fix typo"): Phase 0: patch → create minimal spec → Phase 1: no new test (existing tests cover) → Phase 2: fix typo → tests PASS → commit → done

Why patch needs a spec: "Fix typo" can become "refactor error handling" without explicit "Out of Scope".

Integration

Related

• @./.safeword/guides/planning-guide.md
• @./.safeword/guides/testing-guide.md