Test Plan First

When to use

• Implementing a feature, bug fix, or behavior change with testable outcomes.
• The user asks for "TDD", "tests first", or "how will we verify this?".
• You are about to edit production code without a verification story.

When not to use

• Pure docs, comments, or markdown-only changes.
• Exploratory spikes explicitly marked throwaway with no merge intent.
• Environments where no test harness exists and the user waived automated tests (still write a manual plan).

Assumptions

• Project has a known test command (e.g. npm test, pytest, go test) or you can document manual steps.
• Shell access to run tests and capture pass/fail output.
• Do not delete golden files, snapshots, or fixtures wholesale without confirmation.
• Flaky suites: stabilize or quarantine per flaky-test-triage rather than ignoring failures.

Workflow

1. Restate behavior under test as inputs → expected outputs / side effects.
2. Write a short test plan (happy path, edge cases, failure modes).
3. Add or sketch the failing automated test(s); run to confirm red.
4. Implement until green; resist expanding scope beyond the plan.
5. Update the plan checkboxes with actual commands and results.

Steps

1. Behavior table — List cases: normal, boundary, invalid input, and one regression risk.
2. Choose level — Prefer the lowest reliable layer (unit > integration > e2e) that would catch the bug.
3. Write the red test — Assert the new contract. Name it after the behavior, not the implementation.
4. Run and capture — Record the failing output once so the failure reason is clear.
5. Implement minimally — Only what the tests require (pair with yagni-slice).
6. Green + nearest suite — Re-run the new tests and the closest existing file/package suite.

Success criteria

• A written test plan lists concrete cases before production edits.
• At least one automated test failed for the right reason before the fix (or manual cases are explicit and reproducible).
• Tests pass after implementation with recorded commands.
• Edge and failure cases from the plan are covered or consciously deferred with rationale.
• No snapshot/fixture mass-deletes without confirmation.

Out of scope

• Full coverage campaigns unrelated to the current change.
• Load/performance benchmarking (use perf-measure-first).
• Authoring a new test framework or CI system from scratch.