test-writer

Test Writer

Write failing tests that define what "done" means. Behavioral tests verify acceptance criteria. Conformance tests verify the architecture is followed — not faked.

Boundaries

This skill MAY: read stories and architecture docs, write test files, run the test suite. This skill MAY NOT: write implementation code, modify existing source files, fix failing tests by changing expectations.

ALL tests must FAIL when this skill completes. That's the point — RED state.

Common Rationalizations

Shortcut	Why It Fails	The Cost
"Write tests that pass with mocks"	Tests that pass with mocks prove nothing about real behavior	False confidence → bugs in production
"Skip conformance tests — unit tests are enough"	Unit tests don't verify architecture compliance	Stubs pass tests, real deps aren't wired
"Relax assertions — they're too strict"	Loose assertions let wrong implementations pass	Tests are decoration, not verification
"Test the happy path only"	Edge cases are where bugs hide	Happy path works, edge cases crash

---

Step 1: Read Stories

If $STORIES_PATH is set (pipeline mode):

1. Read the stories file at $STORIES_PATH
2. Extract all stories with their acceptance criteria and edge cases

If no env var (standalone mode):

1. Search docs/stories/ for recent story files
2. If found: Use AskUserQuestion (header: "Stories", question: "Found stories: [list]. Which should I write tests for?") with each as an option
3. If not found: Use AskUserQuestion (header: "Stories", question: "Where are the stories? Provide a path, or describe what to test.")

Exit: Stories loaded, acceptance criteria extracted.

---

Step 2: Read Architecture Doc

If $ARCH_PATH is set (pipeline mode):

1. Read the architecture doc at $ARCH_PATH
2. Extract: dependencies, integration pattern, file structure

If no env var (standalone mode):

1. Look for *.architecture.md near the stories file
2. If found: Read it automatically
3. If not found: Use AskUserQuestion (header: "Architecture", question: "Is there an architecture doc? Provide path or skip.") with options: "Skip (behavioral tests only)" and "Provide path"

Exit: Architecture context loaded (or skipped for standalone behavioral-only mode).

---

Step 3: Write Behavioral Tests

For each story, write tests that verify acceptance criteria:

Test naming convention: Match project conventions (from CLAUDE.md or existing tests).

Rules:

• One test per acceptance criterion — no bundled assertions
• Each test references its story: // STORY-001: criterion description
• Tests assert on observable behavior, not implementation details
• Edge cases from stories become explicit test cases
• Tests MUST import from the expected implementation paths (from architecture doc's File Structure)
• Tests MUST call real functions with real arguments — no mocks of the thing under test

Anti-patterns to avoid (see anti-patterns.md):

• Testing that a function exists (it always will once created)
• Asserting on return type only (any stub returns the right type)
• Mocking the module under test
• Testing internal state instead of behavior

Exit: Behavioral test files written.

---

Step 4: Write Conformance Tests

Skip this step if no architecture doc is available.

For each dependency and integration point in the architecture doc, write tests that verify compliance:

Rules:

• For each dependency listed: test that it is imported and used in the source
• For each integration pattern: test that the pattern is followed (events emitted, entry points exist)
• For each file in the File Structure: test that it exists and exports expected symbols

Conformance test patterns (see conformance-patterns.md):

• Import verification: test that source files import listed dependencies
• Pattern verification: test that the integration pattern is followed
• Structure verification: test that files exist at expected paths

Exit: Conformance test files written.

---

Step 5: Verify RED State

Run the full test suite:

# Use project's test command
npm test 2>&1 || true

ALL tests must fail. This is the executable self-check.

If any tests pass:

1. Identify which tests are passing and why
2. Fix the tests to be more specific (tighter assertions, real imports, no mocks)
3. Re-run and verify

Retry up to 3 times. If tests still pass after 3 attempts, report the issue:

INCOMPLETE: {N} tests are passing when they should fail.
Passing tests: {list}
Reason: {why they pass — likely testing something that already exists}

Exit: All tests fail (RED state confirmed) or INCOMPLETE reported.

---

Validate

Before completing, verify:

• Every acceptance criterion has at least one test
• Every test references its story ID (STORY-NNN)
• Conformance tests cover every dependency in the architecture doc
• ALL tests fail — RED state confirmed by running the suite
• No mocks of the module under test — tests call real functions
• Edge cases from stories have explicit test cases
• Test files are at the paths expected by the project's test framework

What Makes This Heart of Gold

• Building (4.3): Tests define "done" before implementation starts — the foundation of TDD.
• The 90/10 Craft (4.2): Conformance tests catch stubs. They verify architecture is real, not faked.
• Critical Trust (2.1): RED state is verified by running the suite, not by assumption.
• Creative Courage (4.1): Testing edge cases takes courage — it's where the uncomfortable truths live.

Knowledge References

• ./anti-patterns.md — Weak test patterns that pass with stubs
• ./conformance-patterns.md — How to write tests that verify architecture compliance