# TDD Workflow Rules

When `use_tdd=true` in `tas.yaml`, enforce strict Red-Green-Refactor cycle.
No exceptions — every feature starts with test.

## When to Apply

- Implement new Feature with clear Acceptance Criteria (Given/When/Then)
- Bug fix: write regression test before fixing
- Refactor: ensure test coverage before changing code
- DON'T use TDD for: config changes, documentation, pure data migration scripts

## Always / Ask / Never

| | Action |
|---|---|
| **Always** | Write test FIRST, run to confirm FAIL, then write code |
| **Always** | Commit after each successful Green phase |
| **Always** | Run full test suite after Refactor phase |
| **Ask** | When acceptance criteria vague — clarify before writing test |
| **Ask** | When test too hard to write — interface/design may need improvement |
| **Never** | Write implementation before test (even "just to try") |
| **Never** | Skip Red phase because "test will obviously fail" |
| **Never** | Write more than minimal code needed to pass test in Green phase |

## Process

### Red Phase — Write Test First

1. Read Acceptance Criteria in the Feature, plus Unit Test Cases tables in `Feature-{NNN}-Technical.md`
2. Write test cases covering each AC (platform-specific stacks per `/tas-dev`)
3. Run tests: `npm test` / `yarn test` / `dotnet test` / `python -m pytest`
4. **Verify**: tests MUST FAIL — if pass immediately → test is wrong, rewrite

### Green Phase — Minimal Code

1. Write minimal code to pass tests
2. Don't refactor, don't optimize in this phase
3. Run tests: confirm PASS
4. **Verify**: all new tests pass, no regression

### Refactor Phase — Clean Up

1. Remove duplication, improve naming, reduce complexity
2. DON'T change behavior — tests are safety net
3. Run full test suite after each refactor step
4. **Verify**: coverage >= 80%, all tests still pass
5. Commit after successful refactor

## Red Flags

- Test passes on first run before implementation → test doesn't test what it should
- Test too broad ("everything works") → no value, write more specific test
- Green phase has too much logic → only write enough to pass, no more
- Refactor phase makes tests fail → refactor is wrong, roll back step by step
- Writing multiple tests at once before fixing each → only fix one test at a time

## Verification Checklist

- [ ] Red: test file exists and runs with FAIL output
- [ ] Green: test output changes from FAIL → PASS after adding implementation
- [ ] Refactor: `npm test` / `dotnet test` / `pytest` full suite PASS
- [ ] Coverage report: >= 80% for changed files
- [ ] No tests skipped or commented out

## Test Naming Convention

Anchor on **AC**, not Story (Story removed in kit v3).

```
{PROJECT}_F{FEATURE}_AC{N}_{TYPE}_{NUMBER}_{MODIFIER}
```

For E2E (which spans multiple Features), drop the Feature/AC segment:

```
{PROJECT}_E2E_{NUMBER}_{MODIFIER}        # single-stack
{PROJECT}_XSTACK_E2E_{NUMBER}_{MODIFIER} # cross-stack
```

| TYPE | Meaning | Layer |
|------|---------|-------|
| UT | Unit Test | 1 |
| IT | Integration Test | 1 |
| API | API Test | 1 |
| FT | Functional Test | 2 |
| E2E | End-to-End Test | 3 |

MODIFIER: `H` (Happy), `N` (Negative), `E` (Edge), `S` (Security), `P` (Performance)

Examples:
- `AL_F012_AC1_UT_001_H` — Feature 012, AC-1, Unit Test 001, Happy
- `AL_F012_AC2_FT_003_N` — Feature 012, AC-2, Functional Test 003, Negative
- `AL_E2E_005_H`         — End-to-End scenario 005, Happy
- `AL_XSTACK_E2E_002_H`  — Cross-stack End-to-End scenario 002, Happy

## Anti-Rationalization

| Rationalization | Counter |
|---|---|
| "Test will obviously fail, no need to run" | Skipping Red phase loses verification point — always run |
| "Writing test after is faster" | TDD saves more debugging time than time spent writing tests first |
| "This code is too simple for tests" | Simple today, complex after refactor — tests protect future changes |
| "Interface not clear, write code first for clarity" | Test hard to write is signal interface needs improvement — Ask, don't skip |