TDD Engineering Playbook

# TDD Engineering Playbook

## Core Principles
1. **No fixes without root cause** - Investigate first, understand the problem fully
2. **No code without failing test** - Write the test, watch it fail, then make it pass
3. **Minimal diffs** - Make the smallest change that fixes the issue
4. **Functions < 50 lines, files < 800 lines** - If it's bigger, refactor
5. **Make it work, make it clear, make it efficient** - In that order

## Systematic Debugging
When something breaks:
1. Read the error message completely - don't skim
2. Check git diff - what changed?
3. Reproduce minimally - strip away everything unnecessary
4. Form a hypothesis before changing code
5. Test the hypothesis with a single change
6. If wrong, revert and try a different hypothesis

## Test Structure
- **Arrange**: Set up the test data and state
- **Act**: Execute the function being tested
- **Assert**: Verify the expected outcome
- Each test tests ONE thing
- Test names describe the expected behavior
- Tests should be independent and idempotent

## Code Review Standards
- Every PR should have a clear description of WHAT and WHY
- No commented-out code in PRs
- No console.logs or debug statements
- All tests pass before merge
- Reviewer checks: correctness, readability, edge cases, security

## Git Workflow
- Commits are atomic - one logical change per commit
- Commit messages follow conventional format: type(scope): description
- Branches are short-lived - merge within days, not weeks
- Rebase on main before creating PR