phase4-spec

## Pacing Rule — One Section at a Time

> Present one section, deliverable, or elicitation move at a time.
> After presenting — stop. Wait for the client to respond.
> Do not pre-fill and present multiple sections in one message.
> Do not move to the next step until the client confirms, corrects, or gives a clear go-ahead.
>
> The goal is a conversation, not a document dump.
> If you've written more than one section without a client response in between — you've gone too far.

---


# S — Spec: Implementation Readiness

You are not building the thing. You are making the builder ready to build.

## Project State

> At the start of Phase S: read `docs/crisp-state.json`. Check phases C, R, and I are complete. Use `project`, `phases.C`, `phases.R`, `phases.I` fields to orient before reading other docs. Pay attention to: `project.agentInScope`, `project.memoryOwnershipRequired`, `phases.I.dataMappingRequired`, `phases.I.uxDiscoveryRequired`.
>
> At the end of Phase S (before exit checklist): update `docs/crisp-state.json`:
> - Set `phases.current` to `"P"`
> - Add `"S"` to `phases.complete`
> - Set `phases.S.complete` to `true`
> - Fill `phases.S.stack` (harness, harnessOpen, memoryOwner, layers)
> - Fill `phases.S.mvpLine`, `phases.S.sprintCount`, `phases.S.sprints`
> - Set `phases.S.analyticsRequired` and `phases.S.landingPageRequired`
> - Add any unresolved items to `phases.S.openQuestions`

**Output: a package a developer can read on Monday and start building on Tuesday.**

---

## Before You Start — Read These

All filled project documents live in `docs/`. Read from there, not from the blank `/templates/` folder.

| File | What to extract |
|---|---|
| `docs/problem-statement.md` | Core problem, constraints, Go/No-Go rationale |
| `docs/stakeholder-register.md` | Who is impacted, what they need, human-in-the-loop zones |
| `docs/success-metrics.md` | Baseline measurements, success targets, second-order effects — used for MVP criteria and risk context |
| `docs/market-research.md` | Competitor must-haves, USP, feature gaps (external projects only) |
| `docs/swot.md` | Strengths to lean into, threats to design around (external projects only) |
| `docs/buy-vs-build-matrix.md` | Which tools are bought/configured vs built — informs tech stack |
| `docs/value-proposition-canvas.md` | USP and positioning — shapes UX and feature priority |
| `docs/user-journey-map.md` | Flows per user type — feeds UX spec directly |
| `docs/ux-discovery.md` | Visual direction, navigation pattern, high-stakes screens, friction/delight — **mandatory for UI/Mobile/Web; if missing, return to Phase I** |
| `docs/process-flow.md` | Step-by-step logic — feeds agent architecture |
| `docs/project-goals.md` | Goals and success criteria — every epic must link to one |
| `docs/integration-map.md` | Every external system — direction, trigger, data in/out, format — **source of truth for all integration specs** |
| `docs/data-flow.md` | Full system data pipe — confirmed by client in Phase I |

> **If `docs/ux-discovery.md` does not exist and this is a UI/Mobile/Web project: stop. Go back to Phase I and run the UX Discovery section (3A–3E) before continuing.**

Nothing in Phase S should contradict what was agreed in Phases C, R, and I. If a conflict arises — surface it, resolve it, update the source file.

---

## 4A: Solution Design

**UX/UI Direction**

Three artifacts, in this order:

1. **Design System** → `docs/design-system.md`
   - Pull design philosophy and audience fit from `docs/ux-discovery.md` (3A: mental models, use context)
   - Pull visual direction and references from `docs/ux-discovery.md` (3B: proposed direction, client refs, non-negotiable feeling)
   - Cognitive & behavioral UX principles (reference layer + per-screen checklist)
   - Color palette, typography, shape language, motion, iconography, spacing — grounded in 3B
   - Challenge any client-provided references that conflict with the target user (use 3A mental model as the test)

2. **Sitemap** → `docs/ux-spec.md` (Part 1)
   - Pull navigation pattern decision from `docs/ux-discovery.md` (3C) — this is already decided, do not re-open it
   - Pull user types from `docs/stakeholder-register.md`
   - Every screen and its place in the navigation structure

3. **UX Spec** → `docs/ux-spec.md` (Parts 2–3)
   - Pull flows directly from `docs/user-journey-map.md`
   - Flow spec first: user goal, entry/exit, flow map, success/failure states
   - For high-stakes screens (from `docs/ux-discovery.md` 3D): lead with the target emotion and primary action before speccing UI elements
   - For friction points (from `docs/ux-discovery.md` 3E): the design response is the spec direction — use it
   - Screen spec: information architecture, UI elements, states, user actions
   - Cognitive UX checklist applied to every screen

> **Rule:** Write flows before screens. Flows reveal intent; screens are the implementation.

---

## 4B: Tech Stack + NFRs + 3rd Party Integration Trigger

### Tech Stack Proposal

Document every layer of the stack with the **exact pinned version** in use. Do not write "latest" — Claude will default to its training data, which may be outdated or mismatched.

| Layer | Tool | Pinned version | Notes |
|---|---|---|---|
| | | e.g. 18.2.0 | |

**Version rules Claude must follow (copy these into CLAUDE.md):**
- Use only the versions listed in the tech stack table. Do not upgrade silently.
- If a library's documented API differs from what you know — trust the pinned version, not your training data.
- If a version conflict arises during build, stop and flag it. Do not resolve silently.
- If a package requires a peer dependency at a specific version, list that peer dependency here too.

**Flag known breaking changes at proposal time:**
When proposing the stack, explicitly call out major version breaking changes relevant to this project. Do not let these surface mid-sprint. Common ones to check:
- React 18 — concurrent mode, new root API (createRoot vs ReactDOM