srnnkls/test

Test-Driven Development

Write the test first. Watch it fail. Write minimal code to pass.

Core principle: If you didn't watch the test fail, you don't know if it tests the right thing.

---

When to Use

Always use for:

• New features
• Bug fixes
• Behavior changes
• Refactoring

Exceptions (confirm with user):

• Throwaway prototypes
• Generated code
• Configuration files

Workflow Integration:

• Multiple independent tasks from a scope? → Use implement skill (it runs the scope execution pipeline)
• Single implementation task? → Use implement skill (it dispatches tester + implementer subagents)
• This skill is for subagents — tester subagents invoke this skill to follow TDD methodology. The orchestrator never invokes this skill directly to write tests.

---

The Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Wrote code before the test? Delete it. Start over. No exceptions.

---

Red-Green-Refactor Cycle

1. RED - Write Failing Test

Write one minimal test showing what should happen.

Requirements:

• One behavior per test
• Clear name describing behavior
• Real code (avoid mocks unless unavoidable)

2. Verify RED - Watch It Fail

MANDATORY. Never skip.

Run the test. Confirm:

• Test fails (not errors from typos)
• Failure message matches expectation
• Fails because feature is missing

Test passes immediately? You're testing existing behavior. Fix the test.

3. GREEN - Minimal Code

Write the simplest code to pass the test.

DO: Just enough to pass, simple implementation DON'T: Add features, refactor other code, add configurability

4. Verify GREEN - Watch It Pass

MANDATORY.

Run the test. Confirm:

• Test passes
• Other tests still pass
• No errors or warnings

5. REFACTOR - Clean Up

Only after green:

• Remove duplication
• Improve names
• Extract helpers

Keep tests green. Don't add behavior.

6. Repeat

Next failing test for next behavior.

---

Common Rationalizations

| Excuse | Reality | |--------|---------| | "Too simple to test" | Simple code breaks. Test takes 30 seconds. | | "I'll test after" | Tests passing immediately prove nothing. | | "Already manually tested" | Ad-hoc is not systematic. No record, can't re-run. | | "Deleting X hours is wasteful" | Sunk cost fallacy. Unverified code is debt. | | "Need to explore first" | Fine. Throw away exploration, then TDD. | | "Test hard to write" | Hard to test = hard to use. Simplify design. |

---

Red Flags - Stop and Start Over

• Code written before test
• Test passes immediately
• Can't explain why test failed
• "Just this once" rationalization
• Keeping code "as reference"

All of these mean: Delete code. Start with TDD.

---

Verification Checklist

Before marking work complete:

• [ ] Every new function has a test
• [ ] Watched each test fail before implementing
• [ ] Each test failed for expected reason
• [ ] Wrote minimal code to pass each test
• [ ] All tests pass
• [ ] No errors or warnings in output

---

TDD Evidence Format (For Subagent Verification)

When implementing as a subagent, you MUST output this evidence block:

tdd_evidence:
  tests_written:
    - name: "test_feature_x"
      file: "tests/test_x.py"
      red_output: "FAILED - [actual failure message]"
      green_output: "PASSED - 1 passed in 0.05s"
  implementation_files:
    - path: "src/feature.py"
  all_tests_pass: true
  test_command: "pytest tests/test_x.py -v"
  final_output: "[full test output]"

This is REQUIRED for SubagentStop hook verification.

---

Domain Context

Domain skills inject specifics into this generic methodology:

• code: Language-specific test conventions via loqui, test frameworks
• doc: Documentation validation, link checking

When invoked via a domain skill, follow the domain-specific test guidance provided.

---

Integration

Use with:

• implement (debug operation) - Write failing test to reproduce bug before fixing
• implement (execute operation) - Subagents follow TDD for each task
• implement (verify operation) - Run tests before claiming completion