whiteport-design-studio 0.2.2 → 0.3.0

package/docs/method/phase-3-prd-platform-guide.md

@@ -1,284 +1,5 @@
-# Phase 3: PRD Platform (Technical Foundation)
+# Phase 3: UX Scenarios
 
-**Agent:** Freya the PM  
-**Output:** `C-Requirements/` (or your configured prefix)
+This guide has moved. Phase 3 is now **UX Scenarios** (not PRD Platform).
 
----
-
-## What This Phase Does
-
-This phase establishes everything technical that can be done **without the final UI**. It's about platform decisions, technical feasibility, and proving that your innovative features actually work.
-
-By the end, you'll have a solid technical foundation and confidence that your key features are buildable.
-
----
-
-## The Core Principle
-
-**Prove our concept works technically — in parallel with design work.**
-
-While UX designers explore how users interact with features, technical validation runs alongside:
-
-- Can we actually build this?
-- Do the external services we need exist and work as expected?
-- What platform and infrastructure do we need?
-- What constraints does design need to know about?
-
-Design and technical validation inform each other. Neither waits for the other to finish.
-
----
-
-## What You'll Create
-
-- **Platform Architecture** - Technology stack and infrastructure decisions
-- **Data Model** - Core entities and relationships
-- **Integration Map** - External services and how they connect
-- **Technical Proofs of Concept** - Validation that risky features work
-- **Experimental Endpoints** - API specs for known requirements (feeds into E-UI-Roadmap)
-- **Security Framework** - Authentication, authorization, data protection
-- **Technical Constraints Document** - What design needs to know
-
----
-
-## How It Works
-
-### Stage 1: Platform Decisions (30-45 minutes)
-
-Establish the technical foundation:
-
-**Architecture:**
-
-- What technology stack fits your needs?
-- Monolith vs. microservices vs. serverless?
-- What hosting/infrastructure approach?
-- What are the key technical constraints?
-
-**Data Model:**
-
-- What are the core entities?
-- How do they relate to each other?
-- What's the database strategy?
-
-### Stage 2: Integration Mapping (20-30 minutes)
-
-Identify all external dependencies:
-
-- Authentication providers (OAuth, SSO)
-- Payment systems (Stripe, PayPal)
-- Third-party APIs (Google Maps, SendGrid, Twilio)
-- Data sources and feeds
-- Analytics and monitoring
-
-### Stage 3: Technical Proofs of Concept (Variable)
-
-**This is crucial.** For innovative or risky features, validate feasibility BEFORE committing to the design.
-
-**Examples:**
-
-| Feature Idea                        | Proof of Concept Question                                          |
-| ----------------------------------- | ------------------------------------------------------------------ |
-| "Show drive time between locations" | Can we call Google Maps Directions API and get estimated duration? |
-| "Real-time availability updates"    | Can we set up WebSocket connections that scale?                    |
-| "AI-powered recommendations"        | Does the ML model perform well enough with our data?               |
-| "Offline mode"                      | Can we sync data reliably when connection returns?                 |
-| "Video calling"                     | Which provider works best? What's the latency?                     |
-
-**What a PoC validates:**
-
-- The API/service exists and does what we need
-- Performance is acceptable
-- Cost is within budget
-- Data format works for our needs
-- Edge cases are handleable
-
-**PoC Output:**
-
-- Working code snippet or prototype
-- Documented limitations and gotchas
-- Cost estimates (API calls, compute, etc.)
-- Go/No-Go recommendation for the feature
-
-> **Why this matters:** It's a great morale boost when you've proven your core features will work. And if you discover limitations or surprises, it's valuable to know them early so design can account for them from the start.
-
-### Stage 4: Security & Performance Framework (20-30 minutes)
-
-**Security:**
-
-- Authentication approach (passwords, OAuth, SSO, passwordless)
-- Authorization model (roles, permissions, row-level security)
-- Data encryption needs (at rest, in transit)
-- Compliance requirements (GDPR, HIPAA, PCI-DSS, etc.)
-
-**Performance:**
-
-- Expected load and scale
-- Response time expectations
-- Availability requirements (99.9%? 99.99%?)
-- Caching strategy
-
-### Stage 5: Experimental Endpoints (Variable)
-
-**Set up the endpoints you KNOW you'll need.**
-
-Even before the UI is designed, you often know certain data operations are essential. Setting these up early provides:
-
-- **Early validation** - Does the endpoint actually return what we need?
-- **Fail fast** - Discover problems before investing in design
-- **Developer head start** - Backend work can begin immediately
-- **Design confidence** - Designers know what data is available
-
-**What to set up:**
-
-| Endpoint Type         | Example                                  | Why Early?                  |
-| --------------------- | ---------------------------------------- | --------------------------- |
-| Core CRUD             | `GET /api/dogs`, `POST /api/bookings`    | Foundation for everything   |
-| External integrations | `GET /api/routes/estimate` (Google Maps) | Validates third-party works |
-| Authentication        | `/api/auth/login`, `/api/auth/refresh`   | Security model proven       |
-| Key calculations      | `/api/availability/check`                | Business logic validated    |
-
-**Output:**
-
-For each experimental endpoint, document:
-
-- Endpoint specification (method, path, request/response)
-- What it validates
-- Current status (stub, working, blocked)
-- Dependencies and notes
-
-These specifications go in your Requirements folder AND become tasks in the `E-UI-Roadmap/` handover folder for development teams.
-
-> **The mindset:** Every endpoint you validate early is one less surprise during development. Every endpoint that fails early saves weeks of wasted design work.
-
-### Stage 6: Technical Constraints Document (15-20 minutes)
-
-Create a summary of what UX design needs to know:
-
-- **What's possible** - Features validated by PoCs
-- **What's not possible** - Technical limitations discovered
-- **What's expensive** - Features with high API/compute costs
-- **What affects design** - Loading times, offline behavior, real-time vs. polling
-- **Platform capabilities** - What the framework/platform provides out of the box
-
-This document becomes essential input for Phase 4 (UX Design).
-
----
-
-## The Design Connection
-
-Phase 3 is informed by:
-
-- **Product Brief** (Phase 1) - Strategic vision and constraints
-- **Trigger Map** (Phase 2) - Prioritized features from Feature Impact Analysis
-
-And it enables:
-
-- **UX Design** (Phase 4) - Design within known technical constraints
-- **Design System** (Phase 5) - Component technical requirements
-- **Development** - Platform work can begin in parallel with design
-
----
-
-## Parallel Streams
-
-Once Phase 3 is complete:
-
-```
-Phase 3 Complete
-       │
-       ├──► E-UI-Roadmap/ receives:
-       │    • Experimental endpoint specs
-       │    • API implementation tasks
-       │    • Infrastructure setup tasks
-       │
-       ├──► Platform/Backend Development can START
-       │    (Infrastructure, APIs, data model)
-       │
-       └──► Phase 4: UX Design can START
-            (Informed by technical constraints)
-```
-
-This parallelism is one of WDS's key efficiency gains. Development teams can begin backend work while designers continue with UX.
-
----
-
-## When to Use This Phase
-
-**Use this phase when:**
-
-- Building platform/infrastructure for a new product
-- Features depend on external APIs or services
-- Innovative features need technical validation
-- Development team needs architectural clarity before design
-
-**Skip or minimize if:**
-
-- Simple project with obvious technical approach
-- Working within existing platform/infrastructure
-- Enhancement that doesn't change architecture
-- All features use proven, familiar technology
-
----
-
-## What to Prepare
-
-Bring:
-
-- Product Brief (Phase 1)
-- Trigger Map with Feature Impact Analysis (Phase 2)
-- Any existing technical constraints
-- Development team availability for PoC work
-
----
-
-## What Comes Next
-
-Your technical foundation enables:
-
-- **Phase 4: UX Design** - Design with confidence about what's technically possible
-- **Phase 6: Dev Integration** - Handoff with complete technical context
-- **Development** - Backend/platform work can begin immediately
-
----
-
-## Tips for Great Sessions
-
-**Validate risky features first**
-
-- If the Google Maps API doesn't return drive times in a usable format, you need to know NOW
-- Don't design features you can't build
-
-**Document constraints clearly**
-
-- Designers need to know what's possible
-- "Loading state required" vs "instant" changes UX significantly
-
-**Involve developers**
-
-- Technical decisions benefit from dev input
-- PoC work may require developer time
-- Architecture is a conversation, not a decree
-
-**Stay connected to strategy**
-
-- Reference Feature Impact Analysis scores
-- High-impact features deserve more PoC investment
-- Don't over-engineer for hypothetical needs
-
----
-
-## Example Output
-
-See: `examples/dog-week-patterns/C-Requirements/` for the Dog Week technical foundation.
-
-**What Dog Week needed to prove early:**
-
-- _"Can we show dog owners how long it takes to walk to a dog walker?"_ → Google Maps Directions API returns walking time between coordinates ✓
-- _"Can we check real-time availability across multiple walkers?"_ → Endpoint aggregates calendar data in <200ms ✓
-- _"Can we handle Swish payments for Swedish users?"_ → Swish API integration validated with test transactions ✓
-- _"Can walkers see their schedule on mobile?"_ → Responsive calendar component renders correctly on iOS/Android browsers ✓
-
-These early discoveries shaped both the design AND the development approach.
-
----
-
-_Phase 3 of the Whiteport Design Studio method_
+See: [Phase 3: UX Scenarios Guide](./phase-3-ux-scenarios-guide.md)

package/docs/method/phase-3-ux-scenarios-guide.md

@@ -0,0 +1,193 @@
+# Phase 3: UX Scenarios (Scenario Outlines)
+
+**Agent:** Saga the Analyst
+**Output:** `C-UX-Scenarios/` (in your configured design artifacts folder)
+
+---
+
+## What This Phase Does
+
+UX Scenarios transforms your Trigger Map into concrete user journeys. Through the **8-question scenario dialog**, you define each meaningful transaction a user performs on your site — starting with the most important one.
+
+By the end, you'll have scenario outlines that ground every design decision in real user psychology and business goals.
+
+---
+
+## The 8-Question Scenario Dialog
+
+This is the core of Phase 3. For each scenario, you walk through 8 strategic questions — one at a time, as a natural conversation:
+
+| # | Question | What it establishes |
+|---|----------|-------------------|
+| Q1 | "What transaction do we need to get really right?" | The key user journey |
+| Q2 | "Which business goal does it serve?" | Trigger Map connection |
+| Q3 | "Which user, and in what real-life situation?" | Persona + context |
+| Q4 | "What do they want and fear going into this?" | Driving forces |
+| Q5 | "What device are they on?" | Platform |
+| Q6 | "What's the natural starting point?" | Entry point + discovery |
+| Q7 | "What's the best possible outcome — for both sides?" | Mutual success |
+| Q8 | "What's the shortest path through the site?" | Linear sunshine path |
+
+**What counts as a transaction:** Not just purchases or bookings. Clicking through a menu item by item to research site content is a transaction. Comparing options is a transaction. Any meaningful journey where the user moves through the site with intent.
+
+### Two Modes
+
+- **Conversation mode** (default): Saga asks, you answer. One question at a time. Each answer shapes the next question naturally.
+- **Suggest mode**: Saga answers all 8 questions based on the Trigger Map and Product Brief. You review and adjust.
+
+---
+
+## The Scenario → Page Flow
+
+After the 8 questions define a scenario, the process continues with page outlining and design:
+
+```mermaid
+flowchart TD
+    A["8-Question Scenario Dialog\nQ1-Q8 → Name → Quality Gates → Save"] --> B{"Post-Scenario Menu"}
+
+    B -->|"[N] Next scenario"| A
+    B -->|"[O] Outline pages"| C["Page Outline Dialog"]
+    B -->|"[D] Design first page"| D["Create First Page Folder"]
+    B -->|"[C] Overview"| Z["Generate Scenario Overview"]
+
+    C --> E{"For each page:"}
+    E --> F["1. What's the point of this page?\n2. What does the user do to move forward?"]
+    F --> G{"Interaction type?"}
+    G -->|"Leaves page"| H["New scenario step\n→ Create page folder"]
+    G -->|"Stays on page"| I["Storyboard item\n→ Document in page spec"]
+    I --> F
+    H --> J{"Continue?"}
+    J -->|"Next page"| E
+    J -->|"Stop"| B
+
+    D --> K["Phase 4: Design Page\nSteps 08-15"]
+
+    K --> L{"Page Complete Menu"}
+    L -->|"[N] Next page"| M["Outline → Design Loop"]
+    L -->|"[R] Dashboard"| N["Phase 4 Scenario Dashboard"]
+    L -->|"[V] Validate"| O["Audit Page Spec"]
+    O --> L
+
+    M --> P["Outline next page\nPurpose + Exit Action"]
+    P --> Q["Create page folder"]
+    Q --> K
+```
+
+### The Page Outline Dialog
+
+For each page in the scenario, ask two questions:
+
+**1. "What's the point of this page?"**
+What does the user need to accomplish here?
+- e.g., "See a list of news articles" or "Find the phone number and opening hours"
+
+**2. "What does the user do to move forward?"**
+What interaction takes them to the next step?
+- e.g., "Selects 'News' in the menu" → next page is the News listing
+
+**Two types of interactions:**
+- **Leaves the page** → new scenario step (new page folder)
+- **Stays on the page** → storyboard item (documented within the page spec)
+
+### The Outline → Design Loop
+
+After designing a page in Phase 4, the user can choose [N] to outline and design the next page. This creates a continuous loop:
+
+1. **Outline** the next page (purpose + exit action)
+2. **Create** the page folder with boilerplate spec
+3. **Design** the page (Phase 4 steps 08-15)
+4. **Repeat** until all pages are done
+
+---
+
+## Page Folder Structure
+
+Each page gets its own folder with a spec and a Sketches subfolder:
+
+```
+C-UX-Scenarios/01-hasses-emergency-search/
+├── 01-hasses-emergency-search.md         # Scenario outline
+└── pages/
+    ├── 01.1-start-page/
+    │   ├── 01.1-start-page.md            # Full boilerplate
+    │   └── Sketches/
+    ├── 01.2-services/
+    │   ├── 01.2-services.md              # Minimal boilerplate
+    │   └── Sketches/
+    └── 01.3-contact/
+        ├── 01.3-contact.md               # Minimal boilerplate
+        └── Sketches/
+```
+
+**Naming convention:** `{scenario-number}.{step-number}-{page-slug}`
+
+The **first page** gets rich context from the 8-question dialog (device, arrival method, mental state, user situation). Remaining pages get minimal boilerplate with page purpose.
+
+---
+
+## What You'll Create
+
+- **Scenario outlines** — one per transaction, grounded in Trigger Map personas and business goals
+- **Page folders** — structured boilerplate specs ready for Phase 4 design
+- **Scenario overview** — summary of all scenarios with page assignments
+
+---
+
+## Post-Scenario Options
+
+After each scenario, you choose:
+
+| Option | What happens |
+|--------|-------------|
+| **[N] Next scenario** | Define the next transaction for the next target group |
+| **[O] Outline pages** | Walk through pages one at a time, creating folders |
+| **[D] Design first page** | Create first page folder and jump to Phase 4 |
+| **[C] Continue** | Generate scenario overview (when all are done) |
+
+---
+
+## Quality Gates
+
+Before moving on from a scenario, Saga verifies:
+
+- All 8 questions answered with specific, concrete responses
+- Mental state is visceral and specific (not generic "interested")
+- Entry point is realistic with device + context + discovery method
+- Path is truly linear (zero "if" statements, zero branches)
+- Both successes are specific and measurable
+- Scenario name includes persona name
+- Trigger Map connection is explicit
+
+---
+
+## When to Use This Phase
+
+**Always use this phase** — it's the bridge between strategy (Phases 1-2) and design (Phase 4). Without scenarios, page design lacks context and purpose.
+
+**Process scenarios in priority order:**
+1. Primary transaction for primary target group
+2. Secondary transactions
+3. Tertiary/edge case transactions
+
+---
+
+## What to Prepare
+
+Bring:
+- **Product Brief** (Phase 1) — strategic context
+- **Trigger Map** (Phase 2) — personas, driving forces, business goals
+- **Page inventory** — known pages from the Trigger Map's feature analysis
+
+---
+
+## Connection to Phase 4
+
+Phase 3 scenarios feed directly into Phase 4 design:
+
+- **Scenario gate**: Phase 4 checks for existing scenarios before page design. No scenario? It redirects you back to Phase 3.
+- **Page handover**: The first page spec includes device, mental state, and entry context — everything Freya needs to start designing.
+- **Outline → Design loop**: After designing a page, you can outline the next one and continue designing without leaving Phase 4.
+
+---
+
+_Phase 3 of the Whiteport Design Studio method_