whiteport-design-studio 0.1.1 → 0.2.0

package/src/workflows/3-scenarios/steps-c/step-03-build-vtcs.md

@@ -0,0 +1,191 @@
+---
+name: 'step-03-build-vtcs'
+description: 'Extract Value Trigger Chains from Trigger Map to identify which scenarios to create'
+
+# File References
+nextStepFile: './step-04-suggest-scenarios.md'
+---
+
+# Step 3: Build Value Trigger Chains
+
+## STEP GOAL:
+
+Extract Value Trigger Chains (VTCs) from the Trigger Map, assign pages to each VTC, prioritize them, and verify complete coverage of all pages.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a UX Scenario Architect collaborating with the project owner
+- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring scenario thinking and user journey expertise, user brings their project knowledge, together we create concrete UX scenario outlines
+- ✅ Maintain collaborative equal-partner tone throughout
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on building VTCs, assigning pages, and prioritizing
+- 🚫 FORBIDDEN to create scenario outlines — only identify and plan scenarios
+- 💬 Approach: Systematically trace paths from business goals to user actions
+- 📋 Every page from the inventory must be assigned to exactly one VTC
+
+## EXECUTION PROTOCOLS:
+
+- 🔗 Trace complete chains from Business Goal → Persona → Force → Transaction → Scenario
+- 📋 Answer all 7 Decision Matrix questions for each VTC
+- 📊 Assign pages ensuring no repetition and full coverage
+- 🚫 FORBIDDEN to leave any page unassigned
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Product Brief, Trigger Map, approved page inventory from Step 2
+- Focus: VTC extraction, page assignment, prioritization
+- Limits: No scenario outlining, no file creation — only planning
+- Dependencies: Approved scope analysis from Step 2
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Build VTCs
+
+**What is a Value Trigger Chain?**
+
+A VTC traces the path from business strategy to user action:
+
+```
+Business Goal → Persona → Driving Force → Transaction → Scenario
+```
+
+**Example:**
+```
+BG01: Reduce info calls by 40%
+  → Hasse (Primary - stressed tourist)
+    → Fear: Being stranded with broken RV
+      → Transaction: Confirm mechanic capability + get directions
+        → 01: "Hasse's Emergency Search"
+```
+
+For **each business goal** from the Trigger Map:
+
+1. Identify which persona(s) most directly drive this goal
+2. Identify which driving forces (wants AND fears) connect to this goal
+3. Determine the specific transaction/action that fulfills it
+4. Name a candidate scenario using the persona's name
+
+**For each VTC, answer the Decision Matrix (all 7 required):**
+
+| # | Question | Answer |
+|---|----------|--------|
+| 1 | Which business goal? | [Specific goal from Trigger Map] |
+| 2 | Which persona? | [Name + priority level] |
+| 3 | Which driving force? | [Specific want or fear] |
+| 4 | What's the transaction? | [Concrete action user takes] |
+| 5 | Where does user come from? | [Natural starting point - be specific] |
+| 6 | What value does user get? | [Tangible outcome] |
+| 7 | What value does business get? | [Measurable result] |
+
+### 2. Assign Pages to VTCs
+
+For each VTC, list which pages from the inventory (Step 02) the user visits.
+
+**Rules:**
+- Each page appears in exactly ONE VTC/scenario (no repetition)
+- If a page could fit multiple scenarios, assign it to the highest-priority one
+- Shared elements (navigation, footer) are excluded from page assignment
+
+### 3. Prioritize
+
+Rank the VTCs:
+
+**Priority 1 — Critical Path:**
+- Top business goal + primary persona + core product value
+- These scenarios are created first and in most detail
+
+**Priority 2 — Supporting:**
+- Secondary persona scenarios, alternative entry paths
+- Important but not the strategic core
+
+**Priority 3 — Edge Cases:**
+- Admin tasks, rare user segments, error recovery
+- May be deferred to later phases
+
+### 4. Coverage Check
+
+After building all VTCs, verify:
+
+- [ ] Every page from inventory is assigned to exactly one VTC
+- [ ] Primary persona has at least one Priority 1 scenario
+- [ ] Top business goal is addressed by at least one scenario
+- [ ] No page appears in multiple scenarios
+
+**If pages are unassigned:** Create additional VTCs or expand existing ones to cover them.
+
+### 5. Present VTC List
+
+Present the complete VTC list:
+
+```
+## Value Trigger Chains
+
+### Priority 1
+**VTC-01:** [Business Goal] → [Persona] → [Force] → [Transaction]
+- Scenario: 01-[slug]
+- Pages: [list]
+
+### Priority 2
+**VTC-02:** [Business Goal] → [Persona] → [Force] → [Transaction]
+- Scenario: 02-[slug]
+- Pages: [list]
+
+### Coverage: [X/Y] pages assigned
+```
+
+### 6. Present MENU OPTIONS
+
+Display: "Are you ready to [C] Continue to Scenario Suggestions?"
+
+#### Menu Handling Logic:
+
+- IF C: Load, read entire file, then execute {nextStepFile}
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+- User can chat or ask questions - always respond and then end with display again of the menu options
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN [C continue option] is selected and [VTC list with full page coverage presented], will you then load and read fully `{nextStepFile}` to execute and begin scenario suggestions.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All business goals traced through complete VTC chains
+- All 7 Decision Matrix questions answered for each VTC
+- Every page from inventory assigned to exactly one VTC
+- VTCs prioritized with clear rationale
+- Coverage check passes (all pages assigned, no duplicates)
+- Complete VTC list presented to user
+- Menu presented and user input handled correctly
+
+### ❌ SYSTEM FAILURE:
+
+- Leaving pages unassigned
+- Assigning pages to multiple VTCs
+- Skipping Decision Matrix questions
+- Creating scenario outlines during this step
+- Not verifying coverage before proceeding
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/workflows/3-scenarios/steps-c/step-04-suggest-scenarios.md

@@ -0,0 +1,181 @@
+---
+name: 'step-04-suggest-scenarios'
+description: 'Present scenario plan to user for approval before creating outlines'
+
+# File References
+nextStepFile: './step-05-outline-scenario.md'
+---
+
+# Step 4: Suggest Scenarios (USER CHECKPOINT)
+
+## STEP GOAL:
+
+Present the complete scenario plan to the user for approval before creating any outlines, ensuring alignment on scenario count, page assignments, naming, and priorities.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a UX Scenario Architect collaborating with the project owner
+- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring scenario thinking and user journey expertise, user brings their project knowledge, together we create concrete UX scenario outlines
+- ✅ Maintain collaborative equal-partner tone throughout
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on presenting the scenario plan and getting user approval
+- 🚫 FORBIDDEN to proceed to outlining without explicit user approval
+- 💬 Approach: Present clearly, handle feedback gracefully, re-present if needed
+- 📋 This is a critical USER CHECKPOINT — do not auto-proceed under any circumstances
+
+## EXECUTION PROTOCOLS:
+
+- 📋 Format scenario plan exactly as specified
+- ✅ Include coverage check with all four verifications
+- 🔄 Handle user feedback and re-present adjusted plan
+- 🚫 FORBIDDEN to skip user approval checkpoint
+
+## CONTEXT BOUNDARIES:
+
+- Available context: VTCs from Step 3, page inventory, Trigger Map data
+- Focus: Presenting and getting approval for the scenario plan
+- Limits: No scenario outlining, no file creation — only planning approval
+- Dependencies: Complete VTC list from Step 3
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Format the Scenario Plan
+
+Present to user in this exact format:
+
+```
+## Scenario Plan for [Project Name]
+
+### Site Analysis
+- **Type:** [Presentation / Dynamic / Mixed]
+- **Total Pages:** [N]
+- **Format:** [Screen Flow / Storyboard / Mixed]
+- **Scenarios:** [N] total
+
+---
+
+### Suggested Scenarios
+
+**01: [Persona Name]'s [Purpose]** ⭐ Priority 1
+- **Pages:** [comma-separated list]
+- **Persona:** [Name] — [Primary driving force]
+- **User Value:** [What user gets — be specific]
+- **Business Value:** [What business gets — be measurable]
+- **Format:** [Screen Flow / Storyboard]
+
+**02: [Persona Name]'s [Purpose]** ⭐ Priority 1
+- **Pages:** [comma-separated list]
+- **Persona:** [Name] — [Primary driving force]
+- **User Value:** [specific]
+- **Business Value:** [measurable]
+- **Format:** [Screen Flow / Storyboard]
+
+[Continue for all scenarios...]
+
+---
+
+### Coverage Check
+✅ All pages assigned: [Yes/No — if No, list unassigned pages]
+✅ No page repetition: [Yes/No]
+✅ Primary persona covered: [Yes/No]
+✅ Top business goal addressed: [Yes/No]
+```
+
+### 2. Naming Rules
+
+Scenario names MUST use persona names:
+
+**Good:**
+- "Hasse's Emergency Search"
+- "Lars Checks Workshop Hours"
+- "Åke Coordinates Fleet Service"
+
+**Bad:**
+- "Emergency Booking Flow"
+- "Hours Lookup"
+- "Service Scheduling"
+
+**Why:** Keeps persona psychology front-of-mind throughout design.
+
+### 3. Scenario ID Convention
+
+- Format: `01`, `02`, `03`, etc.
+- Folder slug: `01-hasses-emergency-search` (lowercase, hyphenated)
+- File: `01-hasses-emergency-search.md`
+
+### 4. Wait for Approval
+
+**CHECKPOINT — Wait for user response.**
+
+User may:
+- **"Looks good, proceed"** → Continue to menu options
+- **"Combine X and Y"** → Adjust and re-present
+- **"Add a scenario for [purpose]"** → Add VTC and re-present
+- **"Focus on just [one flow]"** → Apply selective ignorance, re-present
+- **"Missing page [X]"** → Add to inventory and assign
+
+**Do NOT proceed to Step 05 until user explicitly approves the scenario plan.**
+
+### 5. Record Approved Plan
+
+After user approval, record:
+- Final scenario count
+- Final page assignments
+- Any user adjustments and reasoning
+
+### 6. Present MENU OPTIONS
+
+Display: "Are you ready to [C] Continue to Outlining Scenarios?"
+
+#### Menu Handling Logic:
+
+- IF C: Load, read entire file, then execute {nextStepFile}
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+- User can chat or ask questions - always respond and then end with display again of the menu options
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN [C continue option] is selected and [user has explicitly approved the scenario plan], will you then load and read fully `{nextStepFile}` to execute and begin scenario outlining.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Scenario plan formatted exactly as specified
+- All scenarios use persona names in their titles
+- Coverage check included and all four items verified
+- User explicitly approves the plan before proceeding
+- User feedback handled gracefully with re-presentation
+- Approved plan recorded with any adjustments noted
+- Menu presented and user input handled correctly
+
+### ❌ SYSTEM FAILURE:
+
+- Proceeding without explicit user approval
+- Using feature-first naming instead of persona names
+- Missing coverage check
+- Not handling user feedback (combining, adding, removing scenarios)
+- Auto-proceeding past the user checkpoint
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/workflows/3-scenarios/steps-c/step-05-outline-scenario.md

@@ -0,0 +1,215 @@
+---
+name: step-05-outline-scenario
+description: Create detailed outline for ONE scenario, repeating for each in the approved plan
+
+# File References
+nextStepFile: './step-06-generate-overview.md'
+
+# Data References
+scenarioTemplate: '../data/scenario-outline-template.md'
+---
+
+# Step 5: Outline Scenario (One at a Time)
+
+## STEP GOAL:
+
+Create a detailed outline for ONE scenario using all 7 required components, verify against quality gates, create the output file, then loop for each remaining scenario in the approved plan.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a UX Scenario Architect collaborating with the project owner
+- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring scenario thinking and user journey expertise, user brings their project knowledge, together we create concrete UX scenario outlines
+- ✅ Maintain collaborative equal-partner tone throughout
+
+### Step-Specific Rules:
+
+- 🎯 Focus on ONE scenario at a time, complete it fully before moving to the next
+- 🚫 FORBIDDEN to skip any of the 7 required components
+- 💬 Approach: Collaborate with user on each scenario, using the template as structure
+- 📋 Verify all quality gates before proceeding to the next scenario or step
+
+## EXECUTION PROTOCOLS:
+
+- 📖 Load the scenario outline template before starting
+- 📋 Ensure all 7 components are present and high quality
+- ✅ Run quality gates check before moving on
+- 💾 Create output file in the correct folder structure
+- 🔄 Loop back for each remaining scenario
+- 🚫 FORBIDDEN to proceed if any quality gate fails
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Approved scenario plan from Step 4, VTCs, page inventory, Trigger Map
+- Focus: Detailed outlining of one scenario at a time
+- Limits: Only outline scenarios from the approved plan
+- Dependencies: User-approved scenario plan from Step 4
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Determine Which Scenario
+
+Process scenarios in priority order (Priority 1 first, then 2, then 3).
+
+If this is your first time at this step, start with scenario 01.
+If returning from a loop, continue with the next unfinished scenario.
+
+### 2. Load Template
+
+Load the full template: `{scenarioTemplate}`
+
+### 3. Create Outline with 7 Required Components
+
+Every scenario outline MUST have all 7 components:
+
+#### Component 1: Scenario Name & ID
+
+- **Name:** Uses persona name + purpose (e.g., "Hasse's Emergency Search")
+- **ID:** 01, 02, etc.
+- **Slug:** `01-hasses-emergency-search`
+
+#### Component 2: Core Feature
+
+What this scenario covers, stated as user purpose (not feature name).
+
+- **Bad:** "Homepage and service pages"
+- **Good:** "Verify service availability before booking"
+
+Must align with a specific business goal from the Trigger Map.
+
+#### Component 3: Entry Point (Realistic)
+
+How the user ACTUALLY arrives. Be specific about:
+- **Device:** Mobile, desktop, tablet
+- **Context:** Where they are, what they are doing
+- **Discovery:** How they found the site (Google search, link, ad, bookmark)
+
+- **Bad:** "User opens app"
+- **Good:** "Googles 'car repair Oland' on mobile while parked at gas station, clicks top organic result"
+
+#### Component 4: Mental State (Trigger / Hope / Worry)
+
+Three components, all required, all specific:
+
+- **Trigger:** What just happened that brought them here NOW
+- **Hope:** What they are hoping to find or achieve
+- **Worry:** What they are afraid of or want to avoid
+
+- **Bad:** "User is interested in the product"
+- **Good:** "Trigger: Motorhome broke down in Byxelkrok, family vacation at risk. Hope: Find trustworthy mechanic nearby, get back on road today. Worry: Being stranded for days, getting ripped off by unknown mechanic"
+
+#### Component 5: Success Goals (Mutual Value)
+
+Both required, both specific and measurable:
+
+- **User Success:** Tangible outcome the user achieves
+- **Business Success:** Measurable result for the business
+
+- **Bad:** User: "Successfully use the site" / Business: "Get more customers"
+- **Good:** User: "Confirmed mechanic fixes motorhomes, has location and hours, feels confident calling" / Business: "High-intent tourist call captured, positioned as emergency-capable, info call avoided"
+
+#### Component 6: Shortest Path (Linear Sunshine Path)
+
+Numbered steps. Each step has page name + what user accomplishes there.
+
+**Rules:**
+- Completely linear — ZERO "if" statements, ZERO branches
+- Minimum viable steps — can you remove any step without breaking the flow?
+- Each step moves meaningfully toward success
+- This is the happiest path when everything works perfectly
+
+**Format:**
+```
+1. **[Page Name]** — [What user sees/does/achieves here]
+2. **[Page Name]** — [What user sees/does/achieves here]
+3. **[Page Name]** — [What user sees/does/achieves here] ✓
+```
+
+#### Component 7: Trigger Map Connections
+
+Explicitly link to Trigger Map data:
+- **Persona:** [Name] ([Priority level])
+- **Driving Forces Addressed:**
+  - Positive: [specific want from Trigger Map]
+  - Negative: [specific fear from Trigger Map]
+- **Business Goal:** [specific goal + objective number]
+
+### 4. Quality Gates (Check Before Moving On)
+
+Before proceeding to the next scenario, verify:
+
+- [ ] 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)
+- [ ] Both successes are specific and measurable (not vague)
+- [ ] Scenario name includes persona name
+- [ ] All 7 components present
+
+**If any gate fails:** Fix before proceeding.
+
+### 5. Create the File
+
+1. Create folder: `{output_folder}/C-UX-Scenarios/[NN-slug]/`
+2. Create file: `{output_folder}/C-UX-Scenarios/[NN-slug]/[NN-slug].md`
+3. Use the template from data/ to structure the content
+
+### 6. Loop Check
+
+**Are there more scenarios in the approved plan?**
+
+- **Yes** → Loop back to instruction 1 for the next scenario
+- **No** → Proceed to menu options
+
+### 7. Present MENU OPTIONS
+
+Display: "Are you ready to [C] Continue to Generating the Overview?"
+
+#### Menu Handling Logic:
+
+- IF C: Load, read entire file, then execute {nextStepFile}
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+- User can chat or ask questions - always respond and then end with display again of the menu options
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN [C continue option] is selected and [all scenarios from approved plan are outlined and pass quality gates], will you then load and read fully `{nextStepFile}` to execute and begin generating the overview.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Each scenario has all 7 required components
+- All quality gates pass for every scenario
+- Output files created in correct folder structure
+- Scenarios processed in priority order
+- All scenarios from approved plan completed before proceeding
+- Menu presented and user input handled correctly
+
+### ❌ SYSTEM FAILURE:
+
+- Missing any of the 7 required components
+- Proceeding with failing quality gates
+- Skipping scenarios from the approved plan
+- Using generic mental states or vague success goals
+- Creating branching paths instead of linear sunshine paths
+- Not creating output files
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.