Atdd Plan

---
name: atdd-plan
description: "Produce an ATDD-first implementation plan in Claude Code's native plan mode, with named design patterns called out where they earn their keep. The skill enters plan mode automatically (via the EnterPlanMode tool), runs /flagrare:codebase-explore to ground the plan in the actual codebase, then produces a plan-mode plan that MUST include both: (1) 3-5 acceptance tests in plain English defining 'done' before any implementation, written behavior-first against the public API only; and (2) any non-trivial structural decisions named as design patterns with a one-line rationale. Plan mode's native approve/edit/reject button UI is the close — ExitPlanMode is how the skill ends. Use whenever the user wants to plan a feature, fix, or refactor — 'how should we implement X', 'plan this', 'let's design X', 'where do we start on Y'. Tests follow Kent Dodds Testing Trophy: behavior over implementation, integration-heavy, public-API-only, refactor-proof. The skill stops at the plan; it does not write implementation code."
---

# ATDD Plan

This skill produces an implementation plan in **Claude Code's native plan mode**. It does not reinvent plan mode's output shape — Claude already knows how to write a plan-mode plan. The skill exists to enforce three things plan mode alone won't:

1. **Plan mode is actually used** — `EnterPlanMode` at skill start, `ExitPlanMode` at skill end. The user gets the native approve/edit/reject button UI, not a wall of markdown.
2. **The plan is grounded in the real codebase** — `/flagrare:codebase-explore` runs before any planning, so the plan references the actual files, conventions, and reusable pieces that exist.
3. **The plan contains the two non-negotiables below.**

Everything else about the plan's form — length, section ordering, tone — follows plan mode's defaults. Don't impose extra structure on top.

---

## The two non-negotiables

Every plan this skill produces **must include** both:

### 1. Acceptance Tests (ATDD)

3 to 5 acceptance tests, written in plain English, that define "done" before implementation begins. Each test must:

- **Exercise the public API only** — no private methods, no internal state, no `_inner` fields. A test that breaks on a behavior-preserving rename is a broken test, not a broken refactor.
- **Describe behavior, not method names** — `"returns an empty Scene when the story has ended"` not `"test_advance_flag"`.
- **Use real collaborators where cheap; mock only at external/network/clock/process/OS boundaries.**
- **Follow Kent Dodds' Testing Trophy** — integration-heavy is the default, because most regressions live between units, not inside them. Unit tests are reserved for pure functions with complex logic. E2E is for one or two critical paths, not one per scenario.

Write 3-5 ATs. Too few leaves behavior undefined; too many creates a brittle harness.

### 2. Design Patterns (named, with rationale)

For every **non-trivial structural decision**, name the pattern and give a one-line rationale that explains why it fits *this* problem — not what the pattern is in the abstract.

| Problem shape | Pattern to consider |
|---|---|
| Swap implementations without changing callers | Strategy |
| Hide a complex subsystem behind a simple interface | Facade |
| Decouple data access from business logic | Repository |
| Notify dependents without coupling to them | Observer |
| Add behavior without changing the object | Decorator |
| Create objects without specifying the class | Factory / Abstract Factory |
| One algorithm, pluggable steps | Template Method |
| Encapsulate a request as an object | Command |
| Wrap incompatible interfaces | Adapter |

Only name a pattern when it genuinely solves the stated problem. Forcing a pattern where it doesn't fit is worse than no pattern. If a plan's structural decisions are all trivial (one obvious file change, no abstraction needed), say so explicitly — *"No design patterns needed; this is a single-function fix in `path/to/file`"* — rather than inventing one.

---

## Procedure

### Step 1 — Enter plan mode

Call `EnterPlanMode` immediately. Do not preface with a summary or ask for confirmation first — the user invoked a planning skill, plan mode is the right posture, just enter it. Plan mode restricts the session to read-only tools, which is exactly what planning needs.

If `EnterPlanMode`'s schema isn't loaded, use `ToolSearch` with `select:EnterPlanMode,ExitPlanMode` to load both before proceeding.

### Step 2 — Explore the codebase

Invoke `/flagrare:codebase-explore`. Pass it the user's description (or the brief from `/flagrare:intake` if the skill was chained through `/flagrare:work-prep`).

**Hard requirement: invoke the skill, not a substitute.** Do not replace it with a generic `Explore` agent or manual grep — the skill encodes a specific methodology (prior-branch discovery, convention mapping, utility inventory, dependency tracing) and produces structured findings the plan depends on.

Wait for it to complete. Do not start writing the plan until you have its output.

### Step 3 — Confirm scope (lightweight gate)

Before writing the plan, post a 3-5 sentence synthesis of what you understood:

- One-sentence framing of the feature/fix/refactor
- The 2-3 most relevant locations exploration surfaced (with `path/to/file.ts:42`-style references)
- 1-2 explicit assumptions you're planning around

Then call `AskUserQuestion` with three options:

- **Looks right, write the plan** (Recommended)
- **I want to adjust direction first** — user describes the adjustment, you re-run Step 3
- **Different direction entirely** — user provides new framing, you may need to re-run Step 2

This gate is light by design — it's one button click when the synthesis is correct, which is the common case. Its purpose is to prevent committing to a wrong direction before producing a full plan, not to interrogate the user.

### Step 4 — Write the plan

Write a plan-mode plan. Follow Claude Code's normal plan-mode conventions for shape, length, and tone — narrative + targeted lists, scannable, no padding.

**Two requirements layered on top of plan mode's defaults:**

1. Include the **Acceptance Tests** section described above (3-5 ATs).
2. **Name the design patterns** for any non-trivial structural decisions, with one-line rationale each. Or explicitly state none are needed.

**Do NOT add**:

- A separate SOLID audit section
- A separate Clean Code checklist
- An enumerated Gap Review by category (empty/boundary/error/concurrent/state-machine/hostile/ordering)
- A Design Patterns table separate from the prose
- A Refactor Pass Reminder
- An Implementation Phases section with builds/gates/patterns columns

Those were artifacts of an older form that produced deliverable documents. Plan mode plans don't need them — they make the plan long without making it better. If something genuinely matters to the design (a real concurrency risk, a real boundary issue), call it out inline in the prose where it lives. A plan that surfaces 2-3 *specific* risks based on what exploration found is far more useful than one that enumerates every theoretical category.

### Step 5 — Exit plan mode

Call `ExitPlanMode` with the plan as the `plan` argument. This gives the user the native button-driven approve/edit/reject UI — which is what they invoked the skill to get.

Do not follow `ExitPlanMode` with a prose question or summary. The button UI is the close.

---

## Anti-patterns — refuse these

- **Acceptance tests that assert on internal state** (`_inner`, mock call counts on types you own, private fields). Refactor-proof or it's not an AT.
- **Pattern names with no rationale** — "we'll use a Strategy" with no explanation of what it replaces or why this problem needs one.
- **A SOLID / Clean Code / Gap Review / Phases section** in the plan output. Those were the old form; plan mode does not need them.
- **Skipping `EnterPlanMode`** and producing a markdown plan in the regular conversation. The user wants the native plan-mode UX; that means the actual tool, not an approximation.
- **Skipping `/flagrare:codebase-explore`.** The plan must be grounded in the real codebase; references to actual `path/to/file.ts:42` locations are what separate this from a generic chatbot plan.
- **Coverage targets as a goal.** Coverage is a side effect of testing the right behaviors, not something the plan aims at.
- **Closing with a prose question after `ExitPlanMode`.** The button UI is the close. Don't double-prompt.