Plan

Plan — the technical blueprint between spec and tasks

The spec says what and why. plan decides how: the components, the contracts between them, the data that flows, how each claim gets proven, and what is most likely to bite. It reads the clarified spec and the constitution, writes ONE artifact — 02-DOCS/wiki/sdd/plans/<slug>.md — and hands off to tasks, which slices it into an ordered, independently-verifiable checklist.

constitution → specify → clarify → [ plan ] → tasks → analyze → implement → verify → review → ship

Decide structure, not syntax

A plan names components, contracts, shapes and flows. It does not write the framework's route decorators, the ORM's session boilerplate or the test runner's flags — those are stack mechanics, owned by the stack skill (../fastapi/SKILL.md, ../nextjs/SKILL.md, ../go/SKILL.md, ../flutter/SKILL.md, ../postgresdb/SKILL.md) at implement time. This altitude is what makes a plan reviewable against intent and slice-able by tasks; drop it and you get code no one approved.

reservation.reserve(cartId: CartId) -> Reservation | OutOfStock | CartNotFound
  - idempotent on cartId (calling twice returns the same Reservation)
  - holds stock for 15 min, then auto-releases
  - never partially reserves: all lines or none

That is the altitude. The stack skill later decides whether it becomes a POST handler with a Pydantic model or a Go method on a struct — it can, because the contract is unambiguous.

Entry gate

1. The spec — 02-DOCS/wiki/sdd/specs/<slug>.md. Missing → STOP, route to ../specify/SKILL.md. Still carrying [NEEDS CLARIFICATION] markers or open questions → STOP, route to ../clarify/SKILL.md. A plan built on an unclarified spec is a guess wearing a diagram, and every phase downstream inherits the guess.
2. The constitution — 02-DOCS/wiki/sdd/constitution.md holds the project's non-negotiables (stack canon, quality bars, conventions). Every architectural choice must be consistent with it; where the design needs to bend a principle, say so with a reason instead of bending it silently.
3. The Knowledge map — 02-DOCS/wiki/index.md points at 02-DOCS/wiki/stack/* and prior plans/decisions. Reusing what the project already settled is the difference between a plan and scope drift.
4. The profile — technical_level in 02-DOCS/wiki/harness/user-profile.md (see below).

What a plan contains

The sections of the artifact, in order; fill them top-down, later ones lean on earlier ones. The fill-in skeleton with per-section guidance is references/plan-template.md — use it verbatim.

Three of them carry the weight and fail quietly:

• §2 Architecture — a box-and-arrow diagram, one sentence of single responsibility per component, internal vs. external marked (the arrows are the seams you will test and parallelize). State the one decision that matters most — sync vs. async, split service vs. monolith, read model vs. single table — and defend it against a constraint from §1. If two designs are genuinely viable, give both, the trade-off, and your recommendation; leaving the reader to choose is not a plan.
• §5 Testing strategy — per acceptance criterion: the level that proves it (unit / contract / integration / e2e), what it asserts, what it fakes to stay fast. Deciding this before code exists is what makes implement's TDD possible. You choose the seams; the stack skill owns the tooling.
• §7 Risks — ranked, each with trigger, impact, and the mitigation or spike that retires it. A plan claiming zero risk is the riskiest one. Significant decisions taken while planning also get appended to 02-DOCS/wiki/sdd/decisions.md, so later phases can trace the why.

The artifact

Write 02-DOCS/wiki/sdd/plans/<slug>.md, <slug> matching the spec's slug exactly — one plan per spec, same name, because that is how tasks, analyze and implement find it. Then index it in 02-DOCS/wiki/index.md (the Knowledge map; root CLAUDE.md keeps only a pointer). If a plan for this slug already exists, update it in place and note what changed — never fork a -v2.

Model tier — heavy (opt-in routing)

Architecture, interfaces, data flow and risk are the heaviest reasoning in the chain, so this phase's default tier is heavy. Routing is off unless models.enabled: true in 02-DOCS/wiki/sdd/config.yaml; the resolution order, the announce rule and the model table live in ../sdd/references/model-routing.md. Routing off or no profile → session model, silently.