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.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 docs alone?
⚖️ License	MIT/Apache-2.0/BSD = free for commercial. GPL = check carefully.
👥 Contributors	Solo maintainer = higher bus factor risk

Step 3: Record decision

Add to the tech stack table:

• Chosen library with pinned version
• Why it was chosen over the alternatives (1 sentence)
• Alternatives considered and why they were rejected

Present to client if the choice is non-obvious: "I evaluated [A], [B], and [C] for [use case]. I'm recommending [A] — [stars], last commit [date], [license]. [B] was last updated [date] so I ruled it out. Agree?"

API Key & Secrets Rules — non-negotiable, copy into CLAUDE.md:

• Never expose API keys, tokens, or secrets on the client side. No exceptions. Not in React components, not in frontend env vars prefixed with NEXT_PUBLIC_, not in mobile app bundles.
• All calls to 3rd party APIs that require credentials must be made server-side (API route, Edge function, backend service).
• The client-side calls your server. Your server calls the 3rd party. The secret never leaves the server.
• Wrong: fetch('https://api.stripe.com/...', { headers: { Authorization: process.env.NEXT_PUBLIC_STRIPE_KEY } }) in a React component.
• Right: fetch('/api/stripe/charge', { body: JSON.stringify(payload) }) → server-side API route handles the Stripe call with process.env.STRIPE_SECRET_KEY.
• Every secret goes into .env.local (or equivalent) — verified in .gitignore before first commit.

---

Non-Functional Requirements — Elicit and Document

NFRs are project-wide constraints. Capture them once here, before sprint planning begins. They go into CLAUDE.md and are referenced by every sprint that touches the relevant layer. Do not leave these as assumptions — a wrong default causes rework in production.

The Djokovic principle: Novak Djokovic wins by being the best-conditioned player on the court, not the flashiest. Pinned versions, NFRs, and security defaults are conditioning. Nobody cheers for them. The client never asks about them. They're exactly why you don't collapse in week 8 when production goes down and you're staring at an unencrypted database and an API key committed to a public repo.

Pre-fill what you can from docs/problem-statement.md (constraints) and docs/stakeholder-register.md (compliance, data sensitivity). Then elicit the rest with these questions:

Availability & Performance

"What's the acceptable downtime for this product? Business-critical (99.9%+ uptime) or is occasional downtime tolerable for MVP?" "Any known peak usage moments — an event, a campaign, end of month? How many concurrent users at max load?"

Security

"Does any data in this system need to be encrypted at rest? In transit? I'll assume yes for both unless there's a reason not to — confirm?" "Who can access what? Are there roles with different data visibility, or flat access for all authenticated users?"

Deployment & Infrastructure

"Should this be containerised with Docker? It makes deployment and environment parity much cleaner — any reason not to?" "Self-hosted or cloud? If cloud — any provider preference, or should I recommend based on the stack and budget?" "Any data residency requirement — does data need to stay in a specific country or region?" (Cross-check with legal constraints in docs/problem-statement.md)

Reliability & Recovery

"If this goes down, what's the acceptable recovery time — hours, minutes? Do we need automated backups, and how often?" "Any monitoring and alerting expectations — proactive notification when something fails, or is reactive support fine for MVP?"

Save NFRs as an appended section in docs/problem-statement.md and reference them in CLAUDE.md.

---

3rd Party Integration Confirmation — mandatory step

Phase I already produced docs/integration-map.md — every external system was identified and mapped there. This step confirms that list against the tech stack and writes the integration AI Specs. Do not discover integrations here. If something appears in the tech stack that isn't in the integration map — stop, go back, and update docs/integration-map.md first.

Step 1: Cross-check tech stack against integration map

Read docs/integration-map.md. For every external system listed there, verify it appears in the tech stack. For every external service in the tech stack, verify it appears in the integration map.

Any mismatch → resolve before continuing:

"I see [service] in the tech stack but it's not in the integration map from Phase I. Before I write the spec — what data does it provide or receive, what triggers it, and in what format? Let's add it to the integration map now."

Step 2: Check for unresolved open questions

Open docs/integration-map.md and read the Open Questions section. Any unresolved questions must be answered before the integration AI Spec for that service is written. Do not write a spec against an unknown payload or trigger.

Step 3: Write integration AI Specs

For each confirmed integration:

1. Flag it in the tech stack table with tag [INTEGRATION REQUIRED]
2. Create a dedicated AI Spec → docs/ai-spec-[service-name].md
3. Pre-fill auth, endpoints, payload shapes, and DB mapping from docs/integration-map.md — this is already elicited, do not re-ask
4. Run the Web Research Protocol from templates/ai-spec.md — browse official dev docs to fill in anything not captured in Phase I (rate limits, error codes, pagination, SDK quirks)
5. Only ask the client for what neither the integration map nor the docs provide (credentials, account-specific config, sandbox access)

Step 4: Sequence integration sprints

Read the "Sprint dependency" column in docs/integration-map.md. Integration specs must be complete before any sprint that calls that API. Flag any sprint ordering conflicts now — do not let them surface during build.

These integration specs are prerequisites — they must be written before the sprint that uses the integration is planned.

---

4C: Project Foundation

---

Initial Backlog — Pre-fill, Name-check, Confirm → docs/initial-backlog.md

Pre-fill from existing docs:

Backlog section	Source
User types for stories	docs/stakeholder-register.md — system users only (not oversight stakeholders)
Epics	docs/user-journey-map.md — each major journey stage is an epic candidate; docs/project-goals.md — each goal must map to at least one epic
Feature scope	docs/problem-statement.md — what's in and out of scope; docs/buy-vs-build-matrix.md — what's being built vs bought
Out of scope / non-goals	docs/project-goals.md — non-goals; docs/problem-statement.md — explicit exclusions
3rd party integrations	docs/buy-vs-build-matrix.md and tech stack decision from 4B

External product rule: If project.type === "external" in docs/crisp-state.json — add a Landing Page epic to the backlog and tag it MVP. The landing page build is part of the launch, not a post-launch afterthought. The brief lives in docs/landing-page-brief.md (written in the Landing Page section below). Assign it to a sprint — typically Sprint 1 or a dedicated pre-launch sprint.

Draft full epics and user stories in "As a [user], I want to [action], so that [outcome]" format. Leave MVP tag column blank — filled in 4D.

Present with a naming check first:

"Here are the epics I've drafted: [list]. Before we check completeness — does the naming match how your team actually talks about these? 'Report Lost Item' might be 'Create a Case' in your world. Let's get the language right before we go deeper."

Then completeness:

"Anything missing, or anything here that doesn't belong?"

One round. Do not reopen scope discussions settled in Phase C.

---

Assumptions Log — Pre-fill and Confirm → docs/assumptions-log.md

An assumption is anything treated as true in prior phases without explicit confirmation. Surface them now — wrong assumptions are the #1 cause of project failure.

Pre-fill by scanning all prior docs for implicit decisions:

Where to look	What to surface
docs/problem-statement.md	Constraints assumed (budget range, timeline, legal framework)
docs/buy-vs-build-matrix.md	Tools assumed available, costs assumed affordable
docs/stakeholder-register.md	User behaviour and adoption assumed
docs/market-research.md	Market size, competitor behaviour, user willingness to switch
docs/process-flow.md	Data availability, system access, API reliability assumed
docs/ux-discovery.md	User mental models and device usage assumed
Tech stack + NFRs (4B)	Third-party reliability, library support, hosting costs, uptime assumed

Rate each assumption: High (wrong = project fails or pivots) / Medium (wrong = rework) / Low (wrong = minor adjustment).

Present for confirmation — the client didn't create these assumptions, you did:

"Here are the assumptions baked into everything so far. The high-risk ones are [X and Y]. Do any of these look wrong to you?"

Flag invalidated assumptions immediately and resolve before proceeding.

---

Risk Assessment — Pre-fill, Elicit hidden risks, Confirm → docs/risk-assessment.md

Pre-fill from existing docs:

Risk category	Source
Business risks	docs/swot.md — threats (external); docs/problem-statement.md — constraints
Technical risks	docs/buy-vs-build-matrix.md — build complexity; docs/assumptions-log.md — high-risk technical assumptions; tech stack from 4B
Legal / compliance	docs/problem-statement.md — legal constraints; docs/stakeholder-register.md — GDPR/HIPAA/data residency
Security	Data types from docs/stakeholder-register.md and docs/process-flow.md; NFRs from 4B; auth approach from tech stack
People / adoption	docs/stakeholder-register.md — stakeholders with neutral or negative impact
Human-in-the-loop zones	docs/stakeholder-register.md — HITL flags from Phase R; docs/process-flow.md — decision points

Draft all risks with likelihood, impact, mitigation, and owner. Pre-fill HITL zones from Phase R — don't reinvent them.

Then elicit what docs can never capture — context the client carries in their head:

"Here's the risk register. I've covered the standard bases. But what keeps you up at night about this project that I haven't listed? A vendor relationship, a team dynamic, a deadline tied to something external — anything that would make this harder than it looks on paper?"

Add what they surface. One round. Lock it.

---

4D: MVP Prioritization — HVLE Conversation

Stop. Do not write sprint plans yet. This step requires a live conversation with the client. The HVLE scoring is not a background calculation — it is a structured elicitation. Run it now. Full scoring logic lives in mvp-prioritization.md — read it before starting.

---

Step 1: Lock MVP-BASELINE (no scoring needed)

Before any HVLE scoring, identify the non-negotiables. These bypass the scoring model entirely.

Pull from docs/market-research.md:

• Must-haves — features every competitor has; users expect them as table stakes
• USP features — the thing that makes this product worth choosing over alternatives

Present them to the client:

"Before we score anything, let me lock the floor. These features go in MVP regardless of score — every competitor has them, and our USP lives here. Does this list look right, or is anything missing?"

Get confirmation. Mark these MVP-BASELINE in docs/initial-backlog.md. Do not re-debate them.

---

Step 2: Elicit Business Value Criteria

Pre-fill 3–4 criteria based on project context (pull from docs/project-goals.md, docs/success-metrics.md, and docs/stakeholder-register.md), then present them for correction — don't ask open-ended questions.

For external products, default criteria are:

• Customer acquisition
• User activation / adoption
• Retention / engagement
• Revenue generation
• Referral / virality

For internal tools, default criteria are:

• Cross-company process adoption
• Time saved per user per week
• Error / rework reduction
• Employee satisfaction
• Compliance / risk reduction

Say this:

"I've assumed the outcomes that matter most here are [X, Y, Z]. Does that feel right, or am I optimizing for the wrong thing? We need max 5 — if you want to add one, we cut one."

Hard limit: 5 criteria. If they want more, help them consolidate. More than 5 and everything starts scoring the same.

---

Step 3: Weight the Criteria

Once criteria are agreed, get weights. Do not skip this — unweighted scoring treats every criterion as equal, which is almost never true.

"Now give each one a weight from 1 to 3. Think of it as: 3 = if we nail this, everything else follows. 1 = nice to track, but it's not what this lives or dies on."

Present the weighted criteria back for confirmation before scoring.

---

Step 4: Score the Backlog Together

Take every feature from docs/initial-backlog.md (excluding MVP-BASELINE items) and score them against each criterion (1–5). For each feature:

• 5 = directly and strongly drives this outcome
• 3 = contributes, but not the whole story
• 1 = barely connected — we're reaching

Walk the client through scores for any non-obvious features. Don't silently assign scores — show your reasoning and invite correction.

Priority Score = Business Value Score ÷ Effort Value

Effort sizing (T-shirt):

Size	Days	Effort Value
XS	< 1 day	0.5
S	1–2 days	1.5
M	3–5 days	4
L	7–10 days	8.5
XL	10+ days	12

---

Step 5: Apply Dependency Overrides

After scoring, check for features that scored low but are required by high-scoring ones.

"Feature [X] scored lower on its own, but [Y] sits on top of it — so [X] moves into MVP as a dependency. We don't get a choice here."

Mark blockers as DEPENDENCY. Adjust the MVP line to include all required foundations.

---

Step 6: Draw the MVP Line with the Client

Sort features by Priority Score (descending): MVP-BASELINE first, then scored features high→low, dependencies resolved.

Present the ranked list and propose where to draw the line:

"Here's the ranked list. I'd draw the line here — everything above ships in MVP. Before you agree, ask yourself three things: Can someone actually use this and get value from it with only these features? Does it deliver our USP? Can we build it in the time we have?"

All three must be yes. If not — something's missing or the scope is too big. Adjust together.

---

Step 7: Tag and Save

Tag every feature:

• MVP-BASELINE — table stakes or USP, non-negotiable
• MVP — scored, above the line
• POST-MVP — scored, below the line (not never — just not now)
• DEPENDENCY — required by an MVP feature, regardless of own score

Save scoring output → docs/mvp-prioritization.md Update tags in → docs/initial-backlog.md

Only after this is complete: proceed to 4E and sprint planning.

---

4E: AI Architecture (Claude Code Projects)

This is the layer between "we know what to build" and "Claude Code starts building." Most AI implementations fall apart here. Don't skip it.

---

CLAUDE.md

Compile from ALL docs/ files → CLAUDE.md in project root.

• Problem statement, constraints, goals, success metrics, tech stack, NFRs, agent map, env vars master list
• Include the CRISP Output Manifest (see Phase 4 Outputs below) so Claude always knows what docs exist
• This is what Claude reads at the start of every session — make it complete and current