# Test Plan First

> Use when starting implementation of a feature or bugfix. Write a concrete test plan and at least one failing automated test (or explicit manual cases) before changing production behavior.

- Skill: `magia187/test-plan-first` (Agent Skill)
- Install (CLI): `npx skillmds@latest add magia187/test-plan-first`
- Raw SKILL.md: https://api.skillmd.com/api/skills/magia187/test-plan-first/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: magia187 (https://skillmd.com/u/magia187)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/magia187/test-plan-first

---


# 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.