whiteport-design-studio 0.1.0

package/src/workflows/shared/vtc-workshop/vtc-template.yaml

@@ -0,0 +1,210 @@
+# Value Trigger Chain Template
+# See: docs/method/value-trigger-chain-guide.md
+
+vtc:
+  # ==========================================
+  # BUSINESS GOAL
+  # What measurable outcome do we want?
+  # ==========================================
+  business_goal:
+    primary: "500 newsletter signups in Q1"
+    secondary: "" # Optional: Secondary goal this also supports
+
+  # ==========================================
+  # SOLUTION
+  # What are we building to achieve this goal?
+  # ==========================================
+  solution: "Landing page with trend insights lead magnet"
+
+  # ==========================================
+  # USER
+  # Who is the primary user for this solution?
+  # ==========================================
+  user:
+    name: "Harriet"
+    description: "Hairdresser, ambitious, small-town salon owner"
+    context: "Late evening, researching industry trends online"
+    current_state: "Wants to stay ahead of local competitors"
+    priority: "" # Optional: Priority score from Trigger Map
+
+  # ==========================================
+  # DRIVING FORCES
+  # What motivates this user?
+  # ==========================================
+  driving_forces:
+    # Positive: Wishes, aspirations, what they want to achieve
+    positive:
+      - "Wish to be the local beauty authority"
+      - "Wish to attract premium clients"
+      - "Wish to be seen as cutting-edge"
+
+    # Negative: Fears, frustrations, what they want to avoid
+    negative:
+      - "Fear of missing industry trends"
+      - "Fear of losing clients to trendier salons"
+      - "Avoid appearing outdated"
+
+  # ==========================================
+  # CUSTOMER AWARENESS
+  # Where user starts → where we move them
+  # ==========================================
+  customer_awareness:
+    start: "Problem Aware" # Knows: Need to stay current
+    end: "Product Aware" # Knows: Our newsletter helps
+
+  # Awareness stages:
+  # - Unaware: Doesn't know problem exists
+  # - Problem Aware: Knows problem, doesn't know solutions
+  # - Solution Aware: Knows solutions exist, doesn't know yours
+  # - Product Aware: Knows your solution exists
+  # - Most Aware: Has used, loved, advocates
+
+# ==========================================
+# METADATA (Optional but recommended)
+# ==========================================
+metadata:
+  # Creation information
+  created_date: "2025-12-31"
+  created_by: "Product Team"
+  version: "1.0"
+
+  # Source tracking
+  source: "creation" # "creation" (from scratch) or "trigger_map" (extracted)
+  trigger_map_path: "" # If extracted from Trigger Map, path to source
+
+  # Priorities (if from Trigger Map)
+  business_goal_priority: "" # e.g., "1" or "High"
+  user_priority: "" # e.g., "1" or "High"
+
+  # Usage context
+  purpose: "product_pitch" # "product_pitch", "scenario", "prototype", etc.
+  phase: "Phase 1" # WDS phase where this VTC is used
+
+  # Related files
+  related_documents:
+    - "" # Path to Product Brief, Scenario, etc.
+
+# ==========================================
+# NOTES & RATIONALE
+# ==========================================
+notes: |
+  Creation context:
+  - Why this VTC was created
+  - Key decisions made during workshop
+  - Important insights captured
+
+  Selection rationale (if from Trigger Map):
+  - Why these specific driving forces were chosen
+  - Why this user/goal combination
+  - Any refinements made from original map
+
+  Usage guidance:
+  - How this VTC should inform design
+  - What questions it should answer
+  - Where it applies
+
+  ALPHA FEEDBACK (please document):
+  - Actual workshop duration: [X minutes]
+  - Steps that were unclear: [which steps?]
+  - What was missing: [gaps?]
+  - What worked well: [successes?]
+  - Suggestions: [improvements?]
+
+# ==========================================
+# REFINEMENTS (Optional)
+# Track changes from Trigger Map if applicable
+# ==========================================
+refinements:
+  - type: "" # "added", "modified", "clarified"
+    element: "" # What was changed
+    original: "" # Original from Trigger Map
+    updated: "" # Updated version in this VTC
+    reason: "" # Why the change was made
+
+# ==========================================
+# VALIDATION CHECKLIST
+# ==========================================
+validation:
+  coherence: false # Does this tell a coherent story?
+  actionable: false # Can designers make decisions from this?
+  specific: false # Are driving forces specific enough?
+  realistic: false # Does awareness progression make sense?
+  measurable: false # Is business goal measurable?
+  focused: false # Is this focused (not trying to serve everyone)?
+
+# ==========================================
+# EXAMPLE APPLICATIONS
+# How this VTC informs design decisions
+# ==========================================
+applications:
+  # Examples of how this VTC guides design
+  # Remove this section in actual VTC files
+
+  content_examples:
+    - element: "Hero headline"
+      vtc_reasoning: "Addresses 'fear of missing trends' directly"
+      result: "'Never Miss a Trend: Weekly Insights for Ambitious Stylists'"
+
+    - element: "CTA button"
+      vtc_reasoning: "Aspirational language matching 'wish to be authority'"
+      result: "'Join the Authority Circle' (not just 'Subscribe')"
+
+  design_examples:
+    - element: "Visual style"
+      vtc_reasoning: "User wants to be seen as cutting-edge"
+      result: "Modern, premium aesthetic (not traditional salon look)"
+
+    - element: "Social proof"
+      vtc_reasoning: "Reduces 'fear of appearing outdated'"
+      result: "Testimonials from successful salon owners"
+
+# ==========================================
+# USAGE INSTRUCTIONS
+# ==========================================
+
+# HOW TO USE THIS TEMPLATE:
+#
+# 1. Copy this file to your project location:
+#    - Product Pitch: docs/A-Product-Brief/vtc-primary.yaml
+#    - Scenario: docs/D-UX-Design/[scenario-name]/vtc.yaml
+#
+# 2. Fill in all sections with your VTC data
+#
+# 3. Remove example applications section (it's just for reference)
+#
+# 4. Complete validation checklist - all should be true
+#
+# 5. Use this VTC to inform ALL design decisions for this scope:
+#    - Content creation (what to say, how to say it)
+#    - Interaction design (what actions to enable)
+#    - Visual design (what aesthetic matches user psychology)
+#    - Microcopy (what tone builds confidence)
+#
+# 6. When making design decisions, ask:
+#    "Does this serve the business goal by triggering these driving forces
+#     while moving the user forward in customer awareness?"
+#
+#    If yes → Good design decision
+#    If no → Reconsider
+
+# ==========================================
+# MAINTENANCE
+# ==========================================
+
+# WHEN TO UPDATE VTC:
+# - Business goal changes
+# - Learn new insights about user
+# - Discover additional driving forces
+# - Awareness progression needs adjustment
+# - Solution scope changes
+#
+# VERSION CONTROL:
+# - Keep old versions (vtc-v1.yaml, vtc-v2.yaml)
+# - Document what changed and why
+# - Update related documents (scenarios, pitch, etc.)
+#
+# CONSISTENCY:
+# - If extracted from Trigger Map, periodically check alignment
+# - If Trigger Map updates significantly, review VTC
+# - Multiple VTCs from same map should be consistent in priorities
+

package/src/workflows/shared/vtc-workshop/vtc-workshop-guide.md

@@ -0,0 +1,418 @@
+# Value Trigger Chain Workshop Suite
+
+**Purpose:** Create or extract Value Trigger Chains for strategic design guidance
+
+**Location:** Shared across multiple WDS phases
+
+**Used in:**
+- Phase 1: Product Pitch (simplified VTC for stakeholder communication)
+- Phase 4: Scenario Definition (VTC for each scenario)
+
+---
+
+## ⚠️ Alpha Status
+
+**This workshop suite is in ALPHA.**
+
+**What this means:**
+- Methodology is sound, structure is complete
+- **Not yet validated in real projects**
+- Steps may need refinement based on actual usage
+- Timing estimates may be off
+- Edge cases may emerge
+
+**We need your feedback:**
+- What worked well?
+- What was confusing?
+- What took longer than estimated?
+- What's missing?
+- Where did you get stuck?
+
+**Report issues/feedback:** Add notes to your VTC file or create session log
+
+**This notice will be removed** once validated across 3-5 real projects.
+
+---
+
+## Quick Start
+
+**Run VTC Workshop:**
+
+```
+1. Start here: vtc-workshop-router.md
+2. Answer: "Do you have a Trigger Map?"
+3. Router sends you to appropriate workshop
+4. Complete workshop (10-30 minutes)
+5. Get VTC file ready to use
+```
+
+---
+
+## Workshop Files
+
+### [vtc-workshop-router.md](./vtc-workshop-router.md)
+
+**What:** Entry point that routes to correct workshop  
+**Duration:** 1 minute  
+**Use when:** You need a VTC
+
+**Decision:**
+- Has Trigger Map? → Selection Workshop
+- No Trigger Map? → Creation Workshop
+
+---
+
+### [vtc-creation-workshop.md](./vtc-creation-workshop.md)
+
+**What:** Create VTC from scratch (no Trigger Map)  
+**Duration:** 20-30 minutes  
+**Use when:** Early stage, quick projects, no time for full Trigger Map
+
+**Process:**
+1. Define business goal
+2. Identify solution
+3. Describe user
+4. Identify driving forces (positive + negative)
+5. Position customer awareness
+
+**Output:** Complete VTC
+
+---
+
+### [vtc-selection-workshop.md](./vtc-selection-workshop.md)
+
+**What:** Extract VTC from existing Trigger Map  
+**Duration:** 10-15 minutes  
+**Use when:** Trigger Map exists, want consistency
+
+**Process:**
+1. Load Trigger Map
+2. Select business goal
+3. Select user
+4. Select relevant driving forces (subset)
+5. Define solution
+6. Position customer awareness
+7. Optional refinements
+
+**Output:** VTC extracted from map
+
+---
+
+### [vtc-template.yaml](./vtc-template.yaml)
+
+**What:** Standard format for all VTCs  
+**Use:** Both workshops output this format
+
+**Contains:**
+- Business Goal
+- Solution
+- User description
+- Driving Forces (positive + negative)
+- Customer Awareness (start → end)
+- Metadata and notes
+
+---
+
+## When to Use VTC vs. Trigger Map
+
+### Use VTC (Lightweight) When:
+
+**Time:**
+- < 2 weeks total timeline
+- Need to start NOW
+- Can't dedicate 1-2 days to mapping
+
+**Scope:**
+- 1-3 key flows
+- Single primary user
+- Focused project/prototype
+- Standalone scenario
+
+**Resources:**
+- Small team
+- Limited research budget
+- Founder/solo designer
+
+**Context:**
+- Early product pitch
+- Quick validation
+- MVP/POC
+- Client presentation
+
+**Result:** Sufficient strategic grounding for focused work
+
+---
+
+### Use Trigger Map (Comprehensive) When:
+
+**Time:**
+- > 1 month timeline
+- Can invest 1-2 days upfront
+- Long-term product
+
+**Scope:**
+- Multiple user types
+- Complex product
+- Many scenarios
+- Full platform
+
+**Resources:**
+- Full team
+- Research capacity
+- Stakeholder availability
+
+**Context:**
+- Strategic foundation needed
+- Multiple VTCs will be extracted
+- Prioritization crucial
+- Long shelf life desired
+
+**Result:** Deep strategic foundation, many VTCs derived
+
+---
+
+## VTC in Product Pitch (Phase 1)
+
+### Purpose
+Create ONE simplified VTC for stakeholder communication
+
+### Typical Flow
+```
+Product Brief Workshop
+  ↓
+VTC Workshop (usually Creation - no map yet)
+  ↓
+VTC added to Pitch Document
+  ↓
+Pitch uses VTC to explain:
+  - WHO we're building for
+  - WHAT motivates them
+  - WHY this solution matters
+```
+
+### Example Pitch Structure with VTC
+
+**Slide 1: The Opportunity**
+- Business Goal (from VTC)
+
+**Slide 2: The User**
+- User description (from VTC)
+- Driving Forces (from VTC)
+
+**Slide 3: Our Solution**
+- Solution (from VTC)
+- How it triggers positive forces
+- How it addresses negative forces
+
+**Slide 4: The Journey**
+- Customer Awareness progression (from VTC)
+- What changes for the user
+
+**Result:** Stakeholders understand strategic grounding
+
+---
+
+## VTC in Scenario Definition (Phase 4)
+
+### Purpose
+Assign VTC to each scenario for design guidance
+
+### Typical Flow
+```
+Scenario Identified
+  ↓
+VTC Workshop
+  ├─ If Trigger Map exists → Selection Workshop
+  └─ If no map → Creation Workshop
+  ↓
+VTC assigned to Scenario
+  ↓
+All pages in scenario inherit VTC
+  ↓
+Design decisions reference VTC
+```
+
+### Multiple Scenarios = Multiple VTCs
+
+**Example: User Onboarding Product**
+
+```
+Scenario 1: First Visit (Landing Page)
+VTC-01:
+- Goal: 500 signups
+- User: Curious visitor
+- Forces: Want to understand, fear commitment
+- Awareness: Problem Aware → Product Aware
+
+Scenario 2: Account Setup
+VTC-02:
+- Goal: 80% activation
+- User: New signup
+- Forces: Want quick value, fear complexity
+- Awareness: Product Aware → Most Aware
+
+Scenario 3: Dashboard (First Use)
+VTC-03:
+- Goal: 80% activation
+- User: First-time user
+- Forces: Want to feel capable, fear looking stupid
+- Awareness: Most Aware (maintain and deepen)
+```
+
+**Notice:** Same product, different VTCs based on context
+
+---
+
+## Workshop Tips
+
+### For Agents Running Workshops
+
+**Momentum:**
+- Keep workshop moving (don't get stuck)
+- "We can refine later" if user hesitates
+- Capture first, perfect second
+
+**Validation:**
+- Quick checks at each step
+- "Does this feel right?"
+- Catch issues early
+
+**Examples:**
+- Use examples from guide to illustrate
+- Show good vs bad
+- Make abstract concrete
+
+**Focus:**
+- One VTC at a time
+- One primary user
+- 2-5 driving forces (not 20)
+
+### For Users Creating VTCs
+
+**Don't Overthink:**
+- This is a heuristic, not science
+- Better to have rough VTC than none
+- Can refine as you learn
+
+**Be Specific:**
+- Generic = not useful
+- "Save time" → "Save time doing WHAT?"
+- "Better experience" → "Feel capable doing WHAT?"
+
+**Test It:**
+- After creating VTC, try making a design decision
+- Does VTC guide you?
+- If not, refine VTC
+
+---
+
+## Common Questions
+
+### Q: How many VTCs do I need?
+
+**Product Pitch:** 1 (maybe 2 for complex products)  
+**Scenarios:** 1 per major scenario  
+**Simple product:** 2-3 total  
+**Complex product:** 5-10 total
+
+### Q: Can scenarios share VTCs?
+
+Yes, if they serve same goal, same user, same forces. But often scenarios have slightly different contexts, so separate VTCs maintain clarity.
+
+### Q: What if I have a Trigger Map but it's old?
+
+Run Selection Workshop but be prepared for Refinement step. May discover need to update Trigger Map.
+
+### Q: Can I create VTC now and Trigger Map later?
+
+Absolutely! VTC is lightweight start. As project grows, create Trigger Map and extract more VTCs from it. Original VTC becomes input to Trigger Map.
+
+### Q: How do I know if VTC is good enough?
+
+Ask: "Can I make design decisions from this?"
+- Yes → It's good enough
+- No → Which part is too vague? Refine that
+
+---
+
+## File Outputs
+
+### Product Pitch VTC
+**Location:** `docs/A-Product-Brief/vtc-primary.yaml`
+
+**Used in:**
+- Pitch deck
+- Stakeholder presentations
+- Project kickoff
+- Strategic alignment
+
+### Scenario VTC
+**Location:** `docs/D-UX-Design/[scenario-name]/vtc.yaml`
+
+**Used in:**
+- Scenario specification
+- Page design decisions
+- Content creation
+- Component specifications
+
+### Multiple Scenarios
+```
+docs/D-UX-Design/
+├── 1.1-landing-page/
+│   └── vtc.yaml
+├── 1.2-signup-flow/
+│   └── vtc.yaml
+├── 2.1-dashboard/
+│   └── vtc.yaml
+└── 2.2-settings/
+    └── vtc.yaml
+```
+
+---
+
+## Maintenance
+
+### When VTC Changes
+1. Update YAML file
+2. Increment version (v1 → v2)
+3. Keep old version for reference
+4. Update related documents
+5. If extracted from Trigger Map, consider updating map
+
+### When Trigger Map Changes
+1. Review all VTCs extracted from it
+2. Check if VTCs still align
+3. Update VTCs if needed
+4. Document changes
+
+---
+
+## Success Metrics
+
+**Good VTC when:**
+- ✅ Designer can make decisions without asking "why?"
+- ✅ Content creator knows which driving forces to address
+- ✅ Stakeholders understand strategic reasoning
+- ✅ Team aligned on WHO and WHY
+- ✅ Can evaluate design alternatives objectively
+
+**VTC needs work when:**
+- ❌ Team argues about design opinions (not strategy)
+- ❌ Content feels generic
+- ❌ Can't explain why design choice serves strategy
+- ❌ Driving forces too vague to inform design
+
+---
+
+## Related Resources
+
+- [Value Trigger Chain Guide](../../../docs/method/value-trigger-chain-guide.md) - Complete VTC methodology
+- [Trigger Mapping Guide](../../../docs/method/phase-2-trigger-mapping-guide.md) - When to create full map
+- [Customer Awareness Cycle](../../../docs/models/customer-awareness-cycle.md) - Understanding awareness stages
+- [Product Pitch Process](../../1-project-brief/project-pitch/) - Using VTC in pitches
+- [Scenario Definition](../../4-ux-design/scenario-init/) - Using VTC in scenarios
+
+---
+
+*VTC Workshop Suite - Strategic clarity in 10-30 minutes*
+