Windsurf rules

1---
2name: develop-tdd
3model: sonnet
4description: "Test-driven development with red-green-refactor loop using vertical slices. Use for features (epic tasks) or bugs (specs/bugs/BUG-*.md)."
5---
6 
7# Develop TDD
8 
9> **HARD GATE** — Do NOT proceed if on `main` or `master`. Run `kickoff-branch` first to create a feature branch or worktree.
10>
11> **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).
12>
13> **RECURSIVE DISCIPLINE** — This lifecycle applies to EVERY task, including updating these skills. Never skip planning because a task is "meta" or "just documentation."
14 
15## Philosophy
16 
17Tests verify behavior through public interfaces, not implementation details. A good test reads like a specification. See [REFERENCE.md](REFERENCE.md) for the horizontal-slice anti-pattern and TDD phase detail.
18 
19## Red Flags
20 
21If you catch yourself thinking these, stop and reconsider — you are likely deviating from production-grade craft.
22 
23| Red Flag | Reality |
24| :--- | :--- |
25| "This is too simple to need tests." | Simple code is where bugs hide. If it's simple, the test is cheap. |
26| "I'll refactor this later." | "Later" is when technical debt becomes bankruptcy. Refactor while Green. |
27| "The tests are already comprehensive." | If you're adding behavior, you need a new test. Coverage ≠ Correctness. |
28| "I'm just fixing a small bug." | Small bugs often indicate deep interface flaws. Investigate root cause. |
29| "I need to mock this internal class." | Mocking internals couples tests to implementation. Mock only I/O. |
30| "This refactor is out of scope." | Leave the code cleaner than you found it (Boy Scout Rule). |
31| "Preflight failed but it's unrelated." | **Always Green:** any reproducible gate failure routes **quick-fix → fix-bug** before forward work. Session boundaries do not waive Preflight. |
32| "I'll note the red gate and continue." | Narrating a failure is banned. fix-or-log is mandatory per CONVENTIONS § Discovered Defects. |
33 
34## Workflow
35 
36> **Timing:** `bash scripts/bp-timing.sh start develop-tdd` at invocation; `bash scripts/bp-timing.sh end develop-tdd` before handoff.
37 
38### 1. Planning
39 
40- [ ] Read active `specs/epics/*/epic.yaml` story tasks or `specs/bugs/BUG-*.md` — understand verify steps
41- [ ] 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.
42- [ ] Confirm interface changes and behaviors to test (prioritize)
43- [ ] Design interfaces for testability — identify [deep modules](deep-modules.md) opportunities
44- [ ] Get user approval on the plan
45 
46Apply the **enforce-first** F.I.R.S.T rubric: Fast, Independent, Repeatable, Self-Validating, Timely.
47 
48### 2. Tracer Bullet
49 
50Write ONE test that confirms ONE thing about the system:
51 
52```
53RED:    Write test for first behavior → test fails → commit: test(<scope>): ...  (test-only; red in CI)
54GREEN:  Write minimal code to pass → test passes → commit: feat(<scope>): ...   (fix commit; green)
55REFACTOR (optional): clean up → commit: refactor(<scope>): ...
56```
57 
58> **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:
59 
60```bash
61bash scripts/verify-tdd-red-commit.sh
62```
63 
64Show `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.
65 
66> **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.
67 
68### 3. Incremental Loop
69 
70> **Snapshot-before-transition (e45s34):** Before each RED → GREEN or GREEN → REFACTOR transition, create a checkpoint so a failed transition can be rolled back cleanly:
71 
72```bash
73bash scripts/bp-yaml-snapshot.sh specs/state.yaml   # if state changed this cycle
74git stash push -m &quot;tdd-checkpoint-$(git rev-parse --short HEAD)-red&quot; --keep-index 2&gt;/dev/null || true
75```
76 
77After GREEN passes and is committed, drop the stash (`git stash drop` if empty). Never refactor while RED.
78 
79For 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.
80 
81### 4. Visual Slices (UI alternate workflow)
82 
83For 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](REFERENCE.md) for the full Visual Slices procedure.
84 
85### 5. Refactor
86 
87After all tests pass: extract duplication, deepen modules, apply SOLID principles. **Never refactor while RED.**
88 
89### 6. Verify
90 
91After every behavior cycle, run the verify command from the active epic task. Show evidence before declaring the step done.
92 
93### 7. Manual Verification Handover
94 
95Once 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.
96 
97 
98### 6a. CI dry-run sub-step
99 
100If this cycle modified files in `.github/workflows/`, run the CI dry-run procedure documented in [REFERENCE.md](REFERENCE.md#ci-dry-run).
101 
102## Checklist Per Cycle
103 
104```
105[ ] Test describes behavior, not implementation
106[ ] No test is ignored without an explicit ambiguity note (T4)
107[ ] Boundary conditions tested: empty, max, min, off-by-one (T5)
108[ ] Tests verify behavior through public interface only — no private methods (T8)
109[ ] Test would survive internal refactor
110[ ] Code is minimal for this test
111[ ] No speculative features added
112[ ] Every new abstraction has an explicit "Reason for Depth" justification
113[ ] Progress committed (Conventional Commits)
114[ ] verify: command passes
115```
116 
117 
118 
119## Handoff
120 
121Gate: READY -> next: verify-work
122Writes: state.yaml handoff.next_skill = verify-work
123 
124## BCP Plus Integration
125 
126At 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.
127 
128## Verify
129 
130→ 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`
131 
132 
133<!-- story: e02s04 -->
134 
135---
136 
137# Develop TDD — Reference
138 
139## Anti-Pattern: Horizontal Slices
140 
141**DO NOT write all tests first, then all implementation.** This is "horizontal slicing" — treating RED as "write all tests" and GREEN as "write all code."
142 
143This produces **crap tests**:
144- Tests written in bulk test _imagined_ behavior, not _actual_ behavior
145- You end up testing the _shape_ of things rather than user-facing behavior
146- Tests become insensitive to real changes
147 
148**Correct approach**: Vertical slices via tracer bullets. One test → one implementation → repeat.
149 
150```
151WRONG (horizontal):
152  RED:   test1, test2, test3, test4, test5
153  GREEN: impl1, impl2, impl3, impl4, impl5
154 
155RIGHT (vertical):
156  RED→GREEN: test1→impl1
157  RED→GREEN: test2→impl2
158  RED→GREEN: test3→impl3
159  ...
160```
161 
162> The Red Flags table lives in [SKILL.md](SKILL.md#red-flags) — it is core behavioral guidance, not reference detail.
163 
164## TDD Phases (Detail)
165 
166### Red Phase
167 
168Write a failing test first:
169- Test describes the desired observable behavior through the public interface
170- Run the test to confirm it fails for the right reason (not a syntax error, not a typo)
171- Commit: `git commit -m "test(<scope>): <description>"`
172 
173### Green Phase
174 
175Write the minimum code to make the test pass:
176- No extra logic, no anticipated future cases, no premature optimization
177- Focus only on making the current test pass
178- Commit: `git commit -m "feat(<scope>): <description>"` or `"fix(<scope>): <description>"`
179 
180### Refactor Phase
181 
182Improve structure without changing behavior:
183- Extract duplication, apply SOLID principles where natural, deepen modules
184- Run tests after each refactor step to ensure behavior is preserved
185- Commit: `git commit -m "refactor(<scope>): <description>"`
186- Apply the Boy Scout Rule: leave the code cleaner than you found it
187 
188## Visual Slices (UI Alternate Workflow)
189 
190For UI components (SwiftUI, React, Flutter) where behavioral unit testing is brittle or low-signal:
191 
1921. **Test-First Logic**: Extract logic (state transitions, formatting, validation) into a Controller, ViewModel, or Hook. This logic MUST follow pure TDD.
1932. **Visual Verification**: For the View/Component itself:
194   - **RED**: Write the component signature and a basic preview/snapshot that fails (or displays placeholder).
195   - **GREEN**: Implement the UI and verify visually via manual run, preview, or snapshot test.
196   - **REFINE**: Adjust styling and layout until it matches the design.
1973. **COMMIT**: `git commit -m "feat(ui): <component name> visual slice verified"`
198 
199---
200 
201# Deep Modules
202 
203From "A Philosophy of Software Design":
204 
205**Deep module** = small interface + lots of implementation
206 
207```
208┌─────────────────────┐
209│   Small Interface   │  ← Few methods, simple params
210├─────────────────────┤
211│                     │
212│                     │
213│  Deep Implementation│  ← Complex logic hidden
214│                     │
215│                     │
216└─────────────────────┘
217```
218 
219**Shallow module** = large interface + little implementation (avoid)
220 
221```
222┌─────────────────────────────────┐
223│       Large Interface           │  ← Many methods, complex params
224├─────────────────────────────────┤
225│  Thin Implementation            │  ← Just passes through
226└─────────────────────────────────┘
227```
228 
229When designing interfaces, ask:
230 
231- Can I reduce the number of methods?
232- Can I simplify the parameters?
233- Can I hide more complexity inside?
234 
235---
236 
237# Interface Design for Testability
238 
239Good interfaces make testing natural:
240 
2411. **Accept dependencies, don't create them**
242 
243```typescript
244   // Testable
245   function processOrder(order, paymentGateway) {}
246 
247   // Hard to test
248   function processOrder(order) {
249     const gateway = new StripeGateway();
250   }
251```
252 
2532. **Return results, don't produce side effects**
254 
255```typescript
256   // Testable
257   function calculateDiscount(cart): Discount {}
258 
259   // Hard to test
260   function applyDiscount(cart): void {
261     cart.total -= discount;
262   }
263```
264 
2653. **Small surface area**
266   - Fewer methods = fewer tests needed
267   - Fewer params = simpler test setup
268 
269---
270 
271# When to Mock
272 
273Mock at **system boundaries** only:
274 
275- External APIs (payment, email, etc.)
276- Databases (sometimes - prefer test DB)
277- Time/randomness
278- File system (sometimes)
279 
280Don't mock:
281 
282- Your own classes/modules
283- Internal collaborators
284- Anything you control
285 
286## Designing for Mockability
287 
288At system boundaries, design interfaces that are easy to mock:
289 
290**1. Use dependency injection**
291 
292Pass external dependencies in rather than creating them internally:
293 
294```typescript
295// Easy to mock
296function processPayment(order, paymentClient) {
297  return paymentClient.charge(order.total);
298}
299 
300// Hard to mock
301function processPayment(order) {
302  const client = new StripeClient(process.env.STRIPE_KEY);
303  return client.charge(order.total);
304}
305```
306 
307**2. Prefer SDK-style interfaces over generic fetchers**
308 
309Create specific functions for each external operation instead of one generic function with conditional logic:
310 
311```typescript
312// GOOD: Each function is independently mockable
313const api = {
314  getUser: (id) => fetch(`/users/${id}`),
315  getOrders: (userId) => fetch(`/users/${userId}/orders`),
316  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
317};
318 
319// BAD: Mocking requires conditional logic inside the mock
320const api = {
321  fetch: (endpoint, options) => fetch(endpoint, options),
322};
323```
324 
325The SDK approach means:
326- Each mock returns one specific shape
327- No conditional logic in test setup
328- Easier to see which endpoints a test exercises
329- Type safety per endpoint
330 
331---
332 
333# Refactor Candidates
334 
335After TDD cycle, look for:
336 
337- **Duplication** → Extract function/class
338- **Long methods** → Break into private helpers (keep tests on public interface)
339- **Shallow modules** → Combine or deepen
340- **Feature envy** → Move logic to where data lives
341- **Primitive obsession** → Introduce value objects
342- **Existing code** the new code reveals as problematic
343 
344---
345 
346# Good and Bad Tests
347 
348## Good Tests
349 
350**Integration-style**: Test through real interfaces, not mocks of internal parts.
351 
352```typescript
353// GOOD: Tests observable behavior
354test("user can checkout with valid cart", async () => {
355  const cart = createCart();
356  cart.add(product);
357  const result = await checkout(cart, paymentMethod);
358  expect(result.status).toBe("confirmed");
359});
360```
361 
362Characteristics:
363 
364- Tests behavior users/callers care about
365- Uses public API only
366- Survives internal refactors
367- Describes WHAT, not HOW
368- One logical assertion per test
369 
370## Bad Tests
371 
372**Implementation-detail tests**: Coupled to internal structure.
373 
374```typescript
375// BAD: Tests implementation details
376test("checkout calls paymentService.process", async () => {
377  const mockPayment = jest.mock(paymentService);
378  await checkout(cart, payment);
379  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
380});
381```
382 
383Red flags:
384 
385- Mocking internal collaborators
386- Testing private methods
387- Asserting on call counts/order
388- Test breaks when refactoring without behavior change
389- Test name describes HOW not WHAT
390- Verifying through external means instead of interface
391 
392```typescript
393// BAD: Bypasses interface to verify
394test("createUser saves to database", async () => {
395  await createUser({ name: "Alice" });
396  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
397  expect(row).toBeDefined();
398});
399 
400// GOOD: Verifies through interface
401test("createUser makes user retrievable", async () => {
402  const user = await createUser({ name: "Alice" });
403  const retrieved = await getUser(user.id);
404  expect(retrieved.name).toBe("Alice");
405});
406```
407 
408## Clean Test Heuristics (Uncle Bob, Ch 17)
409 
410Apply these specific heuristics to maintain a high-quality suite:
411 
412- **T1: Insufficient Tests**: A test suite should test everything that could possibly break. Don't stop at "it seems to work."
413- **T4: Ignored Tests**: Never ignore a test without documenting the ambiguity. An ignored test is a silent warning of a gap in understanding.
414- **T5: Test Boundary Conditions**: Most bugs happen at the edges. Test the exact boundaries (e.g., empty strings, max integers, off-by-one indices).
415- **T6: Exhaustively Test Near Bugs**: Bugs congregate. If you find one, there are likely others nearby; test that area thoroughly.
416- **T9: Tests Should Be Fast**: Slow tests don't get run. Keep them fast so they remain part of the core developer loop.
417