| name | phase4-spec |
| description | The Mileva Method (CRISP) — Phase 4: Spec. Full implementation readiness package including solution design, UX direction, tech stack, backlog, MVP prioritization, risk assessment, and AI architecture for Claude Code projects — CLAUDE.md, skill mapping, AI specs, sprint planning, quality gates. Triggers on "spec", "phase 4", "build ready", "implementation plan", "CLAUDE.md", "sprint planning", "backlog", "AI spec", or after Phase I exit checklist is complete. |
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:
-
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)
-
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
-
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:
- Flag it in the tech stack table with tag
[INTEGRATION REQUIRED]
- Create a dedicated AI Spec →
docs/ai-spec-[service-name].md
- Pre-fill auth, endpoints, payload shapes, and DB mapping from
docs/integration-map.md — this is already elicited, do not re-ask
- 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)
- 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-negotiableMVP — scored, above the linePOST-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
Gostoprimstvo. Serbian hospitality — you don't send a guest away hungry or confused. CLAUDE.md is the welcome you give to every new Claude Code session. A half-empty CLAUDE.md is like handing someone the keys to a house and not telling them where the light switches are. Every missing field is a guess Claude will make for you — and you won't like all the answers.
Skill / Agent Architecture
- Pull process steps from
docs/process-flow.md — each major step is a candidate agent
- For each agent: define responsibilities, inputs, outputs, and boundaries
- Map handoffs between agents
- Write one
SKILL.md per agent into the project's skills/ folder using templates/agent-skill.md
AI Spec — Pre-fill, Generate Open Questions, Confirm (one per sprint / feature)
Do not hand a sprint to Claude Code with a blank spec or unresolved questions.
Pre-fill everything derivable, generate sprint-specific open questions, resolve them with the client, then lock.
Save each spec to docs/ai-spec-[sprint-or-feature-name].md
Step 1: Pre-fill from existing docs
| Spec section | Source |
|---|
| Context (why this feature exists) | docs/project-goals.md — which goal it serves; docs/problem-statement.md — the problem it solves |
| Scope — In | User stories tagged to this sprint in docs/initial-backlog.md |
| Scope — Out | docs/project-goals.md — non-goals; docs/initial-backlog.md — POST-MVP items |
| Inputs | docs/user-journey-map.md — what the user brings; docs/process-flow.md — what data flows in |
| Outputs | docs/user-journey-map.md — what the user gets; docs/process-flow.md — what moves downstream |
| Business logic / rules | docs/process-flow.md — decision points; docs/stakeholder-register.md — HITL zones |
| Edge cases | docs/assumptions-log.md — high-risk assumptions; docs/risk-assessment.md — relevant risks |
| NFR references | docs/problem-statement.md NFR section — which NFRs apply to this sprint |
| 3rd Party Integrations | docs/buy-vs-build-matrix.md and 4B tech stack — only for sprints that call those APIs |
| Environment variables | 4B tech stack; prior integration AI specs |
| Test requirements | docs/process-flow.md — success condition per process step in sprint scope; acceptance criteria from user stories |
Step 2: Generate sprint-specific open questions
After pre-filling, read the sprint's user stories and process-flow steps and ask: "What would a developer need to know that isn't written down yet?"
Use these category prompts to generate questions — only include categories relevant to what this sprint builds:
| Sprint touches… | Questions to generate |
|---|
| Auth / Identity | Session expiry? What happens on expiry — logout or silent refresh? MFA required? Social login providers? Password reset — link or code? |
| File / Media handling | Max file size? Allowed types? Storage location — cloud bucket, local, CDN? Original preserved or processed version only? Who can access uploaded files? |
| Background jobs / Async | What triggers the job — event, schedule, or manual? Retry on failure? Max retries? Dead letter queue? Does the user need feedback on completion? |
| Real-time / Live updates | WebSockets or polling? Fallback if connection drops? Are updates persistent (stored) or ephemeral (lost on refresh)? |
| Notifications (push / email / SMS) | Which events trigger a notification? User-configurable or always-on? Opt-out mechanism required? |
| Payments / Financial | Which payment provider? Sandbox credentials available? Refund logic — automatic or manual? Currency and locale handling? |
| Search / Filtering | Full-text or filtered? Server-side or client-side? Indexed or real-time? Results ranking logic? |
| Roles / Permissions | Which roles exist in this sprint? What can each role see/do/not do? Who can promote or revoke roles? |
Save generated questions as an Open Questions section at the bottom of the AI Spec.
All open questions must be answered before the spec is locked and the sprint begins.
A spec with unresolved questions is not a spec — it's a wishlist.
Step 3: Resolve and confirm
Present the pre-filled spec and open questions together:
"Here's the spec for Sprint [N] — [goal]. I've pre-filled everything from our docs. At the bottom are [N] open questions specific to what this sprint builds — we need to answer these before Claude Code starts. Want to go through them now?"
Work through the questions. Fill answers into the spec. One round. Lock it. No changes mid-sprint.
Sprint Planning → docs/sprint-plan.md
- MVP-tagged features feed Sprint 1+. Post-MVP feeds later sprints.
- Use dependency map from
docs/mvp-prioritization.md to sequence sprints correctly
- Each sprint = a clear, bounded, testable unit of work
- Integration AI specs must be complete before any sprint that calls that API
Quality & Safety Gates (per sprint)
- Deployment checklist: dependencies resolved, env vars clean, no secrets in code
- Security review before each deploy — cross-check NFRs from 4B
- PR review standards defined
- Guardrail validation: hallucination risks, output validation, fallback logic
Unit Tests — mandatory on every sprint:
Tests are not optional and not an afterthought. They are part of the sprint scope. Estimate test writing time alongside feature development — not separately.
Rules for Claude Code (copy these into CLAUDE.md via templates/CLAUDE.md):
- Write unit tests for every function and feature in scope before marking sprint done
- Run the full test suite before every commit — if a test fails, fix it before committing; do not skip
- After every run, append an entry to
docs/test-log.md: sprint, date, each test in plain English, ✅/❌, and for any failure — what was wrong and how it was fixed
- Test descriptions must be plain English: "Slack notification sends when HeyReach campaign receives a reply" — not "test_fn_returns_200"
Pre-filling test requirements in the AI Spec:
For each sprint's AI Spec, pre-fill the Test Requirements section from:
docs/process-flow.md — every process step in scope has a success condition; each becomes a required test- Acceptance criteria from the sprint's user stories in
docs/initial-backlog.md
- Edge cases from
docs/assumptions-log.md and docs/risk-assessment.md
For non-technical clients: the test log is their window into whether the system is actually working. Write it so they can read it. "✅ Slack notification sent when HeyReach reply received — 2026-04-22 — Sprint 1" is useful. "PASS 47/47" is not.
Security Scanning — Bearer (mandatory on every PR):
Add Bearer to the CI pipeline. It scans for security vulnerabilities, secret leaks, and OWASP-class issues on every pull request.
Rules:
- Critical or High severity finding → block the PR. Do not merge. Notify the developer immediately with the finding and remediation path.
- Medium severity → flag in PR comments, require acknowledgement before merge.
- Low / Informational → log, do not block.
Setup (add to CI — GitHub Actions example):
- name: Bearer Security Scan
uses: bearer/bearer-action@v2
with:
severity: critical,high
fail-on-severity: critical,high
If Bearer is not yet configured in the project, flag it as a setup task for Sprint 1 before any code ships.
If Bearer is not yet configured in the project, flag it as a setup task for Sprint 1 before any code ships.
Logging Spec — mandatory for every project
Logging is what tells you what happened when production breaks at 2am. Define it before the build, not after.
Write docs/logging-spec.md using /templates/logging-spec.md. This is a mandatory Phase S output — not optional.
Key decisions to make:
- Log levels per environment (production = INFO minimum, DEBUG off by default)
- What always gets logged: every API request, auth event, background job, unhandled exception, 3rd party call, critical DB write
- What never gets logged: passwords, API keys, secrets, PII (unless masked and compliance-required)
- Log format: structured JSON with
requestId, level, event, timestamp
- Log destination: console (dev), file + aggregation service (production)
Reference docs/logging-spec.md in CLAUDE.md and in every sprint's AI Spec quality gates.
Phase 4 Outputs
All files go to docs/ in the project root. Save as you go — do not batch at the end.
The CLAUDE.md output manifest lists all expected files so nothing gets silently dropped.
| File | Contents | Required? |
|---|
docs/design-system.md | Design philosophy, visual direction, color, type, motion, references | External UI/Mobile/Web only |
docs/ux-spec.md | Sitemap + flow specs + screen specs with cognitive UX | External UI/Mobile/Web only |
docs/initial-backlog.md | Full feature list with user stories, epic-to-goal links, MVP tags | Always |
docs/assumptions-log.md | Logged assumptions and resolution status | Always |
docs/risk-assessment.md | Risks, mitigations, security posture, legal/compliance, HITL zones | Always |
docs/mvp-prioritization.md | HVLE scoring table, weighted criteria, priority scores, MVP line | Always |
docs/logging-spec.md | Log levels, what to log, PII rules, format, destination, alerting | Always |
docs/analytics-spec.md | GA4 setup, event map, conversion goals, PII rules, sprint gates | External products with UI only |
docs/landing-page-brief.md | Hero copy, sections, CTAs, visual direction — compiled from all prior docs | External products only |
docs/agent-security.md | Agent identity/permissions, data handling, failure modes | When agent is in scope |
docs/decisions.md | Updated with Phase S decisions | Always |
docs/ai-spec-[name].md | One per sprint — pre-filled, open questions resolved, locked | Always (one per sprint) |
docs/ai-spec-[service].md | Integration spec per 3rd party service | Per integration |
docs/sprint-plan.md | Sprint sequence, goals, features per sprint, quality gates | Always |
CLAUDE.md | Compiled project context incl. NFRs — lives in project root, not docs/ | Always |
docs/test-log.md | Running test record — appended after every run, plain English, all sprints | Always |
Analytics Spec — External UI/Mobile/Web products
Every success metric from Phase R needs a GA4 event that fires when it happens.
If you're building a UI product and you don't define analytics before the build, you'll ship blind.
Write docs/analytics-spec.md using /templates/analytics-spec.md.
Key steps:
- Pull every success target from
docs/success-metrics.md — map each to a GA4 conversion event
- Map all core user actions from
docs/user-journey-map.md to events
- Define parameters per event — what context is captured alongside the event name
- Apply PII rules — no names, emails, or personal data in event parameters ever
- Assign each event to the sprint that builds the relevant feature
Reference docs/analytics-spec.md in every sprint's AI Spec so Claude implements tracking for that sprint's features by default.
Landing Page Brief — External products only
By Phase S, you already have everything needed for a landing page: value prop, USP, target audience, visual direction, feature breakdown. Compiling it takes 20 minutes. Not compiling it means the client builds it from scratch with none of this context.
Write docs/landing-page-brief.md using /templates/landing-page-brief.md.
Pre-fill from:
docs/value-proposition-canvas.md → hero headline, value prop, pain pointsdocs/market-research.md → USP, target audience descriptiondocs/ux-discovery.md → visual direction, tone, non-negotiable feelingdocs/stakeholder-register.md → who the page speaks todocs/initial-backlog.md → feature highlights (benefits framing, not feature list)
Present to client for one round of copy corrections before handing off.
MVP scope: For external products, the landing page build is MVP — not a nice-to-have. It must already appear in docs/initial-backlog.md with an MVP tag (added during 4C) and have a sprint assigned in docs/sprint-plan.md.
Agent Security Spec — when agent is in scope
Trigger: If docs/problem-statement.md indicates an AI agent is in scope, this is a mandatory Phase S output.
Do not start the sprint that builds the agent without a locked docs/agent-security.md.
Aligned with AIUC-1 enterprise AI agent security standard.
This is the spec-layer translation of what was elicited in Phase R agent permission scoping.
Write docs/agent-security.md using /templates/agent-security.md.
Pre-fill from Phase R:
- Identity & Permissions — from
docs/stakeholder-register.md agent HITL/permissions section
- Hard boundaries — from Phase R "what the agent must never do" elicitation
- Approval gates — from Phase R gate conditions
- Data handling — from
docs/problem-statement.md (PII/compliance constraints) + Phase R data sensitivity elicitation
- Failure modes — from Phase R failure behaviour elicitation
Then generate open questions for anything not covered in Phase R:
- Is the auth credential scoped to least privilege?
- Is there an audit trail for every agent action?
- Is the human fallback process documented and findable?
- Are all agent actions reversible, or are some irreversible — if irreversible, is there a gate?
Resolve all open questions before the sprint that builds the agent starts.
Add to CLAUDE.md:
- Agent security rules block (see CLAUDE.md template)
- Reference
docs/agent-security.md in the output manifest
Decision Logging — Phase S
Update docs/decisions.md with decisions made in Phase S before closing.
Log these decisions in Phase S:
- Tech stack choices — every layer, why that tool, what was rejected and why
- Open source library choices — chosen library, alternatives evaluated, rationale
- MVP line — where it was drawn, what was pushed to post-MVP and why
- NFR decisions — uptime target, deployment approach, any tradeoffs
- Harness choice — open or closed, memory ownership decision if agent in scope
When all exit checklist items are checked and all AI Specs are locked, deliver this message:
Your spec is complete. CRISP Phase S is done.
Here's what's ready:
- Sprint plan →
docs/sprint-plan.md
- AI Spec for Sprint 1 →
docs/ai-spec-[sprint-name].md
- CLAUDE.md compiled → project root
To start building right now, just say:
"Start Sprint 1"
Claude Code will read the AI Spec and begin. No new setup, no mode switching, no additional steps. The spec is the handoff.
If you want to review what's in scope for Sprint 1 first, check docs/ai-spec-[sprint-name].md. Everything the build needs is already in there.
Exit Checklist
Solution Design
Tech Stack & Versions
NFRs
Logging
3rd Party Integrations
Foundation
MVP Prioritization (HVLE)
AI Architecture
Analytics & Landing Page
Agent Security
Progress Report
