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

**REQUIRED BACKGROUND:** Invoke `/flagrare:testing-philosophy` before writing the Acceptance Tests. It defines, layer-agnostically, what a good test is, behavior over implementation, the Testing Trophy, and the e2e necessity floor below. The AT rules here are its application to planning; read both.

---

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. (Apply the acid test from `/flagrare:testing-philosophy`: would this break under a behavior-preserving refactor? Does it assert what a real user observes?)
• **Describe behavior, not method names**: `"returns an empty Scene when the story has ended"` not `"test_advance_flag"`. A name that describes a mechanism (`"calls advanceFlag"`) is the tell of an implementation-detail test.
• **Use real collaborators where cheap; mock only at external/network/clock/process/OS boundaries.** Never assert on spy/mock call-counts for a collaborator you own, that asserts the mechanism, not the behavior.
• **Follow the 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.
• **Include the e2e floor for user-facing work**: if the feature is user-facing, at least one AT must exercise the critical happy path end-to-end through the real, assembled system (browser journey for a UI; running-service-over-HTTP-against-a-real-DB for a backend; subprocess for a CLI; public-API-as-a-consumer for a library). "Mostly integration" is not "skip e2e": one or two critical paths, not one per scenario, but never zero for a user-facing feature.

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