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
2. Pull design philosophy and audience fit from docs/ux-discovery.md (3A: mental models, use context)
3. Pull visual direction and references from docs/ux-discovery.md (3B: proposed direction, client refs, non-negotiable feeling)
4. Cognitive & behavioral UX principles (reference layer + per-screen checklist)
5. Color palette, typography, shape language, motion, iconography, spacing — grounded in 3B
6. Challenge any client-provided references that conflict with the target user (use 3A mental model as the test)

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

1. UX Spec → docs/ux-spec.md (Parts 2–3)
2. Pull flows directly from docs/user-journey-map.md
3. Flow spec first: user goal, entry/exit, flow map, success/failure states
4. For high-stakes screens (from docs/ux-discovery.md 3D): lead with the target emotion and primary action before speccing UI elements
5. For friction points (from docs/ux-discovery.md 3E): the design response is the spec direction — use it
6. Screen spec: information architecture, UI elements, states, user actions
7. 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.render)
• Next.js 13+ — App Router vs Pages Router are fundamentally different conventions
• Expo SDK upgrades — frequently break native modules; check release notes before pinning
• Supabase JS v1 → v2 — auth API changed significantly (createClient, session handling)
• Node 16 → 18 → 20 — native fetch, ESM defaults, breaking crypto changes

Present the stack with versions and flag breaking changes before confirming:

"Here's the proposed stack with pinned versions: [table]. Worth flagging: [relevant breaking changes for this project]. Does anything conflict with existing code or infrastructure you already have?"

Confirm versions with the client before writing a single line of code. Save the pinned version table to CLAUDE.md immediately — it is the version source of truth for every sprint.

• Justify every choice against constraints in docs/problem-statement.md (budget, time, legal, tech)
• Cross-check docs/buy-vs-build-matrix.md — already-decided tools go here, not up for debate again
• Prefer existing libraries and open source when time or budget is constrained

Open Source Library Research — mandatory for every dependency

Claude's training data has a cutoff. A library that was "actively maintained" in training may have had zero commits in 18 months. One search prevents months of dependency debt.

For every open source library in the tech stack, run this evaluation before confirming the choice:

Step 1: Search Search GitHub: [what you need] github library (e.g. "pdf export github library", "react data table github") Evaluate the top 3–5 results.

Step 2: Score each candidate

| Criteria | What to check | |---|---| | ⭐ Stars | Community signal — >500 for a production dependency | | 🍴 Forks | Active derivative use — meaningful number relative to stars | | 📅 Last commit | Must be within 6 months for active maintenance | | 🐛 Issues | Open/closed ratio — high open, low closed = warning sign | | 📖 Documentation | Is it actually usable from do