danielvm-git/bigpowers/develop-tdd

Develop TDD

HARD GATE — Do NOT proceed if on main or master. Run kickoff-branch first to create a feature branch or worktree.

HARD GATE — Do NOT write code before you have a plan. New feature: plan-work → epic capsule tasks. Bug: investigate-bug → specs/bugs/BUG-*.md (or use fix-bug orchestrator).

RECURSIVE DISCIPLINE — This lifecycle applies to EVERY task, including updating these skills. Never skip planning because a task is "meta" or "just documentation."

Philosophy

Tests verify behavior through public interfaces, not implementation details. A good test reads like a specification. See REFERENCE.md for the horizontal-slice anti-pattern and TDD phase detail.

Red Flags

If you catch yourself thinking these, stop and reconsider — you are likely deviating from production-grade craft.

Workflow

Timing: bash scripts/bp-timing.sh start develop-tdd at invocation; bash scripts/bp-timing.sh end develop-tdd before handoff.

1. Planning

• [ ] Read active specs/epics/*/epic.yaml story tasks or specs/bugs/BUG-*.md — understand verify steps
• [ ] If specs/tech-architecture/eNN-TEST_PLAN_LATEST.md exists for the active epic, read it before writing the first test. Implement P0 scenarios (SC-*-P0-*) before P1. P2/P3 scenarios are optional per time budget.
• [ ] Confirm interface changes and behaviors to test (prioritize)
• [ ] Design interfaces for testability — identify deep modules opportunities
• [ ] Get user approval on the plan

Apply the enforce-first F.I.R.S.T rubric: Fast, Independent, Repeatable, Self-Validating, Timely.

2. Tracer Bullet

Write ONE test that confirms ONE thing about the system:

RED:    Write test for first behavior → test fails → commit: test(<scope>): ...  (test-only; red in CI)
GREEN:  Write minimal code to pass → test passes → commit: feat(<scope>): ...   (fix commit; green)
REFACTOR (optional): clean up → commit: refactor(<scope>): ...

Two-commit red/green policy (HARD GATE — e45s08) — Each behavior cycle requires two separate commits: (1) test-only commit that fails in CI (RED), then (2) implementation commit that makes it pass (GREEN). Never combine test + fix in one commit. Before proceeding, run the mechanical RED isolation check:

bash scripts/verify-tdd-red-commit.sh

Show git log -2 --oneline and the script output as evidence. If the test-only commit passes in isolation, the RED gate is violated — stop and fix before GREEN.

tasks.yaml ledger (e45s06) — After each task's verify: exits 0, update eNNsYY-tasks.yaml: set that task's status: passing. Story-level status: passing only when all tasks pass.

3. Incremental Loop

Snapshot-before-transition (e45s34): Before each RED → GREEN or GREEN → REFACTOR transition, create a checkpoint so a failed transition can be rolled back cleanly:

bash scripts/bp-yaml-snapshot.sh specs/state.yaml   # if state changed this cycle
git stash push -m "tdd-checkpoint-$(git rev-parse --short HEAD)-red" --keep-index 2>/dev/null || true

After GREEN passes and is committed, drop the stash (git stash drop if empty). Never refactor while RED.

For each remaining behavior: RED → GREEN → REFACTOR (optional). One test at a time. Two commits per behavior (test-only RED, then fix GREEN). Commit after every GREEN phase.

4. Visual Slices (UI alternate workflow)

For UI components where behavioral unit testing is brittle: extract logic into a Controller/ViewModel/Hook (pure TDD), then use Visual Slices for the View layer. See REFERENCE.md for the full Visual Slices procedure.

5. Refactor

After all tests pass: extract duplication, deepen modules, apply SOLID principles. Never refactor while RED.

6. Verify

After every behavior cycle, run the verify command from the active epic task. Show evidence before declaring the step done.

7. Manual Verification Handover

Once all tests pass: locate the Verification Script in the active epic capsule, present it to the user step-by-step, and wait for confirmation of behavioral correctness.

6a. CI dry-run sub-step

If this cycle modified files in .github/workflows/, run the CI dry-run procedure documented in REFERENCE.md.

Checklist Per Cycle

[ ] Test describes behavior, not implementation
[ ] No test is ignored without an explicit ambiguity note (T4)
[ ] Boundary conditions tested: empty, max, min, off-by-one (T5)
[ ] Tests verify behavior through public interface only — no private methods (T8)
[ ] Test would survive internal refactor
[ ] Code is minimal for this test
[ ] No speculative features added
[ ] Every new abstraction has an explicit "Reason for Depth" justification
[ ] Progress committed (Conventional Commits)
[ ] verify: command passes

Handoff

Gate: READY -> next: verify-work Writes: state.yaml handoff.next_skill = verify-work

BCP Plus Integration

At story completion, if the story was sized with BCP Plus (13-dimension breakdown), log the bcp_plus.total alongside the standard bcps: count in the story's tasks.yaml. The breakdown is available from the epic capsule's bcp_plus_breakdown field. See docs/references/bcp-plus.md for the full methodology and NFR Gate pattern.

Verify

→ verify: test -x scripts/verify-tdd-red-commit.sh && bash scripts/verify-tdd-red-commit.sh --self-test && grep -q 'verify-tdd-red-commit' skills/develop-tdd/SKILL.md && echo OK

<!-- story: e02s04 -->