Tdd

Wiki/Forge session context

Resolve vault via KNOWLEDGE_VAULT_ROOT or wiki config --effective --repo <path>. Do not create durable project memory markdown inside the code repo unless the repo itself is the configured vault. Forge-tracked use: obey the active Forge phase packet, its required skills, artifact owner, and allowed writes. Standalone use: route durable memory through Wiki under ${KNOWLEDGE_VAULT_ROOT}/projects/<project>/.

Test-Driven Development

Philosophy

Tests should verify behavior through public interfaces, not implementation details.

Good tests are integration-style: they exercise real code paths through public APIs and describe what the system does.

Bad tests mock internals, test private methods, or break when behavior stays the same. See tests.md, mocking.md, interface-design.md, and deep-modules.md.

Anti-Pattern: Horizontal Slices

DO NOT write all tests first, then all implementation.

Horizontal RED/GREEN creates tests for imagined behavior. Correct approach: Vertical slices via tracer bullets.

RED→GREEN: test1→impl1
RED→GREEN: test2→impl2

Workflow

1. Read domain language and ADRs before naming tests.
2. Ask: "What should the public interface look like? Which behaviors are most important to test?"
3. Write one failing behavior test through the public interface.
4. Write minimal code to pass.
5. Repeat one behavior at a time.
6. Refactor only while green; Never refactor while RED.

Checklist

• Test describes behavior, not implementation.
• Test uses public interface only.
• Test would survive internal refactor.
• No speculative features added.

Ralph loop (fresh-context TDD)

For AFK/unattended work, use the Ralph pattern:

• One behavior per loop iteration — narrow scope produces better outcomes than broad scope.
• State persists via git and tests, not context — commit after each green, reset context if needed.
• Tests are backpressure — they verify non-deterministic agent output did the right thing.
• Never batch tests — write one test, make it pass, repeat. Horizontal slices (all tests first) test imagined behavior.
• Specs as persistent memory — the slice plan and acceptance criteria are re-read each iteration, not carried in context.

Phase: implement

This skill is loaded during the implement phase of the Forge lifecycle.

The agent loops vertically — one behavior at a time:

1. Write a failing test (RED)
2. Record the red evidence
3. Write minimal code to pass (GREEN)
4. Record the green evidence
5. Refactor while green (never refactor while RED)
6. Commit the passing increment
7. Repeat for the next behavior

Commands per iteration:

wiki forge tdd red <project> <slice-id> --test <path> --command "<failing test command>"
wiki forge tdd green <project> <slice-id> --test <path> --command "<passing test command>"

Or the combined form:

wiki forge tdd cycle <project> <slice-id> --test <path> --red-command "<cmd>" --green-command "<cmd>"

After all behaviors are green, the phase advances to verify.

Forge integration

Load this skill when the phase packet lists tdd. Before changing files, ensure /wiki and /forge skills are loaded. Record red/green with wiki forge tdd cycle <project> <slice>; the preferred tdd cycle command may use different red and green commands when they share a --test path. Record targeted verification with wiki forge evidence <project> <slice> verify. After TDD completes: return to /forge — run wiki forge next to advance.