# Phase prompt template (the skeleton every phase file follows)

> This is the shape of every `backend-phase-N.md` and `frontend-phase-N-bM.md`. It exists so the
> chain is uniform and an agent always knows where to find each thing. When you (a planning author)
> create or edit a phase file, fill every section. When you (an executing agent) run a phase, expect
> every section to be present.

---

```
# <Backend|Frontend> Phase N — <Title>

> One-paragraph mission: what this phase delivers and why it matters to the product.
> **Track:** backend|frontend · **Depends on:** <prior phases / backend phase bM> · **Unlocks:** <what comes next>
> **Before you start, read [_shared/agent-operating-rules.md](../_shared/agent-operating-rules.md).** It is not optional.

## 1. Context — where this sits
- Where we are in the chain; the 2–3 sentence product framing.
- **What already exists (do not rebuild):** bullet list linking the prior phases + the baseline
  facts (from `dev/shared-working-context/...` and the project state).

## 2. Required reading (do this first)
- Exact product docs to read (with paths) and *why* each matters.
- Exact code areas to read (existing patterns to mirror).
- Contracts to consume (frontend) / prior handoff notes.

## 3. Scope — build this
- The precise, enumerated deliverables: entities/migrations, commands/queries, endpoints
  (backend); screens/flows, services/hooks, components (frontend). Each with enough detail to build
  without guessing. Tag anything (DEFERRED) that is explicitly out of scope.

## 4. Mocks & seams in this phase
- Which external services are mocked, the interface each sits behind, what the mock returns, and the
  pointer to record it in the mock registry. (Reuse seams introduced earlier; only *introduce* the
  ones this phase owns.)

## 5. Critical rules you must not get wrong
- The domain-specific invariants (money correctness, idempotency, tenancy, two-stage clinical
  disclosure, same-gender matching, RSC boundary, re-render/caching, etc.) relevant to this phase.

## 6. Definition of Done
- The phase-specific acceptance criteria, on top of the shared
  [definition-of-done.md](../_shared/definition-of-done.md).

## 7. How to test (what a human can verify after this phase)
- Concrete, runnable steps (endpoints to curl / Swagger calls / screens to click) and the expected
  result for each. This becomes the "what can be tested" section of your report.

## 8. Hand off & document (close the phase)
- Docs to update (which CLAUDE.md / product doc).
- Contract(s) to write (backend) / consume (frontend).
- The handoff note + report files to write, and the memory to save. (Mechanics in operating-rules §5–8.)
```

---

## Authoring notes

- Keep each phase **self-contained**: an agent should be able to execute it having read only the phase
  file + the files it links. Link generously to prior phases and to `product/` — don't restate them.
- Phases are **vertical slices** where possible (entity → handler → endpoint → contract for backend;
  service → hook → screen for frontend) so each ends in something testable.
- Never let a phase silently expand scope. If something belongs to a later phase, say so and link it.