Saas Vertical Slice

---
name: saas-vertical-slice
description: "Pre-production validation — end-to-end build to confirm the full loop is achievable before committing to Production. After PRDs, architecture, UX specs."
argument-hint: "[--review full|lean|solo]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/saas-vertical-slice/../../hooks/yaml-helper.sh" resolve_config *)
model: sonnet
---

!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys locale,review_mode,automation,workflow`

Resolved above — use as-is; `--review` overrides `review_mode` for this run. No
block → defaults in `.claude/docs/config-resolution.md`.

# Vertical Slice

> **Interaction Localization Rule**:
> When `locale: pt-BR` (or user speaks Portuguese), ALL questions (`AskUserQuestion` / `ask_question`), confirmation prompts, and selectable options MUST be translated and presented in **Brazilian Portuguese (PT-BR)**.
> Any English question text or options in this skill are illustrative examples — NEVER display English questions or options to a Portuguese developer.
> Internal reasoning, code synthesis, tests, and documentation files MUST remain in English.



## Purpose

The **vertical slice** answers a different question from the concept prototype:
*"Can we build this full application lifecycle at production quality, on schedule?"*

**Default use** — run late in Pre-Production, after PRDs, architecture, and UX
specs are complete. It is a near-production-quality build demonstrating one complete
[start → challenge → resolution] cycle.

**Post-pivot?** If a PIVOT verdict from an earlier vertical slice sent you back to
revise PRDs and architecture, run this again after revisions to re-validate. It can
be run as many times as needed until a PROCEED or KILL verdict is reached.

It validates:

1. The pipeline (can the team actually produce this quality of content?)
2. Execution feasibility (are the architecture decisions correct for this SaaS product?)
3. Fun survival (does the fun from the concept prototype survive full design?)
4. **Velocity** (how long did this take? That's your real production rate estimate.)

**Earlier in the project?** If you haven't written PRDs yet and want to validate
whether the core idea is worth designing, run `/saas-prototype` (concept prototype) instead.

---

## Phase 1: Resolve Review Mode and Load Context


See `.claude/docs/director-gates.md` for the full check pattern. Individual gate definitions live in `.claude/docs/director-gates/[gate-id].md` — the spawned agent reads its own gate file; do not read it in the parent session.


Every `AskUserQuestion` call follows `.claude/docs/automation-modes.md`
(collaborative asks always · guided major-only · autonomous logs and proceeds;
`automation_always_ask` categories always prompt).

Read the following files to understand the full design intent. Read each PRD, ADR
and the control manifest by section: check if `.basinfy/` exists: if present, use the Basinfy Protocol (`basinfy_search` then `basinfy_read`); otherwise check if `.basinfy/` exists: if present, use the Basinfy Protocol (`basinfy_search` then `basinfy_read`); otherwise check if `.basinfy/` exists: if present, use the Basinfy Protocol (`basinfy_search` then `basinfy_read`); otherwise check if `.basinfy/` exists: if present, use the Basinfy Protocol (`basinfy_search` then `basinfy_read`); otherwise find the headings you need with the Basinfy Protocol (`basinfy_search` / `basinfy_read` if `.basinfy/` exists) or the Basinfy Protocol (`basinfy_search` / `basinfy_read` if `.basinfy/` exists) or the Basinfy Protocol (`basinfy_search` / `basinfy_read` if `.basinfy/` exists) or the Grep tool (pattern `^#`, content mode) and Read those ranges with offset and limit.
- `CLAUDE.md` — tech stack and engine
- `design/prd/product-concept.md` — core value proposition and product pillars (or
  `design/product-brief.md`, the one-page brief that replaces it at `rigor: minimal` —
  pitch, core loop and "what they feel" line; it has no pillars)
- `design/prd/features-modules-index.md` — MVP systems and their priorities
- `docs/architecture/architecture.md` — layer structure
- `docs/architecture/control-manifest.md` — technical rules for implementation
- Key PRDs for the systems being sliced

---

## Phase 2: Define the Slice Scope and Validation Question

Before building, define the **falsifiable validation question**:

> *"Does a user, starting from nothing, experience [core fantasy from product-concept.md or product-brief.md]
> within [N] minutes, without developer guidance — and can we build one such loop
> in [X] days at representative quality?"*

Both parts matter: user experience AND build feasibility.

**Scope discipline:**
- Include ALL core loop systems (minimum). If a system is required to complete one
  [start → challenge → resolution] cycle, it must be in the slice.
- **Target scope: 3–5 minutes of polished, continuous core business workflow.** This is the
  industry-standard vertical slice length — long enough to demonstrate core workflows
  and tone, short enough to build at representative quality. If your slice would
  take longer than 5 minutes to play through, cut content, not quality.
- **Cut scope before cutting quality.** A low-quality slice that looks nothing like
  the intended SaaS application cannot validate production feasibility.
- If the scope feels too large to build in 1–3 weeks, the slice scope is wrong —
  not too big to build, but the slice is trying to prove too much at once.

**Scope creep warning:** The vertical slice is the highest-risk moment for scope
creep in the pre-production phase. Features feel "almost there" and it's tempting
to add "just one more system." Resist this. Cut, do not extend.

Present scope to the user before building and get confirmation.

---

## Phase 3: Plan the Build

Define in bullet points:
- Systems implemented (which PRD sections are being exercised)
- The complete application lifecycle cycle ([start] → [challenge] → [resolution] exactly)
- Art and audio quality level (placeholder acceptable, representative preferred)
- Specific, measurable success criteria for the validation question
- Hard time limit: [X] days. If exceeded, scope was wrong — stop and reassess.

Ask the user to confirm scope before building. Name the checkpoint file in that
confirmation: "May I record this plan in `production/session-state/active.md`?"

Once confirmed, write a session checkpoint to `production/session-state/active.md`
(create `production/session-state/` if it does not exist). Include: concept name,
validation question, systems in scope, art quality level, and current phase ("Phase
4 — Implement"). Update this file at the end of each build day with what was
completed. This is the primary recovery mechanism if the session ends mid-slice —
multi-week Engine builds will span many sessions.

---

## Phase 4: Implement

Ask: "May I create the vertical slice directory at
`prototypes/[concept-name]-vertical-slice/` and begin implementation?"

If yes, create the directory. Every file must begin with:

```
[comment] VERTICAL SLICE - NOT FOR PRODUCTION
[comment] Validation Question: [What this build is proving]
[comment] Date: [Current date]
```

Write `[comment]` in each file's own comment syntax — `#` in TypeScript (`.ts`) and
Python, `//` in C#, C++ and JavaScript, `--` in Lua, `<!-- … -->` in HTML and
Markdown. A header in another language's syntax is a parse error, not a label.
Files that cannot hold a comment (JSON, engine-generated scene and project
files) are exempt.

**Quality standards** — higher than concept prototype, not full production:
- Follow architecture layers from `docs/architecture/control-manifest.md`
- Naming conventions — `naming.*` from `project.yaml`; for any key absent or empty (including when `project.yaml` has no `naming` block), from `.claude/docs/technical-preferences.md`
- No hardcoded core business workflow values — use constants or config files
- Basic error handling on critical paths
- Placeholder art acceptable; representative art preferred

**Multi-turn loop:** After writing the initial files, ask the user to run the
build and report what they observe. Iterate until the complete application lifecycle cycle
is demonstrable. Each round:
1. User runs → reports errors or observations
2. Agent fixes errors or adjusts systems
3. Repeat until the full [trigger → core action → value realized] cycle is functional end-to-end

**Sunk cost checkpoint (day 3 of planned timeline):** If the full application lifecycle cycle
is not yet demonstrable, stop and reassess. Either the scope is too large or an
architectural assumption is wrong. Surface the blocker explicitly rather than
continuing to iterate.

Conduct at least 1 usability test session once the loop is demonstrable.

**Usability testing tip:** If you can get anyone who hasn't seen the application to test it —
a friend, family member, online community — watch them silently without explaining
anything. Don't guide them. Their confusion reveals what the application isn't
communicating on its own. This gives much better signal than self-testing.

**No external testers available?** Use rotation within the team: Dev A built
system X, so Dev A is a naive tester for system Y. Even a two-person team can
rotate effectively. Solo? Step away for 2-3 days then play through as a new
user — you won't have perfect first-impression signal but you'll catch the
critical blockers. Also try a "silent walkthrough": play your own slice in one
sitting without stopping to fix anything and log every moment you hesitate.

**Want richer observation data?** Ask the tester to **think aloud** as they play —
narrate what they're doing and why in real time. "I'm trying to figure out how to
attack... I pressed E... nothing... is it click?" This surfaces confusion the
instant it occurs rather than in retrospect. Best for onboarding and UI clarity
validation. Silent observation is still better for feel testing; think-aloud
changes the experience slightly but produces far more granular UX data.

**Async remote option:** Record a Loom or OBS session — give someone the build,
ask them to record their screen + audio, and send you the video. You get genuine
first-impression data without synchronous scheduling. Works across timezones.

**Testing AI pipeline, worker queue, or complex system behavior before it's fully implemented?** Use the
**Wizard of Oz** technique: one person plays normally while a second person secretly
simulates the worker or service behavior in real time. The user believes it's automated.
This validates the *design intent* of an AI or economy system before the implementation
is complete — and reveals exactly what behaviors the system must produce to feel correct.
Particularly useful for vertical slices where an AI system is in scope but not yet
polished enough for unguided testing.

---

## Phase 5: Usability test Debrief

The loop is demonstrable. Before writing the report, collect structured observations
from actually playing it. Do NOT skip to report generation — the report is only as
good as the observations you capture here.

Say exactly this:
> "Play through the complete [start → challenge → resolution] cycle from scratch,
> as if you're a new user with no knowledge of how it was built. Don't skip ahead
> or use developer shortcuts. Come back when you've completed the full loop —
> or when you've hit something that stopped you."

Once the user returns, ask these questions **one at a time**:

1. **Loop completion:**
   > "Did you complete the full [start → challenge → resolution] cycle on your own,
   > without needing any guidance from me or prior knowledge of the build?"

2. **Time check:**
   > "How long did it take to reach the first meaningful action — the first moment
   > where you felt like you were experiencing real product value?"

3. **Core fantasy:**
   > "The product is supposed to deliver [core value proposition from product-concept.md or product-brief.md].
   > Did it? Be honest — not 'kind of' but specifically what you felt and when."

4. **Blockers:**
   > "What stopped you, confused you, or pulled you out of the experience? Any
   > moment where you weren't sure what to do, or where something broke?"

5. **Pipeline check:**
   > "As the developer — not the user — does this feel achievable at this quality
   > for the full production release? What surprised you about how long things took to build?"

6. **Verdict:**
   > "PROCEED, PIVOT, or KILL — and the specific reason."

If any answer is vague, ask: "Can you give me the specific moment where that happened?"
Precise observations populate the report. Vague ones produce a useless report.

**PROCEED is not available when a validation item is NO.** `/saas-gate-check production`
FAILs a built slice with any NO in its Vertical Slice Validation — a user got
through the loop without developer guidance (question 1), learned what to do
within the first 2 minutes (question 2 — longer is a no), the core workflow feels
good (question 3), no critical blocker bug (question 4). If any of those
answers is no, the verdict is PIVOT or KILL — the user chooses — and the report
names the NO.

**NOT ASSESSED is the fourth verdict.** When nobody has yet evaluated the complete
workflow from scratch — the user cannot test it this session, or stopped before the
end — the validation did not run, and the verdict is **NOT ASSESSED**, with the
reason. It ranks above PROCEED and below PIVOT and KILL: an unevaluated slice has not
earned PROCEED, and a slice known to fail is more actionable than one nobody
evaluated. It is never recorded as PROCEED.

---

## Phase 6: Generate Vertical Slice Report


Track velocity throughout the build. Log:
- Day 1: what was built
- Day 2: what was built
- etc.

This is the most honest data you will ever have about your production rate. Do not
skip it. It feeds directly into sprint planning (at `workflow: minimal`, which has
no sprints, into the brief's build order).

Read `.claude/docs/templates/vertical-slice-report.md` to get the report structure.
If the template file is not found, use this fallback structure:
- `## Vertical Slice Report — [Product Name] — [Date]`
- `### Executive Summary` (PROCEED / PIVOT / KILL / NOT ASSESSED verdict + 2-sentence rationale)
- `### Core Loop Validation` (what was tested, what passed, what failed)
- `### Feel Assessment` (animation, controls, feedback — subjective notes)
- `### Technical Findings` (performance, engine issues, architectural risks)
- `### Velocity Log` (day-by-day actual progress — do not skip)
- `### Lessons Learned` (assumptions broken by building to near-production
  quality; what surprised us about the pipeline or architecture; what we would
  change about the slice scope next time)
- `### Recommended Next Steps`

Fill in every section based on what was observed and built during this session.
The velocity log must reflect actual day-by-day progress, not estimates — this is
the most honest production rate data you will ever have. Replace all placeholder
text with real observations. The recommendation carries the Phase 5 verdict,
NOT ASSESSED included, with its reason.

Ask: "May I write this report to
`prototypes/[concept-name]-vertical-slice/REPORT.md` and add its row to
`prototypes/index.md`?"

If yes, write the file. Then update `prototypes/index.md` (create if it does not
exist) — append one row to the vertical slice table: concept name, date, verdict,
and a link to the REPORT.md. Note whether this was a first-run slice or a re-run
after a PIVOT. The velocity log in this report is some of the most valuable data in
the project — cross-reference it with sprint estimates.

---

## Phase 7: Creative Director Review

**Review mode check:**
- `solo` → skip. Note: "PD-USABILITY-REVIEW skipped — Solo mode."
- `lean` → skip (not a PHASE-GATE). Note: "PD-USABILITY-REVIEW skipped — Lean mode."
- `full` → spawn `product-director` via `Agent` using gate **PD-USABILITY-REVIEW**
  (`.claude/docs/director-gates/cd-usability test.md`) — unless the slice's verdict is
  NOT ASSESSED: with no playthrough there is nothing to review, so note
  "PD-USABILITY-REVIEW skipped — the slice has not been played yet."

Pass: the full REPORT.md content, the validation question, product pillars and core
fantasy from `design/prd/product-concept.md` (or the pitch and "what they feel" line
from `design/product-brief.md` at `rigor: minimal`).

The creative director evaluates the vertical slice result against the SaaS product's
creative vision and pillars and returns one of the gate's verdicts — APPROVE,
CONCERNS or REJECT. Apply it to the recommendation:

- **APPROVE** → the recommendation stands.
- **CONCERNS** → show the concerns alongside the recommendation, then use
  `AskUserQuestion`: `Revise the recommendation` / `Accept with noted concerns` /
  `Discuss further`. The user decides; the director does not.
- **REJECT** (the core fantasy is not present) → a PROCEED recommendation cannot
  stand. Use `AskUserQuestion` to ask the user to choose `PIVOT` or `KILL`, and run
  Phase 8 for that choice. A PIVOT or KILL recommendation stands.
- **NOT ASSESSED** [missing input] → the director made no judgement, so it neither
  backs nor overturns the recommendation (`.claude/docs/director-gates.md`): name
  what was missing, then supply it and re-run the gate, or record
  `PD-USABILITY-REVIEW: NOT ASSESSED — [input]` in the report.

When the director returned CONCERNS, REJECT or NOT ASSESSED, ask "May I update
`prototypes/[concept-name]-vertical-slice/REPORT.md` and its
`prototypes/index.md` row?", then record the director's verdict and reason in
REPORT.md, and the final recommendation in both if it changed.

---

## Phase 8: Summary and Next Steps

Output a summary: the validation question, velocity data, and final recommendation.
Link to `prototypes/[concept-name]-vertical-slice/REPORT.md`.

**If PROCEED:**
Your vertical slice validated the full application lifecycle. The project is ready for
Production.

At `workflow: minimal`: `/saas-create-stories` (from the brief), then `/saas-dev-story`
on the first story — the rest of this list is the `standard`/`full` path.

Recommended next steps (`standard`/`full`):
- `/saas-create-epics layer:foundation` — plan Foundation layer epics
- `/saas-create-epics layer:core` — plan Core layer epics
- `/saas-create-stories [epic-slug]` — break each epic into implementable stories
- `/saas-sprint-plan` — plan the first sprint using velocity data from the slice
- `/saas-gate-check production` — formally advance the stage to Production

**Usability test note:** `/saas-gate-check` will look for documented usability test evidence.
At minimum, 1 documented session with a REPORT.md showing PROCEED is required
to pass the gate. More sessions give more reliable signal — 3+ is recommended
before committing the full team to Production, but is not a hard gate.

**If PIVOT:**

Before routing back to PRD revision, capture the carry-forward note. Ask these
two questions (plain text, one at a time):

1. "What systems or workflows worked at this quality level and should be preserved in the revised design?"
2. "What specifically failed — the core loop, the architecture, the pipeline, or the fun?"

Ask: "May I write this to `prototypes/[concept-name]-vertical-slice/PIVOT-NOTE.md`?"

If yes, write the file with: what worked, what failed, the specific systems or
architecture decisions that need revision, and what the next slice should prove
differently. When `/saas-vertical-slice` is next run after a PIVOT, check the
`prototypes/` directory for a `PIVOT-NOTE.md` — use it to frame the new validation
question and inform scope decisions.

- Revise affected PRDs with `/saas-design-system [system]`
- Address architecture issues via `/saas-architecture-decision`
- Then re-run `/saas-vertical-slice` to validate the revised direction

**If KILL:**

Before abandoning the concept, confirm the verdict is sound:

- [ ] Full application lifecycle takes >5 minutes even for an experienced user?
- [ ] No emotional high point (delight, surprise, satisfaction) observed in any usability test session?
- [ ] 50%+ of testers confused or stuck at the same point after 2+ slice attempts?
- [ ] Architecture issues would require rebuilding more than 50% of what was built?
- [ ] This is the 3rd vertical slice attempt on the same concept?

If 2+ boxes apply → KILL verdict is sound. If 0–1 apply → one targeted PIVOT may recover the concept.

**Document the kill in `prototypes/GRAVEYARD.md`** (create if it doesn't exist).
Ask: "May I append this to `prototypes/GRAVEYARD.md`?" If yes, add one entry:

```
## [Concept Name] Vertical Slice — YYYY-MM-DD
- **Kill reason:** [what specifically prevented the user from experiencing the core fantasy]
- **What worked at slice quality:** [systems or workflows that held up]
- **What failed:** [core loop issue, architecture decision, or pipeline blocker]
- **Next time:** [one specific change for the next time a similar concept is attempted]
```

- Return to `/saas-brainstorm` with what you learned
- Or run `/saas-prototype [new-concept]` to test a new direction cheaply first

**If NOT ASSESSED:**

The slice is built but not validated. Say which reason applied, then finish the
Phase 5 playthrough and debrief — the `production/session-state/active.md`
checkpoint is where to resume — and, after asking, update REPORT.md and its
`prototypes/index.md` row with the verdict. Do not take the slice to
`/saas-gate-check production` as if it had passed: NOT ASSESSED is not a PROCEED.

---

### Important Constraints

- Vertical slice code must NEVER be refactored into production — it is reference only
- Production code must NEVER import from `prototypes/`
- If recommendation is PROCEED, production implementation is written from scratch
  using the slice as a design reference only
- Scope cuts are acceptable; quality cuts are not — a low-quality slice proves nothing
- Total effort: 1–3 weeks. If longer, scope is too large — cut the slice, not the quality.
- Day 3 sunk cost rule: if the full application lifecycle cycle is not demonstrable by then,
  stop and surface the blocker
- **Real-time collaborative / multi-tenant products:** A local vertical slice cannot fully
  validate distributed latency characteristics. Network delay fundamentally changes how data sync, real-time presence, and
  optimistic UI mutations perform — testing locally at 0ms latency behaves entirely differently than 100ms
  WAN conditions. The slice can validate that the end-to-end user loop is coherent and
  functionally complete; validating real-time collaboration under realistic conditions requires staging deployments,
  simulated WAN latency, or multi-client automated tests.