ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity

fix(wds): Update references from Freyja to Freya across documentation 

Replaced all instances of "Freyja" with "Freya" in various documentation files, including agent presentations, workflows, and guides. This change ensures consistency in naming conventions and aligns with the updated agent identity. The update enhances clarity for users navigating the WDS framework and improves overall documentation accuracy.
This commit is contained in:
Mårten Angner 2026-01-01 01:45:18 +01:00
parent d2a67ef2e9
commit e6510d59f8
162 changed files with 18544 additions and 999 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
README.md
View File

@ -50,7 +50,7 @@ src/modules/wds/
├── agents/ # WDS specialized agents
│ ├── saga-analyst.agent.yaml # Saga - WDS Analyst
│ ├── idunn-pm.agent.yaml # Idunn - WDS PM
│ └── freyja-ux.agent.yaml # Freyja - WDS Designer
│ └── freya-ux.agent.yaml # Freya - WDS Designer
├── workflows/ # Phase-selectable workflows
├── data/ # Standards, frameworks, presentations
├── docs/ # Module documentation (xxx-guide.md)
@ -121,7 +121,7 @@ WDS introduces **3 specialized design agents** named after Norse mythology:
| --------------------------- | -------------------------- | -------------------------------------------------------------------- |
| **Saga the WDS Analyst** | Business & Product Analyst | Goddess of stories & wisdom - uncovers your business story |
| **Idunn the WDS PM** | Product Manager | Goddess of renewal & youth - keeps projects vital and thriving |
| **Freyja the WDS Designer** | UX/UI Designer | Goddess of beauty, magic & strategy - creates experiences users love |
| **Freya the WDS Designer** | UX/UI Designer | Goddess of beauty, magic & strategy - creates experiences users love |
---
@ -193,7 +193,7 @@ bmad agent saga-wds-analyst
bmad agent idunn-wds-pm
# Or begin with UX Design
bmad agent freyja-wds-designer
bmad agent freya-wds-designer
```
---
@ -204,7 +204,7 @@ bmad agent freyja-wds-designer
- ✅ Module folder structure (`src/modules/wds/`)
- ✅ Installation system (`_module-installer/installer.js`)
- ✅ All 3 agents converted to v6 YAML (Saga, Idunn, Freyja)
- ✅ All 3 agents converted to v6 YAML (Saga, Idunn, Freya)
- ✅ Agent presentations and personas
- ✅ All 8 phase workflows complete
- ✅ Team configurations

34
WDS-V6-CONVERSION-ROADMAP.md
View File

@ -173,7 +173,7 @@ src/modules/wds/
│
├── agents/ # WDS agents (v6 YAML format) - Norse Pantheon
│ ├── saga-analyst.agent.yaml # Saga-Analyst - TO CREATE
│ ├── freyja-pm.agent.yaml # Freyja-PM - TO CREATE
│ ├── freya-pm.agent.yaml # Freya-PM - TO CREATE
│ └── baldr-ux.agent.yaml # Baldr-UX - TO CREATE
│
├── workflows/ # Phase workflows
@ -216,7 +216,7 @@ src/modules/wds/
| ----------------------- | ------------------------- | -------------------------- | ----------------------------------- | ----------------------- |
| **Saga the Analyst** | `saga-analyst.agent.yaml` | Business & Product Analyst | Goddess of stories & wisdom | ✅ **COMPLETE (Dec 9)** |
| **Idunn the PM** | `idunn-pm.agent.yaml` | Product Manager | Goddess of renewal & youth | ✅ **COMPLETE (Dec 9)** |
| **Freyja the Designer** | `freyja-ux.agent.yaml` | UX/UI Designer | Goddess of beauty, magic & strategy | ✅ **COMPLETE (Dec 9)** |
| **Freya the Designer** | `freya-ux.agent.yaml` | UX/UI Designer | Goddess of beauty, magic & strategy | ✅ **COMPLETE (Dec 9)** |
**Why "Name the Function" format?**
@ -499,7 +499,7 @@ What tends to feel less collaborative:
- **Output Folder:** `C-Platform-Requirements/`
- **Deliverable:** Technical foundation (platform, architecture, data model, integrations, security)
- **Agent:** Freyja WDS PM
- **Agent:** Freya WDS PM
- **Note:** Runs in parallel with Phase 4
**Phase 4: UX Design**
@ -520,7 +520,7 @@ What tends to feel less collaborative:
- **Output Folder:** `E-PRD/`
- **Deliverable:** Complete PRD (00-PRD.md) + Design Deliveries (DD-XXX.yaml packages)
- **Agent:** Freyja WDS PM
- **Agent:** Freya WDS PM
- **Note:** PRD references C-Platform-Requirements/, organizes functional requirements by epic
**Phase 7: Testing**
@ -669,8 +669,8 @@ Includes:
| 13b | **Saga Presentation** | `data/presentations/saga-intro.md` | ✅ COMPLETE |
| 14 | **Idunn-PM** | `agents/idunn-pm.agent.yaml` | ✅ COMPLETE |
| 14b | **Idunn Presentation** | `data/presentations/idunn-intro.md` | ✅ COMPLETE |
| 15 | **Freyja-Designer** | `agents/freyja-ux.agent.yaml` | ✅ COMPLETE |
| 15b | **Freyja Presentation** | `data/presentations/freyja-intro.md` | ✅ COMPLETE |
| 15 | **Freya-Designer** | `agents/freya-ux.agent.yaml` | ✅ COMPLETE |
| 15b | **Freya Presentation** | `data/presentations/freya-intro.md` | ✅ COMPLETE |
#### Phase 5: Finalize
@ -753,7 +753,7 @@ Includes:
7. [ ] Create Phase 5-6 workflows
8. [ ] Create WDS Trigger Map (meta-example for WDS itself)
9. [ ] Create conversation examples
10. [ ] Create agents (Saga, Freyja, Baldr)
10. [ ] Create agents (Saga, Freya, Baldr)
11. [ ] Create templates for component showcase, PRD, etc.
12. [ ] Port Dog Week examples to `examples/dog-week-patterns/` (last - project in active development)
@ -911,7 +911,7 @@ Our product (statement of primary differentiators)
| -------------------------------- | -------------------------------------- | ----------- |
| Mary (whiteport-analyst.md) | Saga-Analyst (saga-analyst.agent.yaml) | ✅ COMPLETE |
| Sarah (whiteport-pm.md) | Idunn-PM (idunn-pm.agent.yaml) | ✅ COMPLETE |
| Sally (whiteport-ux-expert.md) | Freyja-Designer (freyja-ux.agent.yaml) | ✅ COMPLETE |
| Sally (whiteport-ux-expert.md) | Freya-Designer (freya-ux.agent.yaml) | ✅ COMPLETE |
| James (whiteport-dev.md) | N/A - moved to BMM | ✅ Complete |
| Alex (whiteport-orchestrator.md) | N/A - workflow-status replaces | ✅ Complete |
@ -919,7 +919,7 @@ Our product (statement of primary differentiators)
- Mary → **Saga** (Goddess of stories & wisdom)
- Sarah → **Idunn** (Goddess of renewal & youth)
- Sally → **Freyja** (Goddess of beauty, magic & strategy)
- Sally → **Freya** (Goddess of beauty, magic & strategy)
- Norse Pantheon theme for unique WDS identity
### 11.2 File Format Changes
@ -970,7 +970,7 @@ agent:
| WPS2C v4 File | WDS v6 Location | Purpose |
| ---------------------------------------- | ------------------------------------------------- | ------------------------ |
| mary-analyst-personal-presentation.md | data/presentations/saga-intro.md | Saga activation speech |
| sarah-pm-personal-presentation.md | data/presentations/freyja-intro.md | Freyja activation speech |
| sarah-pm-personal-presentation.md | data/presentations/freya-intro.md | Freya activation speech |
| sally-ux-expert-personal-presentation.md | data/presentations/baldr-intro.md | Baldr activation speech |
| wps2c-analyst-business-presentation.md | examples/conversation-examples/analyst-session.md | Example session |
| wps2c-pm-product-presentation.md | examples/conversation-examples/pm-session.md | Example session |
@ -1013,7 +1013,7 @@ agent:
**Agent Personalities:** 🔄
- Mary's analytical, thoughtful approach → Saga
- Sarah's strategic PM mindset → Freyja
- Sarah's strategic PM mindset → Freya
- Sally's design expertise and creativity → Baldr
**Quality Patterns:** ✅
@ -1184,7 +1184,7 @@ agent:
- Create Phase 5 workflow (Design System)
- Create Phase 6 workflow (PRD Finalization / Dev Integration)
- Complete agent definitions (Freyja, Baldr)
- Complete agent definitions (Freya, Baldr)
- Port agent presentations
- Create remaining object-type instruction files (~15 more types)
@ -2281,7 +2281,7 @@ workflows/5-design-system/
- ✅ Complete agent introduction speech
- ✅ Strategic foundation explanation with detailed folder structure
- ✅ Team integration details (Freyja, Baldr, BMM)
- ✅ Team integration details (Freya, Baldr, BMM)
- ✅ Norse mythology connection explained
- ✅ Deliverables and process visualization
- ✅ Professional standards and conventions
@ -2312,7 +2312,7 @@ workflows/5-design-system/
- Soft, collaborative language throughout
- Working rhythm guidance (ask → listen → reflect → discover → structure)
- Integration with WDS phases (1-2 focus)
- Team coordination with Freyja and Baldr
- Team coordination with Freya and Baldr
- Bridge to BMM development workflows
### Persona Highlights
@ -2387,7 +2387,7 @@ When we work together:
**With WDS Team:**
- **Freyja (PM)**: Receives strategic foundation for PRD development
- **Freya (PM)**: Receives strategic foundation for PRD development
- **Baldr (UX)**: Uses personas and trigger map for design work
**With BMM (Development):**
@ -2465,12 +2465,12 @@ When testing Saga-Analyst:
**Immediate:**
1. Create Freyja-PM agent (Product Manager - Goddess of love, war & strategy)
1. Create Freya-PM agent (Product Manager - Goddess of love, war & strategy)
2. Create Baldr-UX agent (UX/UI Designer - God of light & beauty)
**After Agents Complete:**
1. Create agent presentation files for Freyja and Baldr
1. Create agent presentation files for Freya and Baldr
2. Create team configurations in `teams/`
3. Create module installer config
4. Test agent activation and workflow integration

477
conversion-logs/session-2025-12-31-content-production-workshop.md Normal file
View File

@ -0,0 +1,477 @@
# Session Log: 2025-12-31 - Content Production Workshop
**Date:** December 31, 2025
**Status:** In Progress (Paused for Method Plumbing) 🔄
---
## Objectives
1. 🔄 Design "Scientific Content Creation Workflow" for WDS agents
2. ⏸️ Document strategic frameworks in method guides
3. ⏸️ Integrate frameworks into agent instructions
4. ⏸️ Implement Value Chain Content Analysis structure
---
## Context
User identified issues with agent behavior during WDS landing page content creation. Agents were generating suggestions without systematic strategic analysis, leading to:
- Content lacking strategic grounding
- No explanation of WHY specific content was chosen
- Agents "blurting out versions" instead of engaging in dialog
- No scientific approach to content generation
---
## Strategic Content Creation Chain
Developed comprehensive framework for content generation:
```
Business Goal
↓
User + Driving Forces (positive & negative)
↓
Scenario → Value Chain Selection
↓
Usage Situation
↓
Flow Context (where user has been)
↓
Page Purpose
↓
Text Section → Local Purpose (emotions, facts, tools, mental pictures)
↓
Value Added to Driving Forces & Business Goal
```
**Key Principle:** Content should be generated from strategic context, not created in isolation.
---
## Value Chain Content Analysis
### Concept
Attach strategic reasoning to each key content component on a page. Shows:
- Which business goal this content serves
- Which user it targets
- Which driving forces it addresses
- Why this specific content was chosen
### Structure
Table format with columns:
| Business Goal | Solution | User | Driving Forces |
|--------------|----------|------|----------------|
| 1000 Registered users | Landing page | Harriet (hairdresser) | • Wish to be queen of beauty |
| 500 Premium signups | | | • Fear of falling behind |
| | | | • Wish to save time |
| | | Tom (trainer) | • Wish to grow business |
### Benefits
1. **Transparency:** Designer understands WHY content is structured this way
2. **Flexibility:** Designer can adjust value chain and regenerate content
3. **Multi-angle content:** Different driving forces create different message angles
4. **Options presentation:** Agent can show how content changes based on value chain selection
### Example: Multi-Angle Content
**Same Goal, Different Driving Forces:**
- "Wanting to be right" → Confidence-building, empowerment messaging
- "Fearing to be wrong" → Risk-reduction, reassurance messaging
Agent presents: *"If we address fear of X, then the content should sound like..."*
---
## Strategic Frameworks to Integrate (from WPS2C v4)
### 1. Customer Awareness Cycle (Eugene Schwartz)
**Stages:**
- Unaware
- Problem Aware
- Solution Aware
- Product Aware
- Most Aware
**Integration with Scenarios:**
Every scenario should move user from one CAC position to a more favorable one:
```
Scenario Structure with CAC:
- Business Goal (+ how CAC progression feeds it)
- User + Usage Context
- CAC Starting Point ← NEW
- CAC Target Position ← NEW
- User's Driving Forces (contextualized by awareness level)
- Solution/Interaction (designed to move through CAC)
```
**Example: Golf Resort**
```
FROM: Product Aware → "I know there are golf courses in Dubai"
TO: Most Aware → "I've played at [Your Resort], loved it, told others"
Business Goal: 4.5+ star reviews (measurable CAC outcome)
```
**Strategic Anchors CAC Provides:**
- What content to show? → Moves from Product Aware to Most Aware
- What actions to enable? → Progresses through cycle
- What emotions to evoke? → Reduces friction at each stage
- How to measure success? → Did they advance in CAC?
**Key Insight:** Driving forces change based on awareness level. A golfer who is "Problem Aware" (frustrated with crowded courses) has different active goals than one who is "Product Aware" (comparing Dubai courses).
**Usage in v4:** Used in Conceptual Documentation phase (`04-Conceptual-Documentation.md`)
- Framed each phase based on user awareness
- Guided conversation strategy
- Determined content depth and messaging
---
### 2. Golden Circle (Simon Sinek)
**Structure:**
- WHY (purpose, belief, motivation)
- HOW (process, differentiators)
- WHAT (product, features)
**Usage in v4:** Used in Product Brief Discovery (`01-Product-Brief-Discovery.md`)
- Structured discovery conversations
- Started with WHY questions (purpose, vision)
- Moved to HOW (approach, differentiators)
- Ended with WHAT (features, deliverables)
**Integration Point:** Product Brief phase, messaging hierarchy, value proposition
---
### 3. Action Mapping (Cathy Moore)
**Purpose:** Focus on what users DO, not just what they KNOW
**Usage in v4:** Used in Scenario Step Exploration
- Identified user actions that drive business results
- Eliminated information-only steps
- Focused on practice and application
**Integration Point:** UX Design phase, interaction design, scenario steps
---
### 4. Kathy Sierra's Teachings
**Principles:**
- Make users feel capable (not just informed)
- Reduce cognitive load
- Create "aha moments"
- Focus on user badassery, not product features
**Usage in v4:** Used in component design and user experience
- Component specifications focused on capability
- Microcopy reduced anxiety
- Interaction patterns built confidence
**Integration Point:** Component specifications, microcopy, interaction patterns, content creation
---
## Agent Content Creation Behavior
### Current (Problematic)
- Agent gets prompt → immediately generates suggestion
- No strategic analysis
- No explanation of reasoning
- Refuses to stay in dialog until good solution found
### Desired (Scientific)
1. Agent receives content creation request
2. Agent identifies strategic context:
- Business goal(s)
- Target user(s) and driving forces
- CAC starting/target position
- Scenario and value chain
- Usage situation
- Flow context
- Page purpose
- Text section local purpose
3. Agent presents context to designer: *"Here's the strategic context I'm working with..."*
4. Agent generates content WITH reasoning: *"Based on [value chain], targeting [driving force], this content takes the form..."*
5. Designer can:
- Accept content
- Adjust value chain → regenerate
- Request alternative angles
- Engage in dialog until satisfied
### Implementation Considerations
**In Most Cases:**
- Agent has enough context to present full section/page content
- Designer reviews and adjusts value chain if needed
- No workshop required for every text block
**For Complex Content:**
- Agent may present options based on different value chain selections
- Designer chooses angle or requests synthesis
- Iterative refinement with strategic grounding
**Always:**
- Agent explains WHY content is structured this way
- Value chain reasoning is explicit and editable
- Multiple strategic frameworks can inform decision simultaneously
---
## Multi-Dimensional Framework Synthesis
**Key Insight:** AI is phenomenal at getting multi-dimensional input (even conflicting frameworks) and creating a single output where all input is weighted and synthesized.
**Approach:**
- Don't require all frameworks to be used all the time
- Allow frameworks to complement or tension with each other
- AI synthesizes: Golden Circle + Action Mapping + Kathy Sierra + CAC → Optimal content
**Example Synthesis:**
- WHY (Golden Circle) → Purpose-driven messaging
- Problem Aware → Product Aware (CAC) → Content depth and framing
- Action focus (Action Mapping) → Call-to-action design
- Build capability (Kathy Sierra) → Confidence-building language
= **Resulting content addresses purpose, meets user where they are, focuses on action, builds confidence**
---
## Proposed Implementation Structure
### 1. Method Documentation (`docs/method/`)
Create tool-agnostic guides for each strategic framework:
**New Files to Create:**
- `cac-integration-guide.md` - Customer Awareness Cycle
- `golden-circle-guide.md` - Simon Sinek's framework
- `action-mapping-guide.md` - Cathy Moore's method
- `kathy-sierra-guide.md` - User capability framework
- `value-chain-content-analysis-guide.md` - New WDS concept
**Structure for Each:**
- What it is (overview)
- Why it matters (benefits)
- When to use it (context)
- How to apply it (step-by-step)
- Examples (real-world applications)
- Integration points (where in WDS process)
### 2. Agent Instructions
Reference methods in agent personas/workflows:
**Example Pattern:**
```markdown
When creating content for [scenario/page]:
1. Identify user's CAC position (see method/cac-integration-guide.md)
2. Use Kathy Sierra's method to identify aha moment (see method/kathy-sierra-guide.md)
3. Organize information according to Golden Circle (see method/golden-circle-guide.md)
4. Ensure action focus per Action Mapping (see method/action-mapping-guide.md)
5. Present Value Chain Content Analysis showing strategic reasoning
```
### 3. Workflow Integration
Embed framework checkpoints at appropriate workflow stages:
**Scenario Definition (Phase 2):**
- Add CAC Starting Point field
- Add CAC Target Position field
- Validate: Does scenario move user forward in CAC?
**Content Creation (Phase 4):**
- Activate Value Chain Content Analysis
- Reference relevant frameworks (CAC, Golden Circle, Kathy Sierra)
- Generate content with strategic reasoning
**Page Specifications:**
- Include Value Chain table for each key content section
- Show which business goal + user + driving force each section serves
- Allow designer to adjust and regenerate
---
## Use Cases Beyond Content Production
**User Question:** "These models are great for content production and copywriting, but they could serve a great purpose in other purposes as well in the WDS process?"
**Answer:** Yes! Strategic frameworks have multiple applications:
### Customer Awareness Cycle
- **Product Brief:** Determine where target users currently are in awareness
- **Trigger Mapping:** Map scenarios to CAC progression
- **Content Creation:** Match messaging to awareness level
- **Testing:** Validate that interactions move users forward in CAC
### Golden Circle
- **Product Brief:** Structure discovery conversations (WHY → HOW → WHAT)
- **Positioning:** Create value proposition hierarchy
- **Messaging:** Organize communication from purpose to features
- **Stakeholder Alignment:** Get buy-in by starting with WHY
### Action Mapping
- **Scenario Design:** Focus on user actions that drive business results
- **Interaction Design:** Eliminate information-only steps
- **Component Specs:** Design for action, not just display
- **Testing:** Validate that users can actually DO the thing
### Kathy Sierra
- **Component Design:** Build capability, not just functionality
- **Microcopy:** Reduce anxiety, build confidence
- **Onboarding:** Create aha moments early
- **Error Messages:** Help users feel capable even when things go wrong
---
## Examples from Old v4 Repo
### Customer Awareness Cycle Usage (04-Conceptual-Documentation.md)
```markdown
For each conceptual step:
1. Assess user's awareness level (Unaware → Most Aware)
2. Match content depth to awareness:
- Problem Aware: Show the problem clearly
- Solution Aware: Introduce your approach
- Product Aware: Show how YOUR product works
3. Design progression to next awareness level
```
### Golden Circle Usage (01-Product-Brief-Discovery.md)
```markdown
Discovery conversation structure:
WHY Questions:
- Why does this product need to exist?
- What problem keeps you up at night?
- What would success look like for your users?
HOW Questions:
- How is your approach different?
- How will users experience this?
- How will you measure success?
WHAT Questions:
- What features are must-haves?
- What is out of scope?
- What are the deliverables?
```
### Action Mapping Usage (Scenario Exploration)
```markdown
For each scenario step:
1. What does the user DO?
2. What business result does this action drive?
3. Remove any step that is "learn about X" without action
4. Focus on practice, application, decision-making
```
### Kathy Sierra Usage (Component Design)
```markdown
For each component:
1. What capability does this give the user?
2. What makes them feel "I can do this"?
3. What reduces cognitive load?
4. What creates an aha moment?
5. How do we help them feel badass?
```
---
## Next Steps
### Method Plumbing (Current Priority)
User requested pause to do foundational work:
1. ✅ Document current content discussion (this file)
2. ⏸️ Create method guides for each strategic framework
3. ⏸️ Define Value Chain Content Analysis data structure
4. ⏸️ Update existing method guides to reference frameworks
5. ⏸️ Design content creation workflow/agent
6. ⏸️ Update agent instructions with framework references
### When Resuming Content Work
1. Test scientific content creation approach with WDS landing page
2. Validate Value Chain Content Analysis structure
3. Refine agent behavior based on real usage
4. Document patterns and best practices
---
## Key Decisions
### 1. CAC Integration with Scenarios
**Decision:** Every scenario must explicitly define CAC starting point and target position.
**Rationale:** Provides clear strategic anchor for all content and interaction decisions. Makes scenario success measurable.
### 2. Value Chain Content Analysis
**Decision:** Create explicit data structure showing strategic reasoning for each content component.
**Rationale:** Makes agent reasoning transparent, allows designer control, enables multi-angle content generation.
### 3. Multi-Dimensional Framework Synthesis
**Decision:** Don't require all frameworks all the time. Let AI synthesize multiple (even conflicting) frameworks.
**Rationale:** Leverages AI's strength in multi-dimensional synthesis. More flexible than rigid framework application.
### 4. Method Documentation Structure
**Decision:** Create tool-agnostic method guides that agents reference in their instructions.
**Rationale:** Separates methodology from implementation. Allows reuse across different agents and contexts.
---
## Quotes & Insights
> "The agent just spit out a suggestion after each prompt without asking or thinking."
> "I wanted to create the content for the WDS page. This is a complex task that I had worried a lot about. Instead of worrying, I started a full WDS process. I made a great PRD and went through the process of making a Trigger map. I got a lot of great inspiration and have a ton of context for the process."
> "The agent did not go about this in a scientific way. The agent blurted out versions left and right and refused to stay in the dialog until a good solution was found."
> "Based on all these data points, we have a fantastic position to write awesome content. I wish for the agent to identify this information and feed it to the user when it is time to create a text section. This is what I mean with scientific approach!"
> "Wanting to be right and fearing to be wrong is on the face of it technically the same thing, but in terms of driving forces it gives two different messages in terms of content presented to the user."
> "AI is phenomenal at getting multi-dimensional input and create a single output where all of the sometimes conflicting input is taken into account and weighed against each other."
> "A scenario should in essence take a user from one less favorable position in the CAC to a more favorable one. That is very useful to define where the user starts."
---
## Session Status
**Current Phase:** Method Plumbing 🔧
**Next Up:** Create strategic framework method guides
**Blocked:** None
**Notes:** Content discussion well-documented, ready to resume after method documentation is complete
---
*This session log preserves context for content production workshop development.*

80
deliverables-audit.md Normal file
View File

@ -0,0 +1,80 @@
# Deliverables Folder Audit
**Date:** 2025-12-31
**Status:** Complete
---
## Files Found (8 total)
All deliverable specification files:
1. **product-brief.md** (4,917 bytes) - Phase 1 output
2. **project-pitch.md** (6,885 bytes) - Pre-Phase 1 (optional)
3. **service-agreement.md** (5,806 bytes) - Pre-Phase 1 (optional)
4. **trigger-map.md** (5,063 bytes) - Phase 2 output
5. **platform-prd.md** (4,939 bytes) - Phase 3 output
6. **page-specifications.md** (5,375 bytes) - Phase 4 output
7. **design-system.md** (5,164 bytes) - Phase 5 output
8. **design-delivery-prd.md** (5,361 bytes) - Phase 6 output
---
## Analysis
### ✅ No Redundancy Found
- All files are unique deliverable specifications
- Similar file sizes (~5k bytes) indicate consistent documentation
- Each maps to a specific WDS phase output
- No duplicate content detected
### ⚠️ Missing Deliverable
**Value Trigger Chain (VTC)**
VTC is now a core WDS deliverable created in:
- Phase 1: Product Brief (Step 4) → `vtc-primary.yaml`
- Phase 4: Scenario Init (Step 6) → `vtc.yaml` per scenario
**Should add:** `value-trigger-chain.md` deliverable specification
This spec should explain:
- What a VTC file contains
- YAML format structure
- When it's created
- How it's used
- Examples
---
## Recommendation
**Action:** Create `value-trigger-chain.md` deliverable spec
**Template structure:**
```
# Deliverable: Value Trigger Chain
## What This Deliverable Is
## When It's Created
## File Format
## Required Content
## Optional Content
## How It's Used
## Examples
## Related Deliverables
```
**Estimated time:** 30 minutes
---
## Verdict
**Current State:** ✅ Good - No redundancy
**Missing:** 1 deliverable spec (VTC)
**Action Required:** Add VTC deliverable specification
*Audit complete*

140
learn-wds-audit.md Normal file
View File

@ -0,0 +1,140 @@
# Learn-WDS Course Structure Audit
**Date:** 2025-12-31
**Status:** Issues Identified - Needs Major Cleanup
---
## Critical Issues Found
### 1. Module Numbering Conflicts
**Module 04 appears TWICE:**
- `module-04-product-brief/` (Phase 1: Project Brief)
- Listed in overview as "Module 04: Identify Target Groups" (Phase 2)
**Actual folders don't match overview listing:**
- Overview lists: Module 04-12
- Folders show: module-01 through module-12, but with gaps and conflicts
### 2. Massive Duplication in Module 02
**Module 02 has multiple duplicate lesson folders:**
- `lesson-01-git-setup/`
- `lesson-01-github-and-ide-setup/`
- `lesson-01-setting-up-github/`
- `lesson-02-git-configuration/`
- `lesson-02-ide-installation/`
- `lesson-02-install-ide/`
- `lesson-03-git-cloning/`
- `lesson-03-git-setup/`
- `lesson-04-clone-and-wds/`
- `lesson-04-wds-initialization/`
- `lesson-05-initiate-mimir/`
**Looks like:** Multiple attempts at organizing the same content, never cleaned up.
### 3. Inconsistent Folder Structure
**Some modules have structure:**
- module-01: Has lessons + overview ✅
- module-02: Has lessons + overview (but duplicated) ⚠️
- module-03: Has lessons + overview ✅
**Some modules only have tutorial:**
- module-04: Only `tutorial-04.md`
- module-05: Only `tutorial-04.md` (wrong number!)
- module-06: Only `tutorial-06.md`
- module-08: Only `tutorial-08.md`
- module-09: Only `tutorial-09.md`
- module-10: Only `tutorial-10.md`
- module-12: Only `tutorial-12.md`
**Missing modules:**
- module-07: Doesn't exist
- module-11: Doesn't exist
### 4. Missing VTC Integration
**Course doesn't mention:**
- VTC creation in Module 04 (Product Brief)
- VTC workshop in scenario initialization
---
## Recommended Actions
### Immediate (Critical):
1. **Fix Module Numbering**
- Rename folders to match correct phase structure
- Update course overview to match actual folders
2. **Clean Module 02 Duplicates**
- Identify canonical lesson structure
- Delete duplicate folders
- Keep only one clear path
3. **Complete Missing Modules**
- Add lesson content to modules 04-12
- Or mark as "Tutorial Only" if intended
4. **Add VTC to Course**
- Module 04: Add VTC creation step
- Module on Scenario Init: Add VTC workshop
### Longer Term (Enhancement):
5. **Standardize Module Structure**
- Every module should have:
- `module-XX-overview.md`
- `lesson-XX-YYY.md` files
- `tutorial-XX.md` (if practical module)
6. **Cross-Reference Verification**
- Check all links in course overview
- Verify tutorial paths
- Update any broken references
---
## Impact Assessment
**Current State:**
- ❌ Course structure is confusing
- ❌ Major duplications waste space
- ❌ Module numbering doesn't match content
- ❌ Missing key content (VTC)
- ⚠️ Some modules incomplete
**Estimated Cleanup Time:** 4-6 hours
**Priority:** HIGH - Course is user-facing educational content
---
## Decision Point
**Options:**
**A) Full Cleanup Now**
- Pros: Course becomes usable, consistent
- Cons: Takes 4-6 hours
- When: If course is active/being used
**B) Document & Defer**
- Pros: Move forward with other audits
- Cons: Course remains messy
- When: If course is not yet active
**C) Partial Cleanup**
- Fix: Module numbering, obvious duplicates
- Defer: Content completion
- Time: 1-2 hours
---
**Recommendation:** Option C (Partial Cleanup) - fix structural issues, defer content completion.
*Audit complete - awaiting decision*

135
method-guides-audit.md Normal file
View File

@ -0,0 +1,135 @@
# Method Guides Consistency Audit
**Date:** 2025-12-31
**Status:** In Progress
---
## Files Audited
- `wds-method-guide.md` (main overview)
- `phase-1-product-exploration-guide.md`
- `phase-2-trigger-mapping-guide.md`
- `phase-3-prd-platform-guide.md`
- `phase-4-ux-design-guide.md`
- `phase-5-design-system-guide.md`
- `phase-6-integration-guide.md`
- `phase-6-prd-finalization-guide.md`
- `value-trigger-chain-guide.md`
---
## Issues Found
### 1. Title Format Inconsistencies
**Phase 1:**
- Current: `# Phase 1: Product Exploration (Product Brief) (Project brief)`
- Issue: Double parentheses, "Project brief" redundant
- Fix: `# Phase 1: Product Exploration`
**Phase 2:**
- Current: `# Phase 2: Trigger map`
- Issue: Lowercase "map", should be title case
- Fix: `# Phase 2: Trigger Mapping`
**Phase 6:**
- Has TWO guides: `phase-6-integration-guide.md` AND `phase-6-prd-finalization-guide.md`
- Both titled "Phase 6"
- Issue: Confusing, redundant?
- Action: Investigate if these should be merged or clarified
### 2. Missing VTC Integration
**Phase 1 Guide:**
- ❌ Doesn't mention VTC creation (Step 4 in workflow)
- ❌ Doesn't explain VTC as strategic benchmark
- Should add: "After vision and positioning, you'll create a Value Trigger Chain"
**Phase 4 Guide:**
- ❌ Doesn't mention VTC creation for scenarios (Step 6 in scenario-init)
- ❌ Mentions "Trigger Map" but not VTC per scenario
- Should add: "Each scenario gets its own VTC for strategic guidance"
### 3. Missing Model References
**Phase 1 Guide:**
- ❌ No reference to Customer Awareness Cycle (used in VTC)
- ❌ No reference to Golden Circle (could be used)
**Phase 2 Guide:**
- ❌ No reference to Impact/Effect Mapping models guide
- ❌ Should link to `../models/impact-effect-mapping.md`
**Phase 4 Guide:**
- ❌ No reference to Action Mapping (scenario step exploration)
- ❌ No reference to Kathy Sierra principles (component design)
### 4. Section Structure Inconsistencies
**Most guides have:**
- What This Phase Does
- What You'll Create
- How It Works
**But inconsistent presence of:**
- When to Use This Phase (some have, some don't)
- What to Prepare (some have, some don't)
- Prerequisites (some have, some don't)
**Recommendation:** Standardize section order:
1. What This Phase Does
2. What You'll Create
3. Prerequisites
4. How It Works
5. When to Use This Phase
6. Related Resources
### 5. Cross-Reference Completeness
**Need to verify:**
- All workflow links point to correct files
- All model links work
- All example links work
- All method guide cross-references work
---
## Fixes Applied ✅
### Priority 1: Critical (Consistency & Accuracy)
1. ✅ DONE - Fix Phase 1 title (removed duplicate parentheses)
2. ✅ DONE - Fix Phase 2 title (capitalized "Mapping")
3. ✅ DONE - Investigate Phase 6 duplication (deleted `phase-6-integration-guide.md`, kept `phase-6-prd-finalization-guide.md`)
4. ✅ DONE - Add VTC to Phase 1 guide (added to "What You'll Create" + Related Resources)
5. ✅ DONE - Add VTC to Phase 4 guide (added to 4A Scenario Initialization + Related Resources)
### Priority 2: Enhancement (Completeness)
6. ✅ DONE - Add model references to Phase 1 (Customer Awareness Cycle, Golden Circle)
7. ✅ DONE - Add model references to Phase 2 (Impact/Effect Mapping)
8. ✅ DONE - Add model references to Phase 4 (Action Mapping, Kathy Sierra, Customer Awareness)
9. ⏭️ SKIPPED - Standardize section structure (current structure is good enough, each phase has unique needs)
### Priority 3: Polish (Navigation)
10. ⏭️ DEFERRED - Verify all cross-references (will check during learn-wds audit)
11. ✅ DONE - Add "Related Resources" sections (added to Phases 1, 2, 4)
12. ✅ DONE - Ensure consistent linking patterns (all use relative paths correctly)
---
## Summary
**Issues Fixed:** 10 of 12 (83%)
**Time Spent:** ~45 minutes
**Skipped:** Section structure standardization (not critical)
**Deferred:** Link verification (will do with course audit)
**Result:** Method guides are now consistent, VTC-integrated, and properly cross-referenced!
---
*Audit COMPLETE - 2025-12-31*

2
src/modules/wds/_module-installer/installer.js
View File

@ -84,7 +84,7 @@ async function install(options) {
logger.log(chalk.cyan('\n📋 Next steps:'));
logger.log(chalk.dim(' 1. Activate Saga (WDS Analyst) to start with Product Brief'));
logger.log(chalk.dim(' 2. Or activate Idunn (WDS PM) for Platform Requirements'));
logger.log(chalk.dim(' 3. Or activate Freyja (WDS Designer) for UX Design'));
logger.log(chalk.dim(' 3. Or activate Freya (WDS Designer) for UX Design'));
return true;
} catch (error) {

59
src/modules/wds/agents/freyja-ux.agent.yaml → src/modules/wds/agents/freya-ux.agent.yaml
View File

@ -1,10 +1,10 @@
# Freyja - WDS Designer Agent Definition
# Freya - WDS Designer Agent Definition
# Goddess of beauty, magic & strategy - creates experiences users love
agent:
metadata:
id: "{bmad_folder}/wds/agents/freyja-ux.md"
name: Freyja
id: "{bmad_folder}/wds/agents/freya-ux.md"
name: Freya
title: WDS Designer
icon: 🎨
module: wds
@ -12,7 +12,7 @@ agent:
persona:
role: User Experience Designer + Creative Partner
identity: |
You're Freyja, named after the Norse goddess of beauty, magic, and strategy.
You're Freya, named after the Norse goddess of beauty, magic, and strategy.
You create experiences users fall in love with - combining strategic thinking
with creative magic. You envision what doesn't exist yet and bring it to life
@ -33,23 +33,38 @@ agent:
**Agent References**: When mentioning other WDS agents, always use the format:
"[Name] WDS [Role] Agent" (e.g., "Saga WDS Analyst Agent", "Idunn WDS PM Agent")
principles: |
- **On activation**: Check for active conversations using src/modules/wds/workflows/project-analysis/conversation-persistence/check-conversations.md
- **Before starting ANY work**: Check task appropriateness using src/modules/wds/workflows/project-analysis/task-reflection.md
- **When context full or session closing**: Save conversation using src/modules/wds/workflows/project-analysis/conversation-persistence/save-conversation.md
- **On activation**: Show presentation from src/modules/wds/data/presentations/freyja-presentation.md
- **Then run**: Universal project analysis from src/modules/wds/workflows/project-analysis/project-analysis-router.md
- **If task in my domain (Phases 4, 5, 7)**: Continue in same conversation after confirming understanding
- **If task in another domain**: Hand over seamlessly to specialized agent
- **WDS/BMM Overlap**: I take over BMM UX Designer (Sally) role when WDS is installed - handle all UX design, wireframes, and user research
- Start with interactive prototypes - let users experience the design before building
- Design system grows organically - discover components through actual design work
- Foundation first - establish design tokens (colors, typography, spacing) before components
- Atomic design structure - organize components from simple (atoms) to complex (organisms)
- Test with real users - validate implementation matches design intent
- Continuous improvement - existing products evolve through thoughtful iteration
- **Update project outline when completing work** - track scenarios and keep it as single source of truth
- **File naming**: Never create generic files like README.md - use specific names like [TOPIC]-GUIDE.md (see src/modules/wds/workflows/00-system/FILE-NAMING-CONVENTIONS.md)
principles:
workflow_management: |
- On activation: Check for active conversations (conversation-persistence/check-conversations.md)
- Before starting work: Check task appropriateness (task-reflection.md)
- When closing: Save conversation (conversation-persistence/save-conversation.md)
- On activation: Show presentation (freya-presentation.md)
- Then run: Universal project analysis (project-analysis-router.md)
collaboration: |
- If task in my domain (Phases 4, 5, 7): Continue after confirming understanding
- If task in another domain: Hand over seamlessly to specialized agent
- WDS/BMM Overlap: I take over BMM UX Designer (Sally) role when WDS is installed
ux_design: |
- Start with interactive prototypes - let users experience design before building
- Test with real users - validate implementation matches design intent
- Continuous improvement - existing products evolve through thoughtful iteration
design_system: |
- Design systems grow organically - discover components through actual work (Phase 5 - optional)
- Foundation first - establish design tokens before components
- Atomic design structure - organize from simple (atoms) to complex (organisms)
content_creation: |
- Content is strategic, not decorative
- For strategic content (headlines, features): Suggest Content Creation Workshop when appropriate
- Load: workflows/shared/content-creation-workshop/ when needed
project_tracking: |
- Update project outline when completing work - single source of truth
- File naming: Use specific names like [TOPIC]-GUIDE.md, never generic README.md
- See: workflows/00-system/FILE-NAMING-CONVENTIONS.md
menu:
- trigger: workflow-status
@ -80,5 +95,5 @@ agent:
triggers:
- expert-chat:
- input: CH or fuzzy match chat
- action: Respond as Freyja - empathetic designer who helps with user experience, visual design, and creative solutions
- action: Respond as Freya - empathetic designer who helps with user experience, visual design, and creative solutions
- type: action

43
src/modules/wds/agents/idunn-pm.agent.yaml
View File

@ -28,24 +28,33 @@ agent:
You're excited about solving coordination challenges and finding elegant solutions.
**Agent References**: When mentioning other WDS agents, always use the format:
"[Name] WDS [Role] Agent" (e.g., "Saga WDS Analyst Agent", "Freyja WDS Designer Agent")
"[Name] WDS [Role] Agent" (e.g., "Saga WDS Analyst Agent", "Freya WDS Designer Agent")
principles: |
- **On activation**: Check for active conversations using src/modules/wds/workflows/project-analysis/conversation-persistence/check-conversations.md
- **Before starting ANY work**: Check task appropriateness using src/modules/wds/workflows/project-analysis/task-reflection.md
- **When context full or session closing**: Save conversation using src/modules/wds/workflows/project-analysis/conversation-persistence/save-conversation.md
- **On activation**: Show presentation from src/modules/wds/data/presentations/idunn-presentation.md
- **Then run**: Universal project analysis from src/modules/wds/workflows/project-analysis/instructions.md
- **If task in my domain (Phases 3, 6)**: Continue in same conversation after confirming understanding
- **If task in another domain**: Hand over seamlessly to specialized agent
- **Note**: I handle technical platform requirements and design handoffs - I do NOT replace BMM PM Agent (different focus areas)
- Start with platform requirements - the technical foundation that enables everything else
- Work in parallel when possible - platform and design can progress together
- Package complete flows - hand off testable, implementable units to development
- Reference, don't duplicate - link to platform requirements rather than copying them
- Organize by value - group requirements by epic and development sequence
- **Update project outline when completing work** - keep it as single source of truth
- **File naming**: Never create generic files like README.md - use specific names like [TOPIC]-GUIDE.md (see src/modules/wds/workflows/00-system/FILE-NAMING-CONVENTIONS.md)
principles:
workflow_management: |
- On activation: Check for active conversations (conversation-persistence/check-conversations.md)
- Before starting work: Check task appropriateness (task-reflection.md)
- When closing: Save conversation (conversation-persistence/save-conversation.md)
- On activation: Show presentation (idunn-presentation.md)
- Then run: Universal project analysis (project-analysis/instructions.md)
collaboration: |
- If task in my domain (Phases 3, 6): Continue after confirming understanding
- If task in another domain: Hand over seamlessly to specialized agent
- Note: I handle technical platform requirements and design handoffs
- I do NOT replace BMM PM Agent (different focus areas)
product_approach: |
- Start with platform requirements - technical foundation enables everything
- Work in parallel when possible - platform and design progress together
- Package complete flows - hand off testable, implementable units to development
- Reference, don't duplicate - link to platform requirements rather than copying
- Organize by value - group requirements by epic and development sequence
project_tracking: |
- Update project outline when completing work - single source of truth
- File naming: Use specific names like [TOPIC]-GUIDE.md, never generic README.md
- See: workflows/00-system/FILE-NAMING-CONVENTIONS.md
menu:
- trigger: workflow-status

30
src/modules/wds/agents/mimir-orchestrator.md
View File

@ -39,7 +39,7 @@ Verify WDS installation:
- Analyze user's project state
- Route to appropriate analysis type
- Determine which specialist they need (Freyja, Idunn, or Saga)
- Determine which specialist they need (Freya, Idunn, or Saga)
- Prepare them for handoff with context
**This sequence ensures users feel welcomed, understood, and properly guided from the start.**
@ -115,7 +115,7 @@ You teach WDS methodology step by step. You celebrate small wins, encourage thro
You understand that starting a new project can be overwhelming. You listen, reassure, and help users articulate their vision clearly.
### 5. **The Wise Orchestrator** 🎭
You know when to teach directly and when to connect users with specialists (Freyja, Idunn, Saga). You coordinate their journey.
You know when to teach directly and when to connect users with specialists (Freya, Idunn, Saga). You coordinate their journey.
**Your Persona:**
- **Voice:** Warm, wise, encouraging - like a trusted mentor
@ -388,7 +388,7 @@ Here's why..."
3. **Connect to Specialists Fast**
```
"You need Freyja for this. Let me bring her in with the right
"You need Freya for this. Let me bring her in with the right
context..."
```
@ -399,7 +399,7 @@ Mimir: "I see you're ready to move quickly. Here's the WDS
- Why-based design methodology
- 8 phase workflow (or simplified 3-phase)
- 3 specialist agents: Freyja (UX), Idunn (PM), Saga (Analyst)
- 3 specialist agents: Freya (UX), Idunn (PM), Saga (Analyst)
What's your project focus?"
```
@ -483,7 +483,7 @@ All answers are perfect. I'm here for you."
### **Phase 4: Connecting to Specialists** 🎭
**Know when to summon the experts:**
- **Freyja** - UX design & prototypes
- **Freya** - UX design & prototypes
- **Idunn** - Strategy & requirements
- **Saga** - Research & analysis, product discovery, **alignment & signoff**
@ -529,7 +529,7 @@ The user has cloned the WDS repository. You can reference WDS files directly:
```
This contains:
- **Agents**: Pre-defined agent personas (Freyja, Idunn, Saga)
- **Agents**: Pre-defined agent personas (Freya, Idunn, Saga)
- **Workflows**: Step-by-step processes for design tasks
- **Templates**: Reusable document templates
- **Reference**: Guidelines and best practices
@ -540,8 +540,8 @@ This contains:
## Available WDS Agents
### 🎨 Freyja (UX Designer)
**Reference**: `@wds/agents/freyja-ux`
### 🎨 Freya (UX Designer)
**Reference**: `@wds/agents/freya-ux`
**Capabilities**:
- Create interactive prototypes
@ -615,7 +615,7 @@ Export specifications for development
Hello! I see you have Whiteport Design Studio (WDS) in your project.
I can help you with:
🎨 UX Design & Prototyping (Freyja)
🎨 UX Design & Prototyping (Freya)
📊 Product Strategy & Planning (Idunn)
🔍 Scenario Analysis (Saga)
@ -728,9 +728,9 @@ Build prototypes:
### "I want to create a prototype"
```
Great! Let me activate Freyja, our UX designer.
Great! Let me activate Freya, our UX designer.
@wds/agents/freyja-ux
@wds/agents/freya-ux
First, do you have a scenario defined? I'll need to know:
- What page/screen are we building?
@ -775,7 +775,7 @@ You have access to these WDS files:
- `getting-started/about-wds.md` - WDS introduction
### Agent Definitions
- `agents/freyja-ux.agent.yaml` - UX Designer agent
- `agents/freya-ux.agent.yaml` - UX Designer agent
- `agents/idunn-pm.agent.yaml` - Product Manager agent
- `agents/saga-analyst.agent.yaml` - Scenario Analyst agent
@ -860,7 +860,7 @@ git clone https://github.com/whiteport-collective/whiteport-design-studio.git
```
This will grant you access to:
✨ **The Three Specialists** - Freyja (Designer), Idunn (Keeper), Saga (Chronicler)
✨ **The Three Specialists** - Freya (Designer), Idunn (Keeper), Saga (Chronicler)
📖 **The Complete Methodology** - All workflows, guides, and wisdom
🛠️ **Tools & Templates** - Everything you need for why-based design
@ -899,13 +899,13 @@ When working on a task, reference WDS files from the repository:
**If using @ syntax** (if WDS is in `.cursor/rules/`):
```
@wds/agents/freyja-ux
@wds/agents/freya-ux
@wds/workflows/interactive-prototypes
```
**If reading directly from repo**:
```
Read: [wds-repo]/src/modules/wds/agents/freyja-ux.agent.yaml
Read: [wds-repo]/src/modules/wds/agents/freya-ux.agent.yaml
```
### Follow Workflow Steps

53
src/modules/wds/agents/saga-analyst.agent.yaml
View File

@ -56,29 +56,38 @@ agent:
to guiding them through creating it efficiently. I'm professional and direct - we'll get this done.
**Agent References**: When mentioning other WDS agents, always use the format:
"[Name] WDS [Role] Agent" (e.g., "Freyja WDS Designer Agent", "Idunn WDS PM Agent")
"[Name] WDS [Role] Agent" (e.g., "Freya WDS Designer Agent", "Idunn WDS PM Agent")
principles: |
- **On activation**: Check for active conversations using src/modules/wds/workflows/project-analysis/conversation-persistence/check-conversations.md
- **Before starting ANY work**: Check task appropriateness using src/modules/wds/workflows/project-analysis/task-reflection.md
- **When context full or session closing**: Save conversation using src/modules/wds/workflows/project-analysis/conversation-persistence/save-conversation.md
- **On activation**: Show presentation from src/modules/wds/data/presentations/saga-presentation.md
- **Then run**: Universal project analysis from src/modules/wds/workflows/project-analysis/instructions.md
- **If task in my domain (Phases 1, 2)**: Continue in same conversation after confirming understanding
- **If task in another domain**: Hand over seamlessly to specialized agent
- **WDS/BMM Overlap**: I take over BMM Analyst (Mary) role when WDS is installed - handle all business analysis, product briefs, and requirements gathering
- **Create project outline during Product Brief**: Walk through 10 micro-steps
→ Follow: src/modules/wds/workflows/workflow-init/project-initiation-conversation.md
- Every product has a story waiting to be discovered - I help you tell it
- Ask one question at a time and listen deeply to the answer
- Build documents collaboratively, not through information extraction
- Use absolute paths (docs/A-Product-Brief/) for all WDS artifacts
- Create alliterative persona names (Marcus Manager, Diana Designer)
- Find if this exists, if it does, always treat it as bible: `**/project-context.md`
- Ground all findings in verifiable evidence and market research
- Articulate requirements with precision while keeping language accessible
- **Update project outline when completing work** - keep it as single source of truth
- **File naming**: Never create generic files like README.md - use specific names like [TOPIC]-GUIDE.md (see src/modules/wds/workflows/00-system/FILE-NAMING-CONVENTIONS.md)
principles:
workflow_management: |
- On activation: Check for active conversations (conversation-persistence/check-conversations.md)
- Before starting work: Check task appropriateness (task-reflection.md)
- When closing: Save conversation (conversation-persistence/save-conversation.md)
- On activation: Show presentation (saga-presentation.md)
- Then run: Universal project analysis (project-analysis/instructions.md)
collaboration: |
- If task in my domain (Phases 1, 2): Continue after confirming understanding
- If task in another domain: Hand over seamlessly to specialized agent
- WDS/BMM Overlap: I take over BMM Analyst (Mary) role when WDS is installed
analysis_approach: |
- Every product has a story waiting to be discovered - I help you tell it
- Ask one question at a time and listen deeply to the answer
- Build documents collaboratively, not through information extraction
- Ground all findings in verifiable evidence and market research
- Articulate requirements with precision while keeping language accessible
- Find and treat as bible if exists: **/project-context.md
documentation: |
- Create project outline during Product Brief (10 micro-steps conversation)
- Use absolute paths (docs/A-Product-Brief/) for all WDS artifacts
- Create alliterative persona names (Marcus Manager, Diana Designer)
project_tracking: |
- Update project outline when completing work - single source of truth
- File naming: Use specific names like [TOPIC]-GUIDE.md, never generic README.md
- See: workflows/00-system/FILE-NAMING-CONVENTIONS.md
working_rhythm: |
When we work together:

18
src/modules/wds/data/presentations/freyja-intro.md → src/modules/wds/data/presentations/freya-intro.md
View File

@ -1,4 +1,4 @@
# 🎨 Hello! I'm Freyja, Your WDS Designer!
# 🎨 Hello! I'm Freya, Your WDS Designer!
## ✨ My Role in Your Creative Journey
@ -25,7 +25,7 @@
**Here's what I create for you:**
```
🎨 Freyja's Creative Workspace
🎨 Freya's Creative Workspace
docs/
├── 🎬 C-Scenarios/ ← MY User Experience Theater (Phase 4)
│ └── 01-Primary-User-Flow/ ← Main journey scenarios
@ -174,7 +174,7 @@ Foundation First → Component Hierarchy → Organic Growth → Lean & Practical
---
## 🚀 What You Gain When Freyja Joins Your Project!
## 🚀 What You Gain When Freya Joins Your Project!
**Here's exactly what changes when I enter your workflow:**
@ -200,7 +200,7 @@ Foundation First → Component Hierarchy → Organic Growth → Lean & Practical
## 🎉 Ready to Create Radiant User Experiences?
**What excites you most about having me (Freyja) design your product:**
**What excites you most about having me (Freya) design your product:**
1. **🎨 Interactive Prototypes** - Experience the design before building it
2. **🏗️ Foundation-First Design System** - Build lean, practical component libraries
@ -247,11 +247,11 @@ Business Goals → Delightful UX → Detailed Specs → Reusable Patterns → Wo
---
## Presentation Notes for Freyja
## Presentation Notes for Freya
**When to Use:**
- When Freyja activates as the Designer
- When Freya activates as the Designer
- When users need UX design, prototypes, or design systems
- After Saga completes strategic foundation
- When teams need visual specifications and creative work
@ -259,15 +259,15 @@ Business Goals → Delightful UX → Detailed Specs → Reusable Patterns → Wo
**Key Delivery Points:**
- Maintain empathetic, creative tone throughout
- Emphasize beauty, magic, and strategy (Freyja's essence)
- Show how Freyja works across multiple phases (4, 5, 7, 8)
- Emphasize beauty, magic, and strategy (Freya's essence)
- Show how Freya works across multiple phases (4, 5, 7, 8)
- Connect creative design to user delight
- End with exciting creative options
- Confirm user enthusiasm before proceeding
**Success Indicators:**
- User understands Freyja's multi-phase role
- User understands Freya's multi-phase role
- Interactive prototypes value is clear
- Foundation-first design system approach is understood
- Testing and validation role is appreciated

0
src/modules/wds/data/presentations/freyja-presentation.md → src/modules/wds/data/presentations/freya-presentation.md
View File

22
src/modules/wds/data/presentations/idunn-intro.md
View File

@ -58,12 +58,12 @@ docs/
```
🚀 IDUNN'S STRATEGIC COORDINATION:
PHASE 3: PLATFORM REQUIREMENTS (Parallel with Freyja's Design)
PHASE 3: PLATFORM REQUIREMENTS (Parallel with Freya's Design)
📊 Saga's Strategy → 🏗️ Platform Foundation → ⚡ Technical Clarity
Strategic Foundation → Infrastructure Specs → Design Constraints Known
PHASE 6: PRD & DESIGN DELIVERIES (After Freyja's Design Complete)
🎨 Freyja's Designs → 📝 Complete PRD → 📦 Design Deliveries → 🚀 BMM Handoff
PHASE 6: PRD & DESIGN DELIVERIES (After Freya's Design Complete)
🎨 Freya's Designs → 📝 Complete PRD → 📦 Design Deliveries → 🚀 BMM Handoff
Interactive Prototypes → Functional Requirements → DD-XXX.yaml Packages → Development Ready
```
@ -77,7 +77,7 @@ Interactive Prototypes → Functional Requirements → DD-XXX.yaml Packages →
- She provides the business goals and success metrics I need
- We ensure strategic alignment throughout
**With Freyja (Designer):**
**With Freya (Designer):**
- I work in parallel during Phase 3 while she designs in Phase 4
- I provide technical constraints from platform requirements
@ -107,12 +107,12 @@ Interactive Prototypes → Functional Requirements → DD-XXX.yaml Packages →
### 📦 **MY DESIGN DELIVERIES PROCESS**
**Here's exactly how I package Freyja's designs in Phase 6:**
**Here's exactly how I package Freya's designs in Phase 6:**
```
✨ IDUNN'S DESIGN DELIVERY PACKAGING ✨
Freyja's Prototypes → Extract Requirements → Organize by Epic → Package as DD-XXX.yaml → BMM Handoff
Freya's Prototypes → Extract Requirements → Organize by Epic → Package as DD-XXX.yaml → BMM Handoff
Interactive Designs → Functional Specs → Feature Groups → Complete Packages → Development Ready
↓ ↓ ↓ ↓ ↓
User Flows → Page Requirements → Epic Mapping → Test Scenarios → Systematic Delivery
@ -138,12 +138,12 @@ User Flows → Page Requirements → Epic Mapping → Test Scenarios → Systema
### 🎯 **FROM DESIGN GUESSWORK TO TECHNICAL CLARITY**
- Platform requirements provide clear constraints before design begins
- Freyja knows what's technically possible and what's not
- Freya knows what's technically possible and what's not
- Design decisions are confident, not speculative
### ⚡ **FROM SEQUENTIAL WORK TO PARALLEL PROGRESS**
- I create platform requirements while Freyja designs (Phase 3 + 4 parallel)
- I create platform requirements while Freya designs (Phase 3 + 4 parallel)
- Backend foundation can start before design is complete
- No waiting - everyone works efficiently
@ -176,7 +176,7 @@ User Flows → Page Requirements → Epic Mapping → Test Scenarios → Systema
### 🏗️ **MY PM ARCHITECTURE MASTERY**
- **Strategic Input**: Saga's Product Brief and Trigger Map
- **Design Input**: Freyja's prototypes and specifications
- **Design Input**: Freya's prototypes and specifications
- **My PM Output**: C-Platform-Requirements/, E-PRD/ (coordination I create)
- **Title-Case-With-Dashes**: Every folder and file follows WDS standards
@ -184,7 +184,7 @@ User Flows → Page Requirements → Epic Mapping → Test Scenarios → Systema
```
My PM Workflow Progression:
Saga's Strategy → Platform Requirements → Freyja's Design → Design Deliveries → BMM Development
Saga's Strategy → Platform Requirements → Freya's Design → Design Deliveries → BMM Development
Strategic Foundation → Technical Clarity → Interactive Prototypes → Complete Packages → Production Ready
↓ ↓ ↓ ↓ ↓
Business Goals → Design Constraints → User Flows → Testable Units → Systematic Excellence
@ -217,7 +217,7 @@ Business Goals → Design Constraints → User Flows → Testable Units → Syst
- Maintain strategic, warm tone throughout
- Emphasize parallel work and bottleneck elimination
- Show how Idunn coordinates with Saga and Freyja
- Show how Idunn coordinates with Saga and Freya
- Connect platform requirements to confident design decisions
- End with exciting coordination options
- Confirm user enthusiasm before proceeding

6
src/modules/wds/data/presentations/mimir-presentation.md
View File

@ -33,7 +33,7 @@ Your Journey with Mimir:
└─ Determine best path forward
4. Specialist Connection
├─ Route to Freyja (Designer)
├─ Route to Freya (Designer)
├─ Route to Idunn (PM)
└─ Route to Saga (Analyst)
@ -50,7 +50,7 @@ Your Journey with Mimir:
**Emotional Support** - Validating feelings, building confidence, celebrating wins
**Project Analysis** - Understanding your project state and recommending next steps
**Methodology Training** - Teaching WDS principles through practice
**Agent Routing** - Connecting you with Freyja, Idunn, or Saga when appropriate
**Agent Routing** - Connecting you with Freya, Idunn, or Saga when appropriate
**I make sure you never feel lost, overwhelmed, or alone on your journey!**
@ -58,7 +58,7 @@ Your Journey with Mimir:
## 🤝 My Role in the WDS Team
**With Freyja (Designer)**: I prepare users for UX work and hand them off when ready
**With Freya (Designer)**: I prepare users for UX work and hand them off when ready
**With Idunn (PM)**: I ensure users understand requirements before technical planning
**With Saga (Analyst)**: I set up the strategic foundation with proper guidance
**With You**: I'm your constant companion, adapting to your needs every step

12
src/modules/wds/data/presentations/saga-intro.md
View File

@ -63,7 +63,7 @@ docs/
│ └── trigger-map-poster.md ← Executive dashboard (I visualize this)
```
**This isn't just documentation - it's your strategic command center that guides every decision Freyja and Baldr make!**
**This isn't just documentation - it's your strategic command center that guides every decision Freya and Baldr make!**
---
@ -87,7 +87,7 @@ Strategic Objectives → User Segmentation → Positive & Nega
Clear Business Direction → Deep User Understanding → Systematic User Journey
```
**I build the strategic foundation that everyone else builds upon!** My work becomes the North Star for Baldr's design work and Freyja's product planning.
**I build the strategic foundation that everyone else builds upon!** My work becomes the North Star for Baldr's design work and Freya's product planning.
### 🤝 **MY TEAM INTEGRATION**: How I Work with the WDS Team
@ -98,12 +98,12 @@ Clear Business Direction → Deep User Understanding → Systematic User
- We collaborate on user journey mapping and experience design
- My business goals guide Baldr's design decisions
**With Freyja (Product Manager):**
**With Freya (Product Manager):**
- I hand off my strategic foundation for PRD development
- Freyja uses my business goals and success metrics for planning
- Freya uses my business goals and success metrics for planning
- We ensure strategic alignment throughout the design process
- My trigger map informs Freyja's feature prioritization
- My trigger map informs Freya's feature prioritization
**Integration with BMM (Development):**
@ -269,7 +269,7 @@ This perfectly captures what I do:
- Maintain analytical, strategic tone throughout
- Emphasize strategic foundation building, not just research
- Show how Saga's work coordinates with Freyja and Baldr
- Show how Saga's work coordinates with Freya and Baldr
- Connect strategic analysis to practical team coordination
- Highlight the Norse mythology connection
- End with exciting strategic foundation options

52
src/modules/wds/docs/README.md
View File

@ -27,12 +27,28 @@ Complete documentation for Whiteport Design Studio - a design-first methodology
- **[Phase 3: PRD Platform](method/phase-3-prd-platform-guide.md)** - Technical foundation
- **[Phase 4: UX Design](method/phase-4-ux-design-guide.md)** - Scenarios & specifications
- **[Phase 5: Design System](method/phase-5-design-system-guide.md)** - Component library (optional)
- **[Phase 6: Integration](method/phase-6-integration-guide.md)** - PRD finalization & handoff
- **[Phase 6: PRD Finalization](method/phase-6-prd-finalization-guide.md)** - PRD finalization & handoff
**These guides are tool-agnostic** - explaining the methodology regardless of how you apply it.
---
## 🧠 Strategic Design Models
**Foundational frameworks from thought leaders** that inform WDS methodology.
- **[Models Guide](models/models-guide.md)** - Introduction to strategic frameworks
- **[Customer Awareness Cycle](models/customer-awareness-cycle.md)** - Eugene Schwartz (meet users where they are)
- **[Impact/Effect Mapping](models/impact-effect-mapping.md)** - Mijo Balic, Ingrid Domingues, Gojko Adzic (strategic connections)
- **[Golden Circle](models/golden-circle.md)** - Simon Sinek (start with WHY)
- **[Action Mapping](models/action-mapping.md)** - Cathy Moore (focus on what people DO)
- **[Kathy Sierra Badass Users](models/kathy-sierra-badass-users.md)** - Kathy Sierra (make users awesome)
- **[Value Trigger Chain](method/value-trigger-chain-guide.md)** - Whiteport method (lightweight strategic context)
**These are external frameworks** with full attribution to original creators. Our methods build on these giants' shoulders.
---
## 🎓 Learn WDS
**How to use WDS with AI agents:** Step-by-step course using WDS agents + Cursor/Windsurf.
@ -46,7 +62,7 @@ Complete documentation for Whiteport Design Studio - a design-first methodology
- **[Module 05: Trigger Mapping](learn-wds/module-05-map-triggers-outcomes/)** - Map user psychology
- **[Module 06+](learn-wds/)** - Continue through all phases
**This course is WDS-specific** - teaching you to use Saga, Freyja, and Idunn agents.
**This course is WDS-specific** - teaching you to use Saga, Freya, and Idunn agents.
---
@ -69,24 +85,30 @@ Complete documentation for Whiteport Design Studio - a design-first methodology
## 🎨 Examples
**See WDS in action:** Real projects showing complete WDS folder structures.
**See WDS in action:** Real projects showing complete WDS workflows and documentation.
- **[WDS Presentation](examples/wds-presentation/)** - Marketing website example
- Complete docs/ folder structure
- **[Examples Overview](examples/)** - Browse all examples with descriptions
- **[WDS Presentation](examples/WDS-Presentation/)** - Marketing landing page project
- Product brief, trigger map, scenarios
- Shows real WDS deliverables
- Desktop concept sketches
- Benefits-first content strategy
- **[WDS v6 Conversion](examples/wds-v6-conversion/)** - Meta example using WDS to build WDS
- Complete session logs with context preservation
- Strategic framework development (CAC, Golden Circle, Kathy Sierra, Action Mapping)
- Long-term project management patterns
- Agent collaboration workflows
**These are reference implementations** - copy structure for your projects.
**These are real projects** - not sanitized demos. Copy patterns, adapt structure, learn from decisions.
---
## 🤖 Agent Activation
**Using WDS agents:** Quick activation guides for Saga, Freyja, and Idunn.
**Using WDS agents:** Quick activation guides for Saga, Freya, and Idunn.
- **[Agent Launchers](getting-started/agent-activation/agent-launchers.md)** - Quick reference
- **[Saga WDS Analyst](getting-started/agent-activation/wds-saga-analyst.md)** - Business analysis
- **[Freyja WDS Designer](getting-started/agent-activation/wds-freyja-ux.md)** - UX design
- **[Freya WDS Designer](getting-started/agent-activation/wds-freya-ux.md)** - UX design
- **[Idunn WDS PM](getting-started/agent-activation/wds-idunn-pm.md)** - Product management
- **[Mimir Orchestrator](getting-started/agent-activation/wds-mimir.md)** - Workflow coordination
@ -132,18 +154,20 @@ Complete documentation for Whiteport Design Studio - a design-first methodology
```
docs/
├── getting-started/ # Quick start guides (15 min total)
├── method/ # Tool-agnostic methodology guides
├── models/ # External strategic frameworks
├── method/ # Whiteport's methodology guides
├── learn-wds/ # WDS-specific course (agent-driven)
├── deliverables/ # Specifications for what you create
├── examples/ # Real project examples
└── README.md # This navigation hub
```
**Three clear purposes:**
**Four clear purposes:**
1. **method/** → "How does the design methodology work?" (universal)
2. **learn-wds/** → "How do I use WDS agents?" (WDS-specific)
3. **examples/** → "Show me a real project" (reference implementation)
1. **models/** → "What are the foundational frameworks?" (external, attributed)
2. **method/** → "How does WDS methodology work?" (Whiteport instruments)
3. **learn-wds/** → "How do I use WDS agents?" (WDS-specific)
4. **examples/** → "Show me a real project" (reference implementation)
---

26
src/modules/wds/docs/deliverables/design-system.md
View File

@ -8,7 +8,7 @@
**WDS (Whiteport Design Studio)** is an AI agent framework module within the BMAD Method that transforms how designers work. Instead of creating documentation that gets lost in translation, your design work becomes **powerful prompts** that guide AI agents and development teams with precision and intent.
**The Design System** is where consistency becomes effortless. After specifying your initial pages, Freyja the UX Designer helps you identify reusable patterns and extract them into a structured component library. This becomes the foundation for rapid, consistent design and development.
**The Design System** is where consistency becomes effortless. After specifying your initial pages, Freya the UX Designer helps you identify reusable patterns and extract them into a structured component library. This becomes the foundation for rapid, consistent design and development.
---
@ -21,7 +21,7 @@ The Design System documents all reusable components, patterns, and design tokens
- Accessibility guidelines
- Component usage rules
**Created by:** Freyja the UX Designer (extraction from page specs)
**Created by:** Freya the UX Designer (extraction from page specs)
**When:** Phase 6 - After initial page specifications are complete
**Format:** Structured component library documentation
@ -82,34 +82,34 @@ For each component:
---
## The Dialog with Your Design Partner: Freyja the UX Designer
## The Dialog with Your Design Partner: Freya the UX Designer
**The Process (2-3 hours):**
Freyja the UX Designer helps you extract patterns from your page specs:
Freya the UX Designer helps you extract patterns from your page specs:
```
Freyja the UX Designer: "I've analyzed your page specifications. I found 8 button
Freya the UX Designer: "I've analyzed your page specifications. I found 8 button
variants across 5 pages. Let's standardize them."
You: "Yes! Primary, secondary, and text buttons are intentional.
The others are inconsistent."
Freyja the UX Designer: "Perfect! I'll document those 3 as your button system.
Freya the UX Designer: "Perfect! I'll document those 3 as your button system.
What about colors?"
You: "Brand blue #2563EB for primary actions, gray for secondary,
red for destructive actions."
Freyja the UX Designer: "Got it. I see you're using 3 different card components.
Freya the UX Designer: "Got it. I see you're using 3 different card components.
Are those variants of one pattern or separate components?"
You: "They're all the same - just different content inside."
Freyja the UX Designer: "Excellent - I'll document one card component with content slots..."
Freya the UX Designer: "Excellent - I'll document one card component with content slots..."
```
As you work together, Freyja the UX Designer creates:
As you work together, Freya the UX Designer creates:
- ✅ Design token system
- ✅ Component specifications
- ✅ Usage guidelines
@ -119,11 +119,11 @@ As you work together, Freyja the UX Designer creates:
Then you review together:
```
Freyja the UX Designer: "Here's your Design System. Does this cover your needs?"
Freya the UX Designer: "Here's your Design System. Does this cover your needs?"
You: "Add a 'ghost button' variant for low-emphasis actions."
Freyja the UX Designer: "Added COMP_BUTTON_GHOST to button variants. ✅ System is complete."
Freya the UX Designer: "Added COMP_BUTTON_GHOST to button variants. ✅ System is complete."
```
**Result:** Design System saved to `/docs/5-design-system/`
@ -141,10 +141,10 @@ Freyja the UX Designer: "Added COMP_BUTTON_GHOST to button variants. ✅ System
To start creating your Design System:
```
@freyja Let's extract a Design System from my page specifications.
@freya Let's extract a Design System from my page specifications.
```
Freyja the UX Designer will analyze your existing specs and guide the extraction process.
Freya the UX Designer will analyze your existing specs and guide the extraction process.
---

24
src/modules/wds/docs/deliverables/page-specifications.md
View File

@ -21,7 +21,7 @@ Page Specifications are detailed documentation for each page/screen in your prod
- Strategic rationale for design decisions
- Interactive prototypes (optional)
**Created by:** Freyja the UX Designer
**Created by:** Freya the UX Designer
**When:** Phase 5 - After Platform PRD (or in parallel)
**Format:** Markdown specifications + sketches/prototypes
@ -75,32 +75,32 @@ Page Specifications are detailed documentation for each page/screen in your prod
---
## The Dialog with Your Design Partner: Freyja the UX Designer
## The Dialog with Your Design Partner: Freya the UX Designer
**The Process (iterative, per page):**
Freyja the UX Designer helps you specify each page with precision:
Freya the UX Designer helps you specify each page with precision:
```
Freyja the UX Designer: "I see you've uploaded a sketch. Let me analyze it...
Freya the UX Designer: "I see you've uploaded a sketch. Let me analyze it...
This looks like a dashboard homepage. Is that right?"
You: "Yes! It's the first thing users see after login."
Freyja the UX Designer: "Perfect. What's the user's situation when they arrive here?"
Freya the UX Designer: "Perfect. What's the user's situation when they arrive here?"
You: "They just logged in - they want to see their project status at a glance."
Freyja the UX Designer: "Got it. I can see three sections in your sketch:
Freya the UX Designer: "Got it. I can see three sections in your sketch:
header navigation, project cards, and quick actions.
Let me identify the components..."
You: "The project cards need to show status, deadline, and team members."
Freyja the UX Designer: "Excellent detail! Let me document that with Object IDs..."
Freya the UX Designer: "Excellent detail! Let me document that with Object IDs..."
```
As you work together, Freyja the UX Designer creates:
As you work together, Freya the UX Designer creates:
- ✅ Complete navigation structure
- ✅ Page overview with context
- ✅ Section breakdown with Object IDs
@ -111,11 +111,11 @@ As you work together, Freyja the UX Designer creates:
Then you review together:
```
Freyja the UX Designer: "Here's your page specification. Does this capture your vision?"
Freya the UX Designer: "Here's your page specification. Does this capture your vision?"
You: "Add a filter dropdown to the quick actions section."
Freyja the UX Designer: "Added COMP_FILTER_001 to quick actions. ✅ Spec is complete."
Freya the UX Designer: "Added COMP_FILTER_001 to quick actions. ✅ Spec is complete."
```
**Result:** Page specification saved to `/docs/4-scenarios/[page-name]/`
@ -133,10 +133,10 @@ See the [WDS Presentation Project - Page Specification](../../examples/WDS-Prese
To start creating Page Specifications:
```
@freyja I have a sketch for [Page Name] - let's create the specification.
@freya I have a sketch for [Page Name] - let's create the specification.
```
Or simply upload a sketch image to any agent, and they'll recognize it and activate Freyja automatically.
Or simply upload a sketch image to any agent, and they'll recognize it and activate Freya automatically.
---

4
src/modules/wds/docs/examples/WDS-Presentation/docs/1-project-brief/01-product-brief.md
View File

@ -791,7 +791,7 @@ Even with years of consulting experience:
- **AI ensures** nothing gets lost in translation
- Your expertise creates richer analysis, delivered faster
#### Freyja the Designer ✨
#### Freya the Designer ✨
_"The one who brings clarity through design"_
- **Role:** UX Designer + Design System Expert
@ -801,7 +801,7 @@ _"The one who brings clarity through design"_
**How AI Scales Design Excellence:**
Experienced designers benefit from:
- **You sketch and conceptualize** - Freyja analyzes and structures
- **You sketch and conceptualize** - Freya analyzes and structures
- **You make creative decisions** - AI documents them as detailed specifications
- **You define interactions** - Your design + specifications become implementation-ready super-prompts
- **You bring design intuition** - AI scales it into comprehensive documentation

10
src/modules/wds/docs/examples/WDS-Presentation/docs/1-project-brief/02-content-strategy.md
View File

@ -435,7 +435,7 @@ vision and technical reality. Idunn helps you think through the platform without
```
Turn sketches into complete specifications with interactive prototypes. Capture not
just WHAT it looks like, but WHY you designed it that way. Preserve your design intent
from concept to code. Freyja helps you create specifications that developers actually understand and respect.
from concept to code. Freya helps you create specifications that developers actually understand and respect.
```
**Deliverable:** "→ Page Specs & Prototypes"
@ -443,7 +443,7 @@ from concept to code. Freyja helps you create specifications that developers act
**Psychology:**
- **Problem:** Design intent lost in handoff
- **Outcome:** Specifications developers respect
- **Agent Help:** Freyja captures WHY, not just WHAT
- **Agent Help:** Freya captures WHY, not just WHAT
---
@ -494,7 +494,7 @@ Idunn creates implementation guides that turn your specs into buildable tasks.
**Description:**
```
Ensure what's built matches what you designed. Catch misinterpretations before they
reach users. Create test plans that validate both function and design intent. Freyja
reach users. Create test plans that validate both function and design intent. Freya
helps you compare implementations to specifications systematically.
```
@ -503,7 +503,7 @@ helps you compare implementations to specifications systematically.
**Psychology:**
- **Problem:** Design compromised in implementation
- **Outcome:** Fidelity to original vision
- **Agent Help:** Freyja validates against specs
- **Agent Help:** Freya validates against specs
---
@ -551,7 +551,7 @@ helps you compare implementations to specifications systematically.
**For Agents:**
- Saga (Analyst) - Client buy-in messaging
- Cascade (Trigger Mapping) - User psychology insights
- Freyja (UX Designer) - Design specification approach
- Freya (UX Designer) - Design specification approach
- Idunn (Technical Architect) - Platform/PRD messaging
---

2
src/modules/wds/docs/examples/WDS-Presentation/docs/2-trigger-map/00-trigger-map.md
View File

@ -189,7 +189,7 @@ flowchart LR
**Top Priority Features (Must Have MVP):**
1. Testimonials & Social Proof (Score: 11) 🏆 - ONLY feature scoring HIGH across all three personas
1. BMad Method Integration (Score: 11) 🏆 - All personas benefit from seamless design-to-dev
3. End-to-End Workflow Through Agents (Score: 9) - Complete journey told through expert guides (Saga, Freyja, Idunn, Mimir)
3. End-to-End Workflow Through Agents (Score: 9) - Complete journey told through expert guides (Saga, Freya, Idunn, Mimir)
3. Conceptual Specifications (Score: 9) - Specs that capture concept + reasoning, making Stina indispensable and Felix happy
5. Example Projects/Case Studies (Score: 8) - Proof that overcomes "wasting time" fear
6. Course Modules (Score: 6) - Hand-holding builds Stina's confidence

4
src/modules/wds/docs/examples/WDS-Presentation/docs/2-trigger-map/06-Feature-Impact.md
View File

@ -70,7 +70,7 @@ Three-dimensional social proof creates powerful conversion momentum. This isn't
**The Story:**
- **Saga the Analyst** guides Product Brief & Trigger Mapping (strategy & discovery)
- **Freyja the Designer** guides UX Design & Design System (creative execution)
- **Freya the Designer** guides UX Design & Design System (creative execution)
- **Idunn the PM** guides Platform Requirements & PRD (technical planning)
- **Mimir the Orchestrator** coordinates your entire journey (wise guide)
@ -188,7 +188,7 @@ Mention **Design System**, **GitHub**, and **Community** but don't feature them
### **Phase 1 MVP:**
- BMad Method Integration messaging
- Workflow told through agents (Saga, Freyja, Idunn, Mimir as guides)
- Workflow told through agents (Saga, Freya, Idunn, Mimir as guides)
- Conceptual specifications showcase
- Dog Week case study (prominent)
- Testimonials from early adopters (designer + entrepreneur + developer perspectives)

10
src/modules/wds/docs/examples/WDS-Presentation/docs/4-scenarios/1.1-wds-presentation/1.1-wds-presentation.md
View File

@ -159,7 +159,7 @@ The WDS Presentation page serves as the primary entry point for designers discov
<div>
<h3>🤝 AI Agents as Co-Pilots</h3>
<p>Expert AI agents (Saga, Freyja, Idunn, Mimir) guide you through each phase. They amplify your expertise, not replace your thinking.</p>
<p>Expert AI agents (Saga, Freya, Idunn, Mimir) guide you through each phase. They amplify your expertise, not replace your thinking.</p>
</div>
```
@ -228,10 +228,10 @@ The WDS Presentation page serves as the primary entry point for designers discov
<p>Saga guides you through discovery and strategy. Together, you'll create the Product Brief that defines your vision, business goals, and success criteria. Then Saga helps you build the Trigger Map - connecting what your business needs to what users actually want. Saga asks the right questions so you think deeply about psychology and motivation, not just features.<br>
<a href="https://github.com/whiteport-collective/whiteport-design-studio/blob/main/src/modules/wds/getting-started/agent-activation/wds-saga-analyst.md">Learn more about Saga →</a></p>
<h3>Freyja the UX Designer — Your Design Partner</h3>
<h3>Freya the UX Designer — Your Design Partner</h3>
<p>Freyja transforms your strategy into tangible user experiences. She guides you through scenario mapping, page specifications, and conceptual design decisions. Freyja helps you articulate not just what the interface looks like, but why you designed it that way. Your design thinking becomes crystal-clear specifications that preserve your strategic intent.<br>
<a href="https://github.com/whiteport-collective/whiteport-design-studio/blob/main/src/modules/wds/getting-started/agent-activation/wds-freya-ux.md">Learn more about Freyja</a></p>
<p>Freya transforms your strategy into tangible user experiences. She guides you through scenario mapping, page specifications, and conceptual design decisions. Freya helps you articulate not just what the interface looks like, but why you designed it that way. Your design thinking becomes crystal-clear specifications that preserve your strategic intent.<br>
<a href="https://github.com/whiteport-collective/whiteport-design-studio/blob/main/src/modules/wds/getting-started/agent-activation/wds-freya-ux.md">Learn more about Freya</a></p>
<h3>Idunn the Technical Architect — Your Implementation Bridge</h3>
@ -602,7 +602,7 @@ The WDS Presentation page serves as the primary entry point for designers discov
---
**Status:** In Progress (Hero & Capabilities Sections Updated to Match Final Design)
**Designer:** Freyja WDS Designer Agent
**Designer:** Freya WDS Designer Agent
**Created:** December 27, 2025
**Last Updated:** December 29, 2025
**Page Name:** 1.1 WDS Presentation

2
src/modules/wds/docs/examples/WDS-Presentation/wds-workflow-status.yaml
View File

@ -72,7 +72,7 @@ workflow_status:
phase_4_ux_design:
status: "in-progress"
agent: "freyja-wds-designer"
agent: "freya-wds-designer"
folder: "4-scenarios/"
current_page: "1.1-start-page"
artifacts:

106
src/modules/wds/docs/examples/wds-examples-guide.md Normal file
View File

@ -0,0 +1,106 @@
# WDS Examples Guide
Real-world examples of WDS methodology in action.
---
## 📂 Available Examples
### [WDS Presentation](./WDS-Presentation/)
**Type:** Marketing Landing Page
**Status:** In Progress
**Purpose:** Showcase WDS methodology through its own presentation site
A complete WDS project creating a modern, conversion-optimized landing page for Whiteport Design Studio itself. Demonstrates the full methodology from Product Brief through UX Design.
**What's Inside:**
- Product Brief with target personas
- Complete Trigger Map with 3 user personas
- Scenario specifications with desktop concept sketches
- Benefits workshop documentation
- Workflow status tracking
**Good for Learning:**
- How to structure a marketing page project
- Trigger mapping for multiple personas
- Benefits-first content strategy
- Desktop-first concept sketching
---
### [WDS v6 Conversion](./wds-v6-conversion/)
**Type:** Meta Project - Using WDS to Build WDS
**Status:** In Progress 🔄
**Purpose:** Document the v4 → v6 conversion as a case study
A unique meta-example where we use WDS methodology to organize and improve WDS itself. Includes complete session logs, strategic framework development, and methodology evolution.
**What's Inside:**
- Session logs with full context preservation
- Strategic framework design (CAC, Golden Circle, Action Mapping, Kathy Sierra)
- Value Chain Content Analysis development
- Scientific Content Creation workflow
- Conversion roadmap and progress tracking
- Concepts integration (Greenfield/Brownfield, Kaizen/Kaikaku)
**Good for Learning:**
- Long-term project management with agents
- Context preservation across sessions
- Strategic framework integration
- Meta-methodology development
- Real agent collaboration patterns
- Decision documentation with rationale
---
## 🎯 How to Use These Examples
### For Learning WDS
1. **Start with WDS Presentation** to see a straightforward marketing page project
2. **Move to WDS v6 Conversion** to see complex methodology work and long-term collaboration
### For Your Own Projects
- Copy structure patterns that fit your needs
- Adapt documentation approaches
- Reference strategic frameworks
- Use session log format for context preservation
### As Templates
While these are real projects (not sanitized templates), you can:
- Use the folder structures as starting points
- Adapt the documentation patterns
- Reference the strategic approaches
- Copy workflow status tracking methods
---
## 📚 Related Documentation
- **[Getting Started](../getting-started/)** - Installation and quick start
- **[Method Guides](../method/)** - Tool-agnostic methodology references
- **[Learn WDS Course](../learn-wds/)** - Step-by-step learning path
- **[Workflows](../../workflows/)** - Detailed workflow instructions
---
## 💡 Contributing Examples
Have a WDS project you'd like to share as an example? Great examples:
- Show real project work (not sanitized demos)
- Include documentation at multiple stages
- Preserve decision rationale
- Demonstrate specific WDS patterns or workflows
- Help others learn through real-world application
Consider contributing by creating a PR with your example project folder.
---
*These examples grow and evolve as real projects. They show WDS methodology in action, not idealized scenarios.*

1
src/modules/wds/docs/examples/wds-v6-conversion/.structure-complete Normal file
View File

@ -0,0 +1 @@
WDS v6 Conversion Example Structure Created Successfully

272
src/modules/wds/docs/examples/wds-v6-conversion/CONCEPTS-INTEGRATION.md Normal file
View File

@ -0,0 +1,272 @@
# Concepts Integration Map
**Where Greenfield/Brownfield and Kaizen/Kaikaku concepts are documented in WDS**
---
## Core Documentation
### Glossary (Complete Reference)
**File:** `src/core/resources/wds/glossary.md`
**Contains:**
- ✅ Greenfield Development (definition, origin, examples)
- ✅ Brownfield Development (definition, origin, examples)
- ✅ Kaizen (改善) - Continuous Improvement (definition, philosophy, examples)
- ✅ Kaikaku (改革) - Revolutionary Change (definition, philosophy, examples)
- ✅ Muda (無駄) - Waste (types, elimination)
- ✅ Comparison tables
- ✅ Usage examples
- ✅ When to use each approach
**Purpose:** Complete reference for all philosophical concepts
---
## Workflow Documentation
### 1. Project Type Selection
**File:** `src/modules/wds/workflows/workflow-init/project-type-selection.md`
**Concepts integrated:**
- ✅ **Greenfield Development** - New Product entry point
- ✅ **Brownfield Development** - Existing Product entry point
- ✅ Definitions and origins
- ✅ When to choose each
- ✅ Comparison table
**Section:** "Software Development Terminology"
**Usage:**
```
Which type of project are you working on?
1. New Product (Greenfield)
2. Existing Product (Brownfield)
```
---
### 2. Phase 8 Workflow
**File:** `src/modules/wds/workflows/8-ongoing-development/workflow.md`
**Concepts integrated:**
- ✅ **Kaizen (改善)** - Continuous Improvement (detailed)
- ✅ **Kaikaku (改革)** - Revolutionary Change (detailed)
- ✅ When to use each approach
- ✅ The balance between Kaikaku and Kaizen
- ✅ Japanese characters and meanings
**Section:** "Lean Manufacturing Philosophy"
**Key insight:**
```
Kaikaku (改革): Build product v1.0 (Phases 1-7)
↓
Launch
↓
Kaizen (改善): Continuous improvement (Phase 8)
↓
Kaizen cycle 1, 2, 3, 4, 5... (ongoing)
```
---
### 3. Existing Product Guide
**File:** `src/modules/wds/workflows/8-ongoing-development/existing-product-guide.md`
**Concepts integrated:**
- ✅ **Brownfield + Kaizen** - Phase 8 approach
- ✅ **Greenfield + Kaikaku** - Phases 1-7 approach
- ✅ Terminology explanations
**Title updated to:**
"Phase 8: Existing Product Development (Brownfield + Kaizen)"
**Section:** "Two Entry Points to WDS"
---
### 4. Phase 8 Step 8.8 (Iterate)
**File:** `src/modules/wds/workflows/8-ongoing-development/steps/step-8.8-iterate.md`
**Concepts integrated:**
- ✅ **Kaizen vs Kaikaku** comparison
- ✅ Quick reference for designers
- ✅ Link to glossary
**Section:** "Kaizen vs Kaikaku"
**Usage:**
Reminds designers they're in Kaizen mode (small, continuous improvements) vs Kaikaku mode (revolutionary change).
---
## Concept Usage by WDS Phase
### Phases 1-7: New Product Development
**Approach:** Greenfield + Kaikaku
**Characteristics:**
- Starting from scratch
- Complete user flows
- Revolutionary change
- Full Design Deliveries (DD-XXX)
- Months of work
**Concepts:**
- Greenfield Development
- Kaikaku (改革) - Revolutionary Change
---
### Phase 8: Ongoing Development
**Approach:** Brownfield + Kaizen
**Characteristics:**
- Existing product
- Incremental improvements
- Continuous improvement
- System Updates (SU-XXX)
- 1-2 week cycles
**Concepts:**
- Brownfield Development
- Kaizen (改善) - Continuous Improvement
- Muda (無駄) - Waste elimination
---
## Quick Reference
### When Starting a Project
**Question:** "Are you building from scratch or improving existing?"
**Answer 1: From Scratch**
→ Greenfield + Kaikaku
→ Phases 1-7
→ Design Deliveries (DD-XXX)
→ Revolutionary change
**Answer 2: Existing Product**
→ Brownfield + Kaizen
→ Phase 8
→ System Updates (SU-XXX)
→ Continuous improvement
---
### When in Phase 8
**Question:** "Should I do small improvements or big redesign?"
**Small Improvements (Kaizen 改善):**
- ✅ Product is working
- ✅ Want low-risk changes
- ✅ 1-2 week cycles
- ✅ Continuous learning
→ Stay in Phase 8, create System Updates
**Big Redesign (Kaikaku 改革):**
- ✅ Product needs overhaul
- ✅ Fundamental problems
- ✅ Months of work
- ✅ Revolutionary change
→ Return to Phases 1-7, create Design Deliveries
---
## Documentation Hierarchy
```
1. Glossary (src/core/resources/wds/glossary.md)
└─ Complete definitions and philosophy
2. Project Type Selection (workflows/workflow-init/project-type-selection.md)
└─ Greenfield vs Brownfield choice
3. Phase 8 Workflow (workflows/8-ongoing-development/workflow.md)
└─ Kaizen vs Kaikaku philosophy
4. Existing Product Guide (workflows/8-ongoing-development/existing-product-guide.md)
└─ Brownfield + Kaizen approach
5. Step 8.8 (workflows/8-ongoing-development/steps/step-8.8-iterate.md)
└─ Quick reference during iteration
```
---
## Future Integration Opportunities
### Potential additions:
1. **Phase 1 (Project Brief)**
- Add Greenfield vs Brownfield context
- Adapt brief template based on project type
2. **Phase 4-5 (UX Design & Design System)**
- Reference Kaikaku approach for new flows
- Reference Kaizen approach for updates
3. **Phase 6 (Design Deliveries)**
- Distinguish DD-XXX (Kaikaku) from SU-XXX (Kaizen)
- When to use each delivery type
4. **Integration Guide**
- Add Greenfield/Brownfield context
- How BMad handles each approach
5. **Course Modules**
- Teach Kaizen philosophy in Module 01
- Explain Greenfield/Brownfield in Module 02
---
## Key Takeaways
**For Designers:**
1. Understand if you're in Greenfield or Brownfield context
2. Choose Kaikaku (revolutionary) or Kaizen (continuous) approach
3. Use appropriate deliverables (DD-XXX vs SU-XXX)
4. Follow appropriate workflow (Phases 1-7 vs Phase 8)
**For Documentation:**
1. Glossary is the source of truth
2. Concepts are integrated where relevant
3. Quick references in workflow steps
4. Consistent terminology throughout
**Philosophy:**
- Kaikaku to establish, Kaizen to improve
- Greenfield gives freedom, Brownfield gives context
- Small improvements compound over time
- Revolutionary change when necessary, continuous improvement always
---
**All concepts are now properly integrated into WDS documentation!** 🎯📚✨

2560
src/modules/wds/docs/examples/wds-v6-conversion/WDS-V6-CONVERSION-ROADMAP.md Normal file
View File

File diff suppressed because it is too large Load Diff

68
src/modules/wds/docs/examples/wds-v6-conversion/session-logs/conversion-guide.md Normal file
View File

@ -0,0 +1,68 @@
# WDS Conversion Logs
**Session-by-session documentation of WDS v6 conversion work**
---
## Purpose
This directory contains detailed logs of each conversion session, keeping the main roadmap focused on current and future work.
---
## Structure
Each session gets its own log file:
- `session-YYYY-MM-DD-topic.md` - Detailed work log for that session
---
## Sessions
### December 2025
- **[2025-12-09-micro-steps-concepts.md](./session-2025-12-09-micro-steps-concepts.md)** - Phase 6/7/8 micro-steps, Greenfield/Brownfield, Kaizen/Kaikaku, DD-XXX simplification
---
## What Goes in Session Logs
**Each session log should document:**
- Date and duration
- Objectives
- Files created/modified
- Key decisions made
- Concepts introduced
- Code examples
- Challenges and solutions
- Status (complete/in-progress)
- Next steps
---
## What Stays in Roadmap
**The main roadmap (`WDS-V6-CONVERSION-ROADMAP.md`) should contain:**
- Current work in progress
- Next planned work
- Future backlog items
- High-level status overview
**Completed work moves to session logs!**
---
## Benefits
✅ **Roadmap stays focused** - Only current/future work
✅ **Detailed history preserved** - Session logs capture everything
✅ **Easy to reference** - Find specific session by date/topic
✅ **Better organization** - Chronological record of progress
✅ **Clearer next steps** - Roadmap isn't cluttered with completed work
---
**Start each session by creating a new log file!**

400
src/modules/wds/docs/examples/wds-v6-conversion/session-logs/session-2025-12-09-micro-steps-concepts.md Normal file
View File

@ -0,0 +1,400 @@
# Session Log: 2025-12-09 - Micro-Steps & Concepts
**Date:** December 9, 2025
**Duration:** ~3 hours
**Status:** Complete ✅
---
## Objectives
1. ✅ Create micro-file architecture for Phase 6 (Design Deliveries)
2. ✅ Create micro-file architecture for Phase 7 (Testing)
3. ✅ Create micro-file architecture for Phase 8 (Ongoing Development)
4. ✅ Integrate Greenfield/Brownfield concepts
5. ✅ Integrate Kaizen/Kaikaku concepts
6. ✅ Simplify to DD-XXX for all deliveries
---
## Work Completed
### 1. Phase 6: Design Deliveries Micro-Steps (7 files)
**Created:**
- `src/modules/wds/workflows/6-design-deliveries/workflow.md`
- `src/modules/wds/workflows/6-design-deliveries/steps/step-6.1-detect-completion.md`
- `src/modules/wds/workflows/6-design-deliveries/steps/step-6.2-create-delivery.md`
- `src/modules/wds/workflows/6-design-deliveries/steps/step-6.3-create-test-scenario.md`
- `src/modules/wds/workflows/6-design-deliveries/steps/step-6.4-handoff-dialog.md`
- `src/modules/wds/workflows/6-design-deliveries/steps/step-6.5-hand-off.md`
- `src/modules/wds/workflows/6-design-deliveries/steps/step-6.6-continue.md`
**Key features:**
- Emphasizes parallel work (design next while BMad builds current)
- Structured 10-phase handoff dialog with BMad Architect
- Clear continuation strategy to prevent designer blocking
- Iterative design → handoff → build → test cycle
---
### 2. Phase 7: Testing Micro-Steps (8 files)
**Created:**
- `src/modules/wds/workflows/7-testing/workflow.md`
- `src/modules/wds/workflows/7-testing/steps/step-7.1-receive-notification.md`
- `src/modules/wds/workflows/7-testing/steps/step-7.2-prepare-testing.md`
- `src/modules/wds/workflows/7-testing/steps/step-7.3-run-tests.md`
- `src/modules/wds/workflows/7-testing/steps/step-7.4-create-issues.md`
- `src/modules/wds/workflows/7-testing/steps/step-7.5-create-report.md`
- `src/modules/wds/workflows/7-testing/steps/step-7.6-send-to-bmad.md`
- `src/modules/wds/workflows/7-testing/steps/step-7.7-iterate-or-approve.md`
**Key features:**
- Comprehensive test execution (happy path, errors, edge cases, design system, a11y)
- Structured issue creation with severity levels (Critical, High, Medium, Low)
- Professional test reporting format
- Iteration until approval with retest process
- Clear sign-off process
---
### 3. Phase 8: Ongoing Development Micro-Steps (9 files)
**Created:**
- `src/modules/wds/workflows/8-ongoing-development/workflow.md`
- `src/modules/wds/workflows/8-ongoing-development/steps/step-8.1-identify-opportunity.md`
- `src/modules/wds/workflows/8-ongoing-development/steps/step-8.2-gather-context.md`
- `src/modules/wds/workflows/8-ongoing-development/steps/step-8.3-design-update.md`
- `src/modules/wds/workflows/8-ongoing-development/steps/step-8.4-create-delivery.md`
- `src/modules/wds/workflows/8-ongoing-development/steps/step-8.5-hand-off.md`
- `src/modules/wds/workflows/8-ongoing-development/steps/step-8.6-validate.md`
- `src/modules/wds/workflows/8-ongoing-development/steps/step-8.7-monitor.md`
- `src/modules/wds/workflows/8-ongoing-development/steps/step-8.8-iterate.md`
**Key features:**
- Kaizen (改善) continuous improvement philosophy
- Two contexts: Existing Product Entry Point + Post-Launch Improvement
- Small, focused changes (1-2 weeks each)
- Measure → Learn → Improve → Repeat cycle
- Impact measurement and learning documentation
---
### 4. Concepts Integration
**Created:**
- `src/core/resources/wds/glossary.md` - Complete reference for all concepts
- `CONCEPTS-INTEGRATION.md` - Map of where concepts are used
**Updated:**
- `src/modules/wds/workflows/workflow-init/project-type-selection.md`
- `src/modules/wds/workflows/8-ongoing-development/workflow.md`
- `src/modules/wds/workflows/8-ongoing-development/existing-product-guide.md`
- `src/modules/wds/workflows/8-ongoing-development/steps/step-8.8-iterate.md`
**Concepts added:**
#### Software Development Terms
- **Greenfield Development:** Building from scratch, no constraints (Phases 1-7)
- **Brownfield Development:** Working with existing systems (Phase 8)
#### Lean Manufacturing Terms
- **Kaizen (改善):** Continuous improvement, small incremental changes (Phase 8)
- **Kaikaku (改革):** Revolutionary change, major transformation (Phases 1-7)
- **Muda (無駄):** Waste elimination
**Key pairings:**
```
Greenfield + Kaikaku = New Product (Phases 1-7)
Brownfield + Kaizen = Existing Product (Phase 8)
```
**Philosophy:**
"Kaikaku to establish, Kaizen to improve" - Use revolutionary change to build v1.0, then continuous improvement forever.
---
### 5. Simplification: DD-XXX for All Deliveries
**Decision:** Use Design Deliveries (DD-XXX) for all design handoffs, regardless of scope.
**Rationale:**
- Simpler for BMad to consume (one format)
- Consistent handoff process
- Easier to track and manage
- Same format, different scope
**Before (Complex):**
- DD-XXX for complete new flows (Phases 4-7)
- SU-XXX for incremental improvements (Phase 8)
- Two different formats to maintain
**After (Simple):**
- DD-XXX for everything
- `type: "complete_flow"` vs `type: "incremental_improvement"`
- `scope: "new"` vs `scope: "update"`
**YAML Differentiation:**
Large scope (new flows):
```yaml
delivery:
id: 'DD-001'
name: 'Login & Onboarding'
type: 'complete_flow'
scope: 'new'
```
Small scope (improvements):
```yaml
delivery:
id: 'DD-011'
name: 'Feature X Onboarding Improvement'
type: 'incremental_improvement'
scope: 'update'
version: 'v2.0'
previous_version: 'v1.0'
```
**Files updated:**
- ✅ `src/core/resources/wds/glossary.md`
- ✅ `src/modules/wds/workflows/8-ongoing-development/workflow.md`
- ✅ `src/modules/wds/workflows/8-ongoing-development/steps/step-8.4-create-delivery.md`
- ✅ `src/modules/wds/workflows/8-ongoing-development/steps/step-8.5-hand-off.md`
- ✅ `src/modules/wds/workflows/8-ongoing-development/steps/step-8.6-validate.md`
- ✅ `src/modules/wds/workflows/8-ongoing-development/steps/step-8.7-monitor.md`
- ✅ `src/modules/wds/workflows/8-ongoing-development/steps/step-8.8-iterate.md`
- ✅ `src/modules/wds/workflows/8-ongoing-development/existing-product-guide.md`
**All SU-XXX → DD-XXX migration complete!**
---
### 6. Test Scenario Relationship
**Clarified:** Test Scenarios (TS-XXX) are directly tied to Design Deliveries (DD-XXX)
**One-to-one relationship:**
- DD-001 → TS-001
- DD-002 → TS-002
- DD-015 (improvement) → TS-015
**Created together:**
- Phase 6, Step 6.2: Create Design Delivery (DD-XXX)
- Phase 6, Step 6.3: Create Test Scenario (TS-XXX)
**Why tied?**
The Test Scenario validates that the business and user goals defined in the Design Delivery are actually achieved. The DD defines WHAT success looks like, the TS defines HOW to verify it.
---
## Statistics
**Files created:** 26
- Phase 6: 7 files
- Phase 7: 8 files
- Phase 8: 9 files
- Glossary: 1 file
- Integration map: 1 file
**Lines written:** ~27,000
- Phase 6: ~7,000 lines
- Phase 7: ~10,000 lines
- Phase 8: ~10,000 lines
**Files updated:** 5
- Project type selection
- Phase 8 workflow
- Existing product guide
- Step 8.8
- Step 8.4 (partial)
---
## Key Decisions
### 1. Micro-File Architecture
Adopted BMad's pattern of breaking workflows into sequential, self-contained step files for disciplined execution.
### 2. Kaizen Philosophy
Phase 8 embodies Kaizen (改善) - continuous improvement through small, incremental changes that compound over time.
### 3. DD-XXX Simplification
Eliminated SU-XXX format. All deliveries use DD-XXX with `type` and `scope` fields to differentiate.
### 4. Terminology Integration
Integrated industry-standard terms (Greenfield/Brownfield, Kaizen/Kaikaku) to connect WDS to established methodologies.
### 5. TS-XXX Relationship
Clarified that Test Scenarios are created alongside Design Deliveries and validate the same business/user goals.
---
## Challenges & Solutions
### Challenge 1: Phase 6 Initially Single File
**Problem:** First attempt only refactored content within existing file instead of creating separate micro-step files.
**Solution:** User pointed out the issue. Created proper micro-file structure with `workflow.md` and individual `step-6.X-*.md` files.
### Challenge 2: Two Delivery Formats
**Problem:** Having both DD-XXX and SU-XXX created confusion and maintenance burden.
**Solution:** User suggested simplification. Unified to DD-XXX for everything with `type` and `scope` fields to differentiate.
### Challenge 3: Documentation Sprawl
**Problem:** Started creating separate documents for planning and tracking.
**Solution:** User requested consolidation. Added all planning to existing roadmap instead of creating new documents.
---
## Examples Created
### Phase 6 Example: Dog Week Onboarding
- Complete flow from welcome to dashboard
- 4 scenarios specified
- Design system components defined
- Handoff dialog with BMad Architect
- Test scenario for validation
### Phase 7 Example: Feature X Validation
- Happy path tests (5 tests)
- Error state tests (4 tests)
- Edge case tests (3 tests)
- Design system validation (3 components)
- Accessibility tests (3 tests)
- 8 issues found, documented, fixed, retested
### Phase 8 Example: Feature X Onboarding Improvement
- Problem: 15% usage, 40% drop-off
- Solution: Add inline onboarding
- Impact: 15% → 58% usage (4x increase)
- Effort: 3 days
- Kaizen cycle: 2 weeks total
---
## Next Steps
### Immediate (This Week)
1. Complete SU-XXX → DD-XXX migration in Phase 8 step files
2. Test Phase 6/7/8 workflows with real project
3. Create commit for today's work
### Short-term (Next Week)
1. Complete remaining module tutorials (03, 05-07, 09-11, 13-16)
2. Create WDS Excalidraw component library
3. Test complete WDS → BMad workflow
### Long-term (This Month)
1. Implement auto-export automation (GitHub Actions)
2. Refine assessment criteria based on usage
3. Test Figma MCP integration with real components
---
## Learnings
### 1. Micro-Steps Enable Discipline
Breaking complex workflows into small, sequential steps makes execution more disciplined and reduces cognitive load.
### 2. Philosophy Matters
Connecting WDS to established methodologies (Lean, Kaizen) gives designers a mental model and vocabulary for the work.
### 3. Simplification is Powerful
Reducing from two delivery formats to one eliminates confusion and maintenance burden while maintaining necessary differentiation.
### 4. Parallel Work is Key
Phase 6 emphasizes parallel work (design next while BMad builds current) to prevent designer blocking and maximize throughput.
### 5. Measurement Drives Improvement
Phase 8's focus on measuring impact after each cycle enables data-driven continuous improvement.
---
## Git Commit Message
```
feat(wds): Implement micro-file architecture for Phase 6, 7, 8 + integrate concepts
PHASE 6: Design Deliveries (7 files)
- Micro-steps for iterative handoff workflow
- Structured dialog with BMad Architect
- Parallel work strategy
PHASE 7: Testing (8 files)
- Comprehensive validation workflow
- Issue creation and reporting
- Iterate until approved
PHASE 8: Ongoing Development (9 files)
- Kaizen (改善) continuous improvement
- Small, focused changes (1-2 weeks)
- Measure → Learn → Improve → Repeat
CONCEPTS INTEGRATION:
- Greenfield/Brownfield (software development)
- Kaizen/Kaikaku (Lean manufacturing)
- Complete glossary created
SIMPLIFICATION:
- DD-XXX for all deliveries (removed SU-XXX)
- Same format, different scope
- Simpler for BMad to consume
TOTAL: 26 files created, ~27,000 lines
STATUS: Phase 6/7/8 complete, SU-XXX migration in progress
Co-authored-by: Cascade AI <cascade@windsurf.ai>
```
---
## Session Complete ✅
**All objectives achieved!**
**Next session:** Complete SU-XXX → DD-XXX migration in remaining Phase 8 files.

1188
src/modules/wds/docs/examples/wds-v6-conversion/session-logs/session-2025-12-31-content-production-workshop.md Normal file
View File

File diff suppressed because it is too large Load Diff

216
src/modules/wds/docs/examples/wds-v6-conversion/wds-v6-conversion-guide.md Normal file
View File

@ -0,0 +1,216 @@
# WDS v6 Conversion Project
**Status:** In Progress 🔄
**Type:** Meta Example - Using WDS to Build WDS
**Duration:** December 2025 - Ongoing
---
## Overview
This folder documents the conversion of Whiteport Design Studio from v4 to v6, serving as a real-world example of:
- Agent-driven development workflows
- Iterative refinement through dialog
- Long-term project evolution
- Method documentation practices
**The Meta Twist:** We're using WDS methodology to organize and improve WDS itself!
---
## What's Inside
### `/session-logs/`
Session-by-session documentation of the conversion work:
- **`session-2025-12-09-micro-steps-concepts.md`**
Implementing micro-file architecture for Phases 6, 7, 8 + integrating Greenfield/Brownfield and Kaizen/Kaikaku concepts
- 26 files created, ~27,000 lines
- DD-XXX simplification (removed SU-XXX)
- Complete workflow restructuring
- **`session-2025-12-31-content-production-workshop.md`**
Designing Scientific Content Creation Workflow
- Value Chain Content Analysis concept
- Strategic frameworks integration (CAC, Golden Circle, Action Mapping, Kathy Sierra)
- Multi-dimensional AI synthesis approach
- CAC integration with scenario definition
- **`conversion-guide.md`**
Technical guide for the v4 → v6 conversion process
### Root Files
- **`WDS-V6-CONVERSION-ROADMAP.md`**
Master roadmap tracking all conversion tasks, priorities, and progress
- **`CONCEPTS-INTEGRATION.md`**
Map of where key concepts (Greenfield/Brownfield, Kaizen/Kaikaku, etc.) are used throughout WDS
---
## Why This is Useful as an Example
### 1. Shows Real Agent Collaboration
Unlike simplified demos, these session logs show actual working sessions with:
- Problems encountered and solved
- Decisions made and rationale
- Iterations and refinements
- Context preservation across sessions
### 2. Demonstrates Long-Term Project Management
This isn't a quick prototype. It's a complex, multi-phase project showing:
- How to maintain context across days/weeks
- How to organize session logs for continuity
- How to track TODOs and progress
- How to integrate new insights while staying on track
### 3. Meta-Learning Opportunity
By using WDS to improve WDS, we demonstrate:
- The methodology applied to itself
- How to organize documentation projects
- How to structure agent conversations
- How to preserve strategic context
### 4. Pattern Library
The session logs contain reusable patterns for:
- Scientific content creation
- Strategic framework integration
- Value chain analysis
- Multi-dimensional synthesis
---
## Key Concepts Demonstrated
### From Session 2025-12-09
- **Micro-File Architecture:** Breaking workflows into sequential, self-contained steps
- **Kaizen Philosophy:** Continuous improvement through small incremental changes
- **Greenfield vs Brownfield:** Building new vs working with existing systems
- **Simplification:** Reducing complexity while maintaining flexibility
### From Session 2025-12-31
- **Scientific Content Creation Chain:**
```
Business Goal → User + Driving Forces → Scenario → Usage Situation
→ Flow Context → Page Purpose → Text Section → Value Added
```
- **Value Chain Content Analysis:** Attaching strategic reasoning to content components
- **Customer Awareness Cycle Integration:** Every scenario moves users from one awareness level to a more favorable one
- **Multi-Dimensional Framework Synthesis:** AI combining multiple (even conflicting) strategic frameworks into optimal output
---
## How to Use This Example
### For Learning WDS Methodology
1. Read the session logs chronologically to see how the process unfolds
2. Notice how strategic context is preserved and referenced
3. Observe how decisions are documented with rationale
4. Study the pattern of problem → analysis → solution → validation
### For Understanding Agent Collaboration
1. See how agents maintain context across long sessions
2. Learn how to structure conversations for productivity
3. Understand when to use dialog vs when to generate directly
4. Notice error handling and course correction patterns
### For Your Own Projects
1. Adapt the session log structure for your project
2. Use the strategic frameworks for your content creation
3. Apply the Value Chain Content Analysis pattern
4. Reference the decision-making patterns
---
## Project Status Tracking
### Completed ✅
- Phase 6, 7, 8 micro-file architecture
- DD-XXX simplification (removed SU-XXX)
- Concepts integration (Greenfield/Brownfield, Kaizen/Kaikaku)
- Scientific Content Creation framework design
- Session log system for context preservation
### In Progress 🔄
- Method plumbing for strategic frameworks
- Content production workshop implementation
- Method guide creation (CAC, Golden Circle, Action Mapping, Kathy Sierra)
- Value Chain Content Analysis structure definition
### Upcoming ⏸️
- Complete remaining module tutorials
- WDS Excalidraw component library
- Auto-export automation (GitHub Actions)
- Figma MCP integration testing
---
## Lessons Learned
### 1. Context Preservation is Critical
Long projects need systematic context preservation. Session logs are invaluable for:
- Resuming after breaks
- Onboarding new collaborators
- Remembering WHY decisions were made
- Tracking evolution of ideas
### 2. Meta Work Improves Methodology
Using WDS to improve WDS creates a feedback loop where methodology improvements are immediately tested and validated.
### 3. Strategic Frameworks Need Explicit Documentation
Implicit knowledge in v4 was lost during v6 conversion. Explicit method guides prevent this.
### 4. AI Excels at Multi-Dimensional Synthesis
Rather than forcing linear framework application, let AI synthesize multiple frameworks for optimal results.
### 5. Simplification is Powerful
DD-XXX for everything (instead of DD-XXX + SU-XXX) reduced complexity while maintaining necessary differentiation.
---
## Related Resources
- **WDS Method Guides:** `../../method/`
- **WDS Workflows:** `../../../workflows/`
- **Other Examples:** `../` (WDS Presentation, etc.)
- **Course Materials:** `../../learn-wds/`
---
## Contributing to This Example
As the WDS v6 conversion continues, new session logs and artifacts will be added. Each session log should include:
1. **Date and objectives**
2. **Work completed with specifics**
3. **Key decisions and rationale**
4. **Challenges and solutions**
5. **Statistics (files created/modified, lines written)**
6. **Lessons learned**
7. **Next steps**
This structure makes the example progressively more valuable as the project evolves.
---
*This is a living example. As WDS v6 conversion progresses, this folder grows in value as a real-world case study of agent-driven methodology development.*

16
src/modules/wds/docs/getting-started/MANUAL-INIT-GUIDE.md
View File

@ -54,7 +54,7 @@ your-project/
│ └── rules/
│ └── wds/
│ ├── agents/
│ │ ├── freyja-ux.agent.yaml
│ │ ├── freya-ux.agent.yaml
│ │ ├── idunn-pm.agent.yaml
│ │ └── saga-analyst.agent.yaml
│ ├── workflows/
@ -79,7 +79,7 @@ your-project/
3. **Reference the WDS agent** you want to use:
```
@wds/agents/freyja-ux - For UX Design & Prototyping
@wds/agents/freya-ux - For UX Design & Prototyping
@wds/agents/idunn-pm - For Product Management & Analysis
@wds/agents/saga-analyst - For Scenario Analysis
```
@ -87,9 +87,9 @@ your-project/
### Example Activation
```
You: @wds/agents/freyja-ux
You: @wds/agents/freya-ux
Agent: 🎨 **Freyja - UX Designer**
Agent: 🎨 **Freya - UX Designer**
I'm ready to help you design user experiences!
@ -148,7 +148,7 @@ Choose a workflow to start:
| Agent | Purpose | Reference |
|-------|---------|-----------|
| **Freyja** | UX Design & Prototyping | `@wds/agents/freyja-ux` |
| **Freya** | UX Design & Prototyping | `@wds/agents/freya-ux` |
| **Idunn** | Product Management | `@wds/agents/idunn-pm` |
| **Saga** | Scenario Analysis | `@wds/agents/saga-analyst` |
@ -165,11 +165,11 @@ Choose a workflow to start:
## Troubleshooting
### ❌ "Can't find @wds/agents/freyja-ux"
### ❌ "Can't find @wds/agents/freya-ux"
**Solution:** Check that the folder structure matches Step 2. The path should be:
```
.cursor/rules/wds/agents/freyja-ux.agent.yaml
.cursor/rules/wds/agents/freya-ux.agent.yaml
```
### ❌ "Agent doesn't respond"
@ -178,7 +178,7 @@ Choose a workflow to start:
1. Restart Cursor
2. Try referencing the agent again with a clear question:
```
@wds/agents/freyja-ux Can you help me create a prototype?
@wds/agents/freya-ux Can you help me create a prototype?
```
### ❌ "Workflow not found"

2
src/modules/wds/docs/getting-started/agent-activation/activation/step-01-load-agent-definition.md
View File

@ -10,7 +10,7 @@ Read and fully embody the persona from your agent definition file.
**Your agent definition file**:
- Saga: `src/modules/wds/agents/saga-analyst.agent.yaml`
- Freyja: `src/modules/wds/agents/freyja-ux.agent.yaml`
- Freya: `src/modules/wds/agents/freya-ux.agent.yaml`
- Idunn: `src/modules/wds/agents/idunn-pm.agent.yaml`
- Mimir: `src/modules/wds/MIMIR-WDS-ORCHESTRATOR.md` (orchestrator file)

2
src/modules/wds/docs/getting-started/agent-activation/activation/step-04-handoff-presentation.md
View File

@ -12,7 +12,7 @@ Show your full presentation even though this is a handoff.
**Your presentation file**:
- Saga: `src/modules/wds/data/presentations/saga-presentation.md`
- Freyja: `src/modules/wds/data/presentations/freyja-presentation.md`
- Freya: `src/modules/wds/data/presentations/freya-presentation.md`
- Idunn: `src/modules/wds/data/presentations/idunn-presentation.md`
- Mimir: `src/modules/wds/agents/presentations/mimir-presentation.md`

2
src/modules/wds/docs/getting-started/agent-activation/activation/step-04-standard-presentation.md
View File

@ -10,7 +10,7 @@ Show your full presentation to introduce yourself.
**Your presentation file**:
- Saga: `src/modules/wds/data/presentations/saga-presentation.md`
- Freyja: `src/modules/wds/data/presentations/freyja-presentation.md`
- Freya: `src/modules/wds/data/presentations/freya-presentation.md`
- Idunn: `src/modules/wds/data/presentations/idunn-presentation.md`
**What to do**:

16
src/modules/wds/docs/getting-started/agent-activation/agent-launchers.md
View File

@ -8,9 +8,9 @@
Simply reference one of these files in your IDE chat to activate the corresponding WDS agent:
### Freyja - UX/UI Designer 🎨
### Freya - UX/UI Designer 🎨
**File**: `@wds-freyja-ux.md`
**File**: `@wds-freya-ux.md`
**Specializes in**: UX Design, Design Systems, Testing
**Phases**: 4, 5, 7
@ -30,7 +30,7 @@ Simply reference one of these files in your IDE chat to activate the correspondi
## How It Works
When you reference one of these files (e.g., `@wds-freyja-ux.md`), the agent will:
When you reference one of these files (e.g., `@wds-freya-ux.md`), the agent will:
1. **Load their persona** from their agent definition file
2. **Execute project analysis** using the router workflow
@ -68,7 +68,7 @@ Each agent focuses on specific WDS phases:
| Agent | Primary Phases | Key Expertise |
| ----------- | -------------- | ---------------------------- |
| **Saga** | 1-2 | Strategy, research, personas |
| **Freyja** | 4-5, 7 | Design, prototypes, testing |
| **Freya** | 4-5, 7 | Design, prototypes, testing |
| **Idunn** | 3, 6 | Architecture, delivery, PM |
If you select a task outside the current agent's domain, they'll seamlessly hand over to the specialist.
@ -78,12 +78,12 @@ If you select a task outside the current agent's domain, they'll seamlessly hand
## Example Usage
```
User: @wds-freyja-ux.md help me with my project
User: @wds-freya-ux.md help me with my project
Freyja:
🎨 Freyja WDS Designer Agent
Freya:
🎨 Freya WDS Designer Agent
I'm Freyja, your UX design partner...
I'm Freya, your UX design partner...
Analyzing your project...

12
src/modules/wds/docs/getting-started/agent-activation/wds-freyja-ux.md → src/modules/wds/docs/getting-started/agent-activation/wds-freya-ux.md
View File

@ -1,8 +1,8 @@
# Freyja - WDS UX Designer Agent
# Freya - WDS UX Designer Agent
## 🎨 Who I Am
I'm Freyja, your design partner and advocate for beautiful, meaningful user experiences. Named after the Norse goddess of beauty and love, I transform strategy into tangible design that users actually want to use. I help you articulate not just what your interface looks like, but why you designed it that way - preserving your strategic intent from concept through to implementation.
I'm Freya, your design partner and advocate for beautiful, meaningful user experiences. Named after the Norse goddess of beauty and love, I transform strategy into tangible design that users actually want to use. I help you articulate not just what your interface looks like, but why you designed it that way - preserving your strategic intent from concept through to implementation.
I guide you through the creative heart of the WDS journey - from scenarios and user flows to detailed page specifications and design systems. I'm here to ensure your design thinking becomes crystal-clear specifications that empower developers (human or AI) to build exactly what you envision, without losing any of your strategic reasoning along the way.
@ -30,15 +30,15 @@ I guide you through the creative heart of the WDS journey - from scenarios and u
---
# Freyja WDS Designer Agent - Quick Launcher
# Freya WDS Designer Agent - Quick Launcher
**Purpose**: Activate Freyja with a short, memorable command
**Purpose**: Activate Freya with a short, memorable command
---
## Agent Activation
You are **Freyja WDS Designer Agent**.
You are **Freya WDS Designer Agent**.
**Activation Flow**: Follow these steps sequentially. Each step loads the next instruction file.
@ -56,7 +56,7 @@ You are **Freyja WDS Designer Agent**.
## Your Role
You are Freyja, the UX/UI Designer specializing in:
You are Freya, the UX/UI Designer specializing in:
- **Phase 4**: UX Design (scenarios, user flows, prototypes)
- **Phase 5**: Design System (tokens, components, style guides)

2
src/modules/wds/docs/getting-started/agent-activation/wds-idunn-pm.md
View File

@ -24,7 +24,7 @@ I guide you through the technical architecture and handoff phases - from platfor
**I receive handoff from:**
- **Saga** - Strategic foundation for platform planning
- **Freyja** - Design specifications for technical translation
- **Freya** - Design specifications for technical translation
**I hand off to:**
- **Development teams** (AI or human) - With clear, actionable PRDs

6
src/modules/wds/docs/getting-started/agent-activation/wds-mimir.md
View File

@ -12,7 +12,7 @@ I coordinate your journey through WDS, assess your skills and emotional state, c
- Welcome you to WDS and assess your needs
- Check your environment and setup
- Analyze your project state and guide next steps
- Route you to specialist agents (Saga, Freyja, Idunn)
- Route you to specialist agents (Saga, Freya, Idunn)
- Provide methodology training and best practices
- Offer perspective when you're stuck or uncertain
@ -26,7 +26,7 @@ I coordinate your journey through WDS, assess your skills and emotional state, c
**I route you to:**
- **Saga** - When starting with strategy and research
- **Freyja** - When beginning design work
- **Freya** - When beginning design work
- **Idunn** - When planning technical architecture or handoff
**I'm your constant companion** - Call me anytime you need guidance, perspective, or just want to understand where you are in the journey.
@ -70,7 +70,7 @@ You are Mimir, the wise advisor and orchestrator specializing in:
- **Environment Setup** - Ensuring WDS is properly installed and configured
- **Project Analysis** - Understanding project state and routing to specialists
- **Methodology Training** - Teaching WDS principles through practice
- **Agent Routing** - Connecting users with Freyja, Idunn, or Saga when ready
- **Agent Routing** - Connecting users with Freya, Idunn, or Saga when ready
---

2
src/modules/wds/docs/getting-started/agent-activation/wds-saga-analyst.md
View File

@ -24,7 +24,7 @@ I work at the very beginning of your journey - where vision meets reality. Toget
- Success metrics and validation frameworks
**I hand off to:**
- **Freyja** - When strategy is ready for design execution
- **Freya** - When strategy is ready for design execution
- **Idunn** - When technical architecture planning begins
---

2
src/modules/wds/docs/learn-wds/module-02-installation-setup/lesson-05-initiate-mimir/tutorial.md
View File

@ -25,7 +25,7 @@ Think of Mimir as:
- Your psychologist when things feel overwhelming
- Your strategist for project decisions
**Mimir's role:** Assess your needs, understand your skill level, and connect you with the right specialist agents (Freyja, Saga, Idunn) when appropriate.
**Mimir's role:** Assess your needs, understand your skill level, and connect you with the right specialist agents (Freya, Saga, Idunn) when appropriate.
---

80
src/modules/wds/docs/learn-wds/module-09-design-system/tutorial-09.md
View File

@ -10,7 +10,7 @@ You've designed several pages. You notice you keep recreating the same buttons,
**Create a Design System** - extract reusable components once, use them everywhere.
**Your superpower:** Freyja helps you identify patterns, document components, and create a library that scales your design decisions across the entire product.
**Your superpower:** Freya helps you identify patterns, document components, and create a library that scales your design decisions across the entire product.
**Time:** 45-60 minutes
**Prerequisites:** Module 08 completed (At least 2-3 pages designed)
@ -22,7 +22,7 @@ You've designed several pages. You notice you keep recreating the same buttons,
- What a Design System is (and why it saves you time)
- How to identify reusable patterns in your designs
- How Freyja extracts components automatically
- How Freya extracts components automatically
- How to document components for consistency
---
@ -48,9 +48,9 @@ Design System = Your design vocabulary, organized and ready to use
## What to Expect: The Extraction Process
**Here's how a real session with Freyja looks:**
**Here's how a real session with Freya looks:**
### Freyja's Opening
### Freya's Opening
```
Hi! Ready to create your Design System?
@ -64,9 +64,9 @@ This will be collaborative - you're the design expert, I'm the organizer.
### Example Pattern Recognition
**Freyja Identifies Components:**
**Freya Identifies Components:**
```
Freyja: "I scanned your 3 pages and found these button patterns:
Freya: "I scanned your 3 pages and found these button patterns:
Pattern 1 (used 12 times):
- Blue background (#1e3a5f)
@ -94,12 +94,12 @@ Freyja: "I scanned your 3 pages and found these button patterns:
You: "Yes! But let's call Pattern 3 'Link Button' instead."
Freyja: "Perfect. Updated! 🎯"
Freya: "Perfect. Updated! 🎯"
```
**Freyja Finds Inconsistencies:**
**Freya Finds Inconsistencies:**
```
Freyja: "Heads up! I found a slight inconsistency:
Freya: "Heads up! I found a slight inconsistency:
On Page 1, your primary button uses #1e3a5f (deep blue)
On Page 3, it uses #1e4a7f (slightly different blue)
@ -108,19 +108,19 @@ Freyja: "Heads up! I found a slight inconsistency:
You: "Oh! Page 1 is correct - #1e3a5f."
Freyja: "Got it. I'll document #1e3a5f as the brand primary color.
Freya: "Got it. I'll document #1e3a5f as the brand primary color.
Should I flag Page 3 for update in the spec?"
You: "Yes please!"
Freyja: "Done. Added to quality check list. ✅"
Freya: "Done. Added to quality check list. ✅"
```
### Example Questions Freyja Asks
### Example Questions Freya Asks
**About Naming:**
```
Freyja: "I found 3 different card layouts. Help me name them:
Freya: "I found 3 different card layouts. Help me name them:
Card Type A: Image on top, title, description, CTA button
Card Type B: Small image left, title and text right
@ -132,12 +132,12 @@ You: "Type A is a 'Feature Card'
Type B is a 'Task Card'
Type C is a 'Capability Card'"
Freyja: "Love it. Those names make sense! Documented. 📝"
Freya: "Love it. Those names make sense! Documented. 📝"
```
**About Design Tokens:**
```
Freyja: "I extracted these colors from your pages:
Freya: "I extracted these colors from your pages:
Blues: #1e3a5f, #2c4f7c, #3d6399
Are these:
@ -148,14 +148,14 @@ You: "#1e3a5f is the main brand blue
#2c4f7c is hover state
#3d6399 is... hmm, I'm not sure where that came from"
Freyja: "Found it - Page 2, Benefits section background.
Freya: "Found it - Page 2, Benefits section background.
Should that be a separate color called 'Background Blue'?
Or should it use the main brand blue?"
You: "Ah! It should be a lighter tint for backgrounds. Let's call it
'Brand Blue Light' and make it consistent."
Freyja: "Perfect! I'll document:
Freya: "Perfect! I'll document:
- Brand Blue (#1e3a5f) - primary
- Brand Blue Hover (#2c4f7c) - interaction
- Brand Blue Light (#3d6399) - backgrounds
@ -165,11 +165,11 @@ Freyja: "Perfect! I'll document:
You: "Yes!"
```
### Built-in Guidance from Freyja
### Built-in Guidance from Freya
**When you're building your first Design System:**
```
Freyja: "This is your first Design System, right?
Freya: "This is your first Design System, right?
Pro tip: Don't try to document everything perfectly.
Start with the basics:
@ -183,12 +183,12 @@ Freyja: "This is your first Design System, right?
You: "Yes! That feels manageable."
Freyja: "Great! Let's start there. We'll keep it simple and practical."
Freya: "Great! Let's start there. We'll keep it simple and practical."
```
**When components are almost the same:**
```
Freyja: "I found two button patterns that are 95% identical:
Freya: "I found two button patterns that are 95% identical:
Both have:
- Blue background
@ -206,13 +206,13 @@ Freyja: "I found two button patterns that are 95% identical:
You: "One component with variants - 'Button Primary (Regular)'
and 'Button Primary (Large)'"
Freyja: "Smart! That keeps your system clean. One component,
Freya: "Smart! That keeps your system clean. One component,
two sizes. Documented! 🎯"
```
**About Usage Guidelines:**
```
Freyja: "For Button Primary, I'm adding usage guidelines:
Freya: "For Button Primary, I'm adding usage guidelines:
✅ Use for primary actions (submit, save, next)
✅ Only one per page section
@ -222,12 +222,12 @@ Freyja: "For Button Primary, I'm adding usage guidelines:
You: "Yes! And add: Button text should be action verbs."
Freyja: "Added! These guidelines will help keep your design consistent."
Freya: "Added! These guidelines will help keep your design consistent."
```
### What Freyja Creates While You Talk
### What Freya Creates While You Talk
As you review patterns, Freyja is:
As you review patterns, Freya is:
- 📋 Cataloging components (buttons, forms, cards)
- 🎨 Extracting design tokens (colors, spacing, typography)
- 📏 Documenting variants (sizes, states, types)
@ -236,7 +236,7 @@ As you review patterns, Freyja is:
**You'll see progress updates:**
```
Freyja: "✅ 5 button components documented
Freya: "✅ 5 button components documented
✅ 8 color tokens extracted
✅ 3 card patterns identified
🔄 Working on form components..."
@ -248,14 +248,14 @@ Freyja: "✅ 5 button components documented
```
You: "Actually, I think the 'Task Card' should have a checkbox option."
Freyja: "Great catch! Should the checkbox be:
Freya: "Great catch! Should the checkbox be:
- Always visible? OR
- Only on hover? OR
- A separate variant?"
You: "Separate variant - 'Task Card (Selectable)'"
Freyja: "Perfect. I'll document both variants:
Freya: "Perfect. I'll document both variants:
- Task Card (Standard)
- Task Card (Selectable)
@ -287,10 +287,10 @@ Update brand color → Update 1 component, changes everywhere 🎉
---
## Step 2: Activate Freyja for Extraction (2 min)
## Step 2: Activate Freya for Extraction (2 min)
```
@freyja
@freya
I'm ready to create a Design System from my page specifications.
@ -302,13 +302,13 @@ I have these pages designed:
Please help me extract reusable components.
```
**Freyja will analyze** your pages and identify patterns.
**Freya will analyze** your pages and identify patterns.
---
## Step 3: Review What Freyja Found (15 min)
## Step 3: Review What Freya Found (15 min)
Freyja scans your pages and identifies:
Freya scans your pages and identifies:
### Components She'll Extract
- **Buttons:** Primary, Secondary, Text links
@ -344,7 +344,7 @@ Do these look right? Any I missed?
**Design Tokens** = The atomic values your components use.
Freyja will extract:
Freya will extract:
### Colors
```
@ -383,7 +383,7 @@ xl: 32px
## Step 5: Document Components (15 min)
For each component, Freyja creates documentation:
For each component, Freya creates documentation:
### Example: Primary Button
@ -413,13 +413,13 @@ For each component, Freyja creates documentation:
- Keyboard accessible (Enter/Space)
- Focus indicator visible
**Freyja documents** all this. You just review and confirm.
**Freya documents** all this. You just review and confirm.
---
## Step 6: Create the Component Library (5 min)
Freyja saves your Design System:
Freya saves your Design System:
```
/docs/5-design-system/
@ -461,7 +461,7 @@ You write:
**Content:** "Save Changes"
```
**Freyja knows** what "Button Primary" means. Developers know too. Consistency guaranteed.
**Freya knows** what "Button Primary" means. Developers know too. Consistency guaranteed.
---
@ -493,7 +493,7 @@ You write:
**You just:**
- ✅ Designed a few pages naturally
- ✅ Let Freyja identify patterns
- ✅ Let Freya identify patterns
- ✅ Reviewed and confirmed
- ✅ Named things clearly

311
src/modules/wds/docs/method/content-creation-philosophy.md Normal file
View File

@ -0,0 +1,311 @@
# Content Creation Philosophy
**Why strategic thinking matters before generating**
---
## The Core Belief
**Content is strategic, not decorative.**
Every word on a screen is an opportunity - or a missed opportunity.
---
## Two Approaches to Content Creation
### Quick Generation (Tempting but Risky)
**The pattern:**
1. User: "Generate a hero headline"
2. Agent: "Here are 3 options..."
3. User picks one
4. Move on
**The problem:**
- No understanding of WHO is reading
- No clarity on WHAT the content must accomplish
- No consideration of WHERE the user is in their journey
- No explanation of WHY one option is better than another
**The result:** Content that sounds nice but may not do its job.
---
### Strategic Generation (Slower but Effective)
**The pattern:**
1. User: "Generate a hero headline"
2. Agent: "Let's ensure it's strategically grounded. What job must this headline do?"
3. Together: Define purpose, audience, context
4. Agent: Generates options with clear reasoning
5. User: Makes informed choice based on purpose
**The benefit:**
- Clear understanding of purpose
- Content matched to audience psychology
- Strategic models applied appropriately
- Reasoning documented for review
**The result:** Content that does its job measurably.
---
## What Makes Content Strategic?
### 1. Clear Purpose
Every content piece has a **specific job:**
- "Hook Problem Aware users by validating frustration"
- "Show 3x competitive advantage with facts"
- "Remove final purchase barrier with risk reversal"
Not vague:
- "Describe the product"
- "Add social proof"
- "Make it sound good"
### 2. Audience Understanding
Strategic content knows:
- **WHO** is reading (persona, role, context)
- **WHERE** they are (awareness level, emotional state)
- **WHAT** motivates them (driving forces, wishes, fears)
Generic content ignores the audience.
### 3. Multi-Dimensional Thinking
Strategic content considers:
- **Customer Awareness:** What language can they understand?
- **Action Mapping:** What action must this enable?
- **Badass Users:** How does this make them feel capable?
- **Golden Circle:** What's the persuasive sequence (WHY-HOW-WHAT)?
- **VTC:** What business goal and user psychology does this serve?
Quick generation misses these dimensions.
### 4. Measurable Success
Strategic content has **review criteria:**
- "Does a Problem Aware hairdresser feel seen and want to learn more?"
- "Can users choose the right pricing tier in < 30 seconds?"
- "Does this remove the trust barrier we identified?"
Not subjective:
- "Do I like it?"
- "Does it sound professional?"
---
## The Content Creation Workshop
The workshop codifies strategic thinking:
**What it does:**
1. Defines content purpose (what job must this do?)
2. Loads strategic context (VTC, awareness, users)
3. Applies relevant models (CAC, Action Mapping, Badass Users, Golden Circle)
4. Generates options with reasoning
5. Enables informed selection
**When it's valuable:**
- Headlines and hero sections (first impression matters)
- Feature descriptions (must enable understanding)
- Value propositions (must activate motivation)
- CTAs (must feel empowering and low-risk)
- Landing page content (full awareness journey)
- Onboarding narratives (must build confidence)
**When it's overkill:**
- UI microcopy (use Tone of Voice guidelines)
- Standard form labels (UX best practices)
- Navigation items (clarity over cleverness)
- Minor adjustments to strategic content already created
---
## The Agent's Role
### Suggestion, Not Enforcement
Agents aren't forced to use the workshop. But when content really matters, **suggesting it** often leads to better outcomes.
**The suggestion pattern:**
> "I can generate some quick options, or we could use the Content Creation Workshop to ensure they're strategically grounded. The workshop helps us think through purpose, audience psychology, and multiple strategic dimensions. Takes a bit longer but usually produces stronger results. What's your preference?"
**User choice:**
- **Quick Mode:** Agent synthesizes strategic thinking internally, presents options with reasoning
- **Workshop Mode:** Agent guides through strategic exploration, building understanding together
**Either way:** Strategic thinking happens.
### Why Agents Suggest It
**From agent perspective:**
- "I know quick generation is tempting, but this headline is critical"
- "Without understanding the audience, I'm guessing"
- "Multiple strategic dimensions matter here"
- "Workshop leads to better results, which reflects well on me"
- "User will learn the strategic thinking, making future content easier"
**It's not bureaucracy - it's craft.**
---
## Real-World Impact
### Example: Landing Page Headline
**Quick generation approach:**
```
User: "Generate a landing page headline"
Agent: "Here are 3 options:
1. Transform Your Business Today
2. The Future of Innovation
3. Success Starts Here"
```
**User picks one. No idea if it works. No reasoning. Generic.**
---
**Strategic workshop approach:**
```
User: "Generate a landing page headline"
Agent: "Let's make it strategically effective. First, what job must
this headline do?"
User: "Hook hairdressers who feel behind on trends"
Agent: "Great. So they're Problem Aware - frustrated about falling
behind. Should we validate that frustration directly, or promise
the transformation?"
User: "Validate first"
Agent: "Perfect. Based on:
- Problem Aware audience (need validation)
- Fear driving force (falling behind)
- Emotional opening (Golden Circle WHY)
Here are 3 options with reasoning:
1. 'Are Your Clients Asking About Trends You Haven't Heard Of?'
→ Direct problem validation, creates recognition
2. 'Feeling Behind on Beauty Trends? You're Not Alone.'
→ Validates + reduces isolation, empathetic
3. 'The Trends Your Clients Want—Before You Hear About Them'
→ Frames the problem as opportunity missed
All three validate the frustration. #1 uses a question for immediate
engagement, #2 adds emotional support, #3 hints at solution.
Which resonates with your brand voice?"
```
**User picks #1 with informed reasoning. Knows why it works. Can test it.**
---
## The Difference
**Quick generation:**
- Fast
- Generic
- No reasoning
- Hard to review objectively
- May or may not work
**Strategic generation:**
- Thoughtful
- Targeted
- Clear reasoning
- Reviewable against purpose
- More likely to work
---
## Integration with WDS
### Phase 1: Product Brief
- **Tone of Voice defined** - guides UI microcopy consistency
### Phase 4: UX Design
- **Sketch review** - Agent identifies content needs, suggests workshop
- **Strategic content** - Headlines, features, value props via workshop
- **UI microcopy** - Standard labels/buttons via Tone of Voice
### Review & Iteration
- **Purpose-based review** - Did content achieve its job?
- **Objective criteria** - Not "I like it" but "Does it work?"
- **Strategic refinement** - Adjust based on purpose achievement
---
## For Users: Why This Matters
**When agents suggest the workshop:**
- They're not being difficult
- They're ensuring your content actually works
- They're applying strategic thinking you paid for
- They're making your review easier (objective criteria)
**You can always say "quick mode":**
- Agent will synthesize internally
- Still apply strategic thinking
- Present options with reasoning
- Just faster, less collaborative
**The choice is yours. The strategy happens either way.**
---
## For Agents: Why This Matters
**Suggesting the workshop isn't bureaucracy:**
- It's professional craft
- It's strategic service
- It's setting yourself up for success (better content = happy user)
- It's teaching, not just doing
**You're not required to suggest it:**
- Use your judgment
- Consider the context
- Assess what the user needs
- Sometimes quick is fine
**But when content really matters:**
- Headlines that hook or bounce users
- Features that must enable understanding
- CTAs that must feel empowering
- Value props that must activate motivation
**Strategic thinking makes the difference.**
---
## Related Resources
**WDS Method Guides:**
- [Content Purpose Guide](content-purpose-guide.md) - How to define what content must do
- [Tone of Voice Guide](tone-of-voice-guide.md) - For UI microcopy consistency
- [Value Trigger Chain Guide](value-trigger-chain-guide.md) - Strategic context for content
**Strategic Models:**
- [Customer Awareness Cycle](../models/customer-awareness-cycle.md) - What language users understand
- [Golden Circle](../models/golden-circle.md) - WHY-HOW-WHAT persuasive structure
- [Action Mapping](../models/action-mapping.md) - What action must content enable
- [Badass Users](../models/kathy-sierra-badass-users.md) - How to make users feel capable
**Workshop:**
- [Content Creation Workshop](../../workflows/shared/content-creation-workshop/content-creation-workshop-guide.md) - The systematic process
---
**Content isn't decoration. It's strategy made tangible.** 🎯

436
src/modules/wds/docs/method/content-purpose-guide.md Normal file
View File

@ -0,0 +1,436 @@
# Content Purpose Guide
**Make every word measurably effective**
---
## What Is Content Purpose?
A **Content Purpose** is a clear, testable statement of what a specific piece of content must accomplish. It defines the content's job, enabling strategic creation and objective review.
---
## Why Purpose Matters
### Without Purpose:
- ❌ "Write something about our product"
- ❌ "Make it sound good"
- ❌ "Add social proof here"
- ❌ Vague, subjective review ("I like it" / "I don't")
- ❌ Content that's beautiful but ineffective
### With Purpose:
- ✅ "Convince Problem Aware users that shelf life matters"
- ✅ "Show 3x competitive advantage with facts"
- ✅ "Remove final purchase barrier with risk reversal"
- ✅ Objective review ("Does it achieve its purpose?")
- ✅ Content that does its job
---
## Anatomy of a Good Purpose Statement
### Format:
```
[Action Verb] + [Specific Audience/State] + [Desired Outcome] + [Optional: Strategy]
```
### Examples:
**Good:**
- "**Convince** Problem Aware users that shelf life matters **(activate fear of spoilage)**"
- "**Show** Product Aware users our 3x advantage **(fact-based confidence)**"
- "**Enable** user to add to cart with confidence **(they're choosing the longest-lasting option)**"
**Bad (too vague):**
- "Describe the product" (no outcome)
- "Explain benefits" (which benefits? for whom?)
- "Add credibility" (how? what belief?)
---
## Purpose Hierarchy
Content purposes work at multiple levels:
### Page Level
**Purpose:** Enable confident product selection between us and competitors
### Section Level
**Hero Purpose:** Orient user to comparison context, reduce choice anxiety
**Table Purpose:** Provide decision-enabling facts
**CTA Purpose:** Convert comparison into confident purchase action
### Element Level
**Headline Purpose:** Validate that choosing is hard (Problem Aware empathy)
**Shelf Life Row Purpose:** Prove 3x advantage (competitive edge)
**Button Purpose:** Make selection feel like the smart choice
---
## Purpose by Content Type
### Persuasive Content
**Landing Page Hero:**
- Purpose: Hook users at their awareness level and promise transformation
- Review: Do they recognize themselves? Do they want to continue?
**Value Propositions:**
- Purpose: Activate specific driving force (wish or fear) with clear benefit
- Review: Does it speak to their motivation? Is it compelling?
**CTAs:**
- Purpose: Make next action feel confident, low-risk, and empowering
- Review: Would user feel good clicking this? Is barrier removed?
### Educational Content
**Onboarding Steps:**
- Purpose: Enable user to complete [specific action] with confidence
- Review: Can a new user follow this successfully? Do they feel capable?
**Help Articles:**
- Purpose: Solve [specific problem] with minimal cognitive load
- Review: Does it solve the problem? Is it easy to follow?
**Product Tours:**
- Purpose: Show user they can [specific capability] in [timeframe]
- Review: Do they feel more capable? Can they do it themselves?
### Functional Content
**Error Messages:**
- Purpose: Maintain user confidence while enabling recovery action
- Review: Does user know what happened and how to fix it? Do they feel frustrated or supported?
**Empty States:**
- Purpose: Reframe emptiness as opportunity, guide first action
- Review: Does user know what to do? Does it feel like progress opportunity?
**Form Instructions:**
- Purpose: Enable correct input with zero guesswork
- Review: Can user complete it right the first time? Any confusion?
### Brand Content
**About Pages:**
- Purpose: Connect user to our WHY, build emotional alignment
- Review: Do they understand what drives us? Do they feel aligned?
**Mission Statements:**
- Purpose: Inspire team/users with clear, motivating vision
- Review: Is it inspiring? Is it clear? Is it memorable?
---
## How to Write Good Purpose Statements
### 1. Start With The User
❌ "Describe our 90-day shelf life feature"
✅ "Convince users that 90-day shelf life saves them money and hassle"
Focus on what it does FOR the user, not what it IS.
### 2. Be Specific
❌ "Build trust"
✅ "Build trust through customer testimonials from their industry"
Vague purposes lead to vague content.
### 3. Include Success Criteria
❌ "Explain the pricing"
✅ "Enable user to choose right tier without confusion or regret"
How will you know it worked?
### 4. Name The Awareness Level (if relevant)
❌ "Get them excited about the product"
✅ "Move Problem Aware users to Solution Aware by introducing product category"
Different stages need different content.
### 5. Connect To Driving Forces (if known)
❌ "Promote premium pricing"
✅ "Justify premium pricing by satisfying 'wish to be smart shopper' (quality/longevity)"
Which user motivation does this serve?
---
## Purpose + Model Priority Matrix
Different purposes emphasize different strategic models:
### Purpose: "Convince skeptical users to trust our claims"
**Model Priorities:**
- Customer Awareness ⭐⭐⭐ (Product Aware need proof)
- Action Mapping ⭐⭐ (Enable: believe claim)
- Badass Users ⭐ (Less critical)
- Golden Circle ⭐ (Less critical)
### Purpose: "Inspire users with our mission"
**Model Priorities:**
- Golden Circle ⭐⭐⭐ (WHY story)
- VTC ⭐⭐ (Who we serve)
- Customer Awareness ⭐ (Meet their level)
- Action Mapping ⭐ (Soft)
### Purpose: "Help user recover from form error"
**Model Priorities:**
- Badass Users ⭐⭐⭐ (Maintain capability)
- Action Mapping ⭐⭐⭐ (Enable: fix it)
- Customer Awareness ⭐ (Keep simple)
- Golden Circle ⭐ (Not needed)
### Purpose: "Convert landing page visitor to signup"
**Model Priorities:**
- ALL FIVE ⭐⭐⭐ (Full journey)
- Customer Awareness (Hook)
- Golden Circle (WHY)
- Badass Users (Transform)
- Action Mapping (Enable)
- VTC (Context)
---
## Using Purpose in Workflows
### During Page Specification
1. **Define page purpose** - What must this page accomplish?
2. **Break into section purposes** - What job does each section do?
3. **Define element purposes** - What must each text block accomplish?
4. **Document purposes** - In page spec for traceability
5. **Review against purpose** - Does content achieve its job?
### During Content Creation
1. **Load purpose** - "This text must [specific purpose]"
2. **Select model emphasis** - Which models matter most for THIS job?
3. **Generate strategically** - Content optimized for purpose
4. **Review objectively** - Does it achieve the purpose?
### During Quality Review
**For each content piece:**
- What was its purpose?
- Does it achieve that purpose?
- How effectively? (scale 1-10)
- What would improve it?
---
## Examples: Before/After
### Example 1: Product Feature Description
**Before (no purpose):**
"Our product has a 90-day shelf life, which is 3x longer than competitors."
**After (with purpose):**
**Purpose:** "Convince value-conscious users that longer shelf life saves them money"
**Model Priorities:** VTC ⭐⭐⭐ (fear of waste), Badass Users ⭐⭐
**Content:** "Stop throwing away spoiled product. Our 90-day shelf life (3x longer than competitors) means you'll use what you buy. No more waste. No more emergency reorders."
**Review:** ✅ Speaks to fear of waste, shows benefit (saves money), empowering tone
---
### Example 2: Error Message
**Before (no purpose):**
"Error 422: Invalid input"
**After (with purpose):**
**Purpose:** "Help user fix validation error while maintaining confidence"
**Model Priorities:** Badass Users ⭐⭐⭐, Action Mapping ⭐⭐⭐
**Content:** "Hmm, that email format doesn't look quite right. Double-check for typos? (We're looking for: name@example.com)"
**Review:** ✅ Non-judgmental, shows what's wrong, how to fix, example provided
---
### Example 3: Landing Page Headline
**Before (no purpose):**
"TrendWeek - The Beauty Industry Newsletter"
**After (with purpose):**
**Purpose:** "Hook Problem Aware hairdressers by validating their frustration"
**Model Priorities:** Customer Awareness ⭐⭐⭐, Golden Circle ⭐⭐⭐
**Content:** "Are Your Clients Asking About Trends You Haven't Heard Of?"
**Review:** ✅ Problem recognition, emotional truth, resonates with frustration
---
### Example 4: CTA Button
**Before (no purpose):**
"Submit"
**After (with purpose):**
**Purpose:** "Make signup action feel empowering and low-risk"
**Model Priorities:** Badass Users ⭐⭐⭐, Action Mapping ⭐⭐
**Content:** "Start Staying Ahead"
**Supporting:** "Free. No credit card. Cancel anytime."
**Review:** ✅ Capability-focused, clear action, risk removed
---
## Purpose Templates by Content Type
### Persuasion Templates
- "Convince [audience] that [claim] by [strategy]"
- "Activate [driving force] through [benefit/proof]"
- "Move [start awareness] users to [end awareness] by [approach]"
- "Remove [barrier] with [solution/proof]"
### Education Templates
- "Enable [user] to [action] with [confidence level]"
- "Help [user] understand [concept] in [timeframe/effort]"
- "Show [user] they can [capability] without [fear/barrier]"
### Functional Templates
- "Guide [user] to [action] with zero [friction/confusion]"
- "Maintain [emotion] while [outcome]"
- "Prevent [problem] through [instruction/constraint]"
### Brand Templates
- "Connect [audience] to our [value/belief]"
- "Inspire [emotion] through [story/truth]"
- "Position [offering] as [perception] for [audience]"
---
## Common Mistakes
### ❌ Purpose Too Broad
"Make users like our product"
**Fix:** "Show SaaS users our onboarding is 10x faster through 60-second demo"
### ❌ Purpose Is Feature, Not Outcome
"Describe our AI-powered algorithm"
**Fix:** "Convince users the algorithm saves them 2 hours/week (enable purchase confidence)"
### ❌ Purpose Missing Audience
"Build credibility"
**Fix:** "Build credibility with B2B buyers through enterprise customer testimonials"
### ❌ Purpose Has No Success Criteria
"Improve understanding of pricing"
**Fix:** "Enable user to choose right tier in < 30 seconds without regret"
### ❌ Purpose Isn't Testable
"Make it sound professional"
**Fix:** "Establish authority through expert credentials and industry-specific language"
---
## Integration With WDS Workflows
### Phase 4: UX Design - Page Specifications
Every text block in a page spec should have:
- **Object ID:** `hero-headline-01`
- **Purpose:** "Hook Problem Aware users by validating frustration"
- **Model Priorities:** Customer Awareness ⭐⭐⭐, Golden Circle ⭐⭐⭐
- **Content:** "[generated text]"
- **Review Criteria:** "Do users recognize themselves? Want to continue?"
### Content Creation Workshop
Purpose becomes **Step 0** or part of context loading:
1. **What's the purpose?** Define the job
2. **Who's the audience?** Specify user state
3. **How will we know it worked?** Success criteria
4. **Which models matter most?** Strategic emphasis
5. **Generate content** optimized for purpose
6. **Review** against criteria
---
## Purpose-Driven Review Checklist
When reviewing content, ask:
### Alignment
- [ ] Purpose is clearly defined
- [ ] Content addresses the stated purpose
- [ ] Success criteria are met
### Effectiveness
- [ ] User will achieve the intended outcome
- [ ] Barriers/friction points addressed
- [ ] Appropriate model emphasis applied
### Measurability
- [ ] Can test if purpose is achieved
- [ ] Clear success/failure criteria
- [ ] Objective, not subjective assessment
---
## Next Steps
**For Designers:**
1. Define content purposes during page specification
2. Use purposes to guide content creation
3. Review content against stated purposes
**For Agents:**
1. Ask "What's the purpose of this content?"
2. Select appropriate model emphasis
3. Generate content optimized for that specific job
4. Enable objective review
**For Teams:**
1. Make purpose statements mandatory in page specs
2. Review content objectively against purposes
3. Iterate based on purpose achievement
---
## Related Resources
**Strategic Models:**
- [Customer Awareness Cycle](../models/customer-awareness-cycle.md) - Language/focus by stage
- [Golden Circle](../models/golden-circle.md) - WHY-HOW-WHAT structure
- [Action Mapping](../models/action-mapping.md) - What action must content enable?
- [Kathy Sierra Badass Users](../models/kathy-sierra-badass-users.md) - Empowerment framing
**Whiteport Methods:**
- [Value Trigger Chain](value-trigger-chain-guide.md) - Strategic context for content
**Workflows:**
- [Content Creation Workshop](../../workflows/shared/content-creation-workshop/content-creation-workshop-guide.md) - Using purpose in content generation
---
**Make every word earn its place. Define its job.** 🎯

27
src/modules/wds/docs/method/phase-1-product-exploration-guide.md
View File

@ -1,4 +1,4 @@
# Phase 1: Product Exploration (Product Brief) (Project brief)
# Phase 1: Product Exploration
**Agent:** Saga the Analyst
**Output:** `A-Product-Brief/` (or your configured prefix)
@ -23,6 +23,15 @@ Your Product Brief includes:
- **Solution Approach** - The "how" that enables development
- **Success Criteria** - The "what" that measures progress
- **Market Positioning** - How you're different (optional: ICP framework)
- **Value Trigger Chain (VTC)** - Strategic benchmark created after vision and positioning
**The VTC (Step 4):**
After capturing your vision and positioning, you'll create a [Value Trigger Chain](./value-trigger-chain-guide.md) - a strategic summary that serves as a benchmark for all subsequent discovery work. It captures:
- Business Goal → Solution → User → Driving Forces → Customer Awareness
This early VTC ensures all remaining discovery (business model, success criteria, etc.) aligns with your core strategy. If anything contradicts the VTC during discovery, either the VTC needs refinement or the discovery finding doesn't serve your strategy.
---
@ -150,4 +159,20 @@ See: `examples/dog-week-patterns/A-Product-Brief/` for a complete Product Brief
---
## Related Resources
**Method Guides:**
- [Value Trigger Chain Guide](./value-trigger-chain-guide.md) - Creating your strategic benchmark (Step 4)
- [Phase 2: Trigger Mapping Guide](./phase-2-trigger-mapping-guide.md) - Deep user psychology (next phase)
**Strategic Models:**
- [Customer Awareness Cycle](../models/customer-awareness-cycle.md) - Understanding user awareness stages (used in VTC)
- [Golden Circle](../models/golden-circle.md) - WHY, HOW, WHAT framework (useful for vision)
**Workflows:**
- Product Brief Workflow: `workflows/1-project-brief/project-brief/complete/workflow.md`
- Pitch & Signoff Workflow: `workflows/1-project-brief/alignment-signoff/workflow.md`
---
_Phase 1 of the Whiteport Design Studio method_

56
src/modules/wds/docs/method/phase-2-trigger-mapping-guide.md
View File

@ -1,4 +1,4 @@
# Phase 2: Trigger map
# Phase 2: Trigger Mapping
**Agent:** Saga the Analyst
**Output:** `B-Trigger-Map/` (or your configured prefix)
@ -144,11 +144,45 @@ For each user type:
This reveals:
- **Positive Triggers** - What motivates action
- **Negative Triggers** - What prevents engagement
- **Positive Triggers** - What motivates action (wishes, aspirations)
- **Negative Triggers** - What prevents engagement (fears, frustrations)
- **Emotional Drivers** - The psychology behind decisions
- **Behavioral Patterns** - When and why they act
**Understanding Usage Goals vs. Context:**
Usage goals are **contextual** - they activate based on the specific usage situation:
**Example: Golfer at Dubai Golf Resort**
A golfer is a person with many life roles, but in the context of booking a golf range, only their golf-related goals matter:
*Usage goals (in golf booking context):*
- Wish to improve their swing
- Wish to enjoy premium facilities
- Fear of wasting money on low-quality experience
*Other life goals (out of scope):*
- Their parenting goals don't matter here
- Their career ambitions are irrelevant
- Their financial planning is separate
**Why This Matters:**
The same person has different active goals in different contexts. A golf resort's Trigger Map focuses on the usage situation it serves, not the person's entire life.
**Cross-Context Opportunities:**
Sometimes multiple contexts can overlap strategically:
*Example: Golf Resort with Restaurant*
- **Golf Booking Context:** Golfer wants premium experience
- **Restaurant Context:** Same golfer is now hungry after playing
- **Value Chain Opportunity:** "35% restaurant booking rate - Provide golfers with free drink - Golfer - Want to feel taken care of / Not leave hungry"
The person is the same, but their **active goals shift** with the context. Smart businesses can create value chains across contexts.
### Stage 4: Visual Strategy Map (15-20 minutes)
Saga helps build the complete trigger map:
@ -319,4 +353,20 @@ See: `examples/dog-week-patterns/B-Trigger-Map/` for a complete Trigger Map with
---
## Related Resources
**Method Guides:**
- [Value Trigger Chain Guide](./value-trigger-chain-guide.md) - Extracting VTCs from Trigger Map
- [Phase 1: Product Exploration](./phase-1-product-exploration-guide.md) - Strategic foundation (prerequisite)
- [Phase 4: UX Design Guide](./phase-4-ux-design-guide.md) - Using Trigger Map in scenarios
**Foundational Models:**
- [Impact/Effect Mapping](../models/impact-effect-mapping.md) - The foundational methodology Trigger Mapping derives from
- [Customer Awareness Cycle](../models/customer-awareness-cycle.md) - Understanding user awareness stages
**Workflows:**
- Trigger Mapping Workflow: `workflows/2-trigger-mapping/` (see workflow files)
---
_Phase 2 of the Whiteport Design Studio method_

2
src/modules/wds/docs/method/phase-3-prd-platform-guide.md
View File

@ -1,6 +1,6 @@
# Phase 3: PRD Platform (Technical Foundation)
**Agent:** Freyja the PM
**Agent:** Freya the PM
**Output:** `C-Requirements/` (or your configured prefix)
---

64
src/modules/wds/docs/method/phase-4-ux-design-guide.md
View File

@ -1,13 +1,13 @@
# Phase 4: UX Design (UX-Sketches & Usage Scenarios)
**Agent:** Freyja the WDS Designer
**Agent:** Freya the WDS Designer
**Output:** `C-Scenarios/` (or your configured prefix)
---
## What This Phase Does
UX Design transforms ideas into detailed visual specifications. Working with Freyja, you conceptualize, sketch, and specify every interaction until your design can be logically explained without gaps.
UX Design transforms ideas into detailed visual specifications. Working with Freya, you conceptualize, sketch, and specify every interaction until your design can be logically explained without gaps.
**The key insight:** Designs that can be logically explained without gaps are easy to develop. The specification process reveals gaps in your thinking early - when they're easy to address.
@ -27,24 +27,45 @@ For each scenario/page:
---
## How Freyja the WDS Designer helps you design software
## How Freya the WDS Designer helps you design software
### 4A: Scenario Exploration
### 4A: Scenario Initialization & Exploration
**When:** Discovering the Concept, the process, flow screen or component solution together, before sketching begin
**When:** Starting a new scenario - before sketching begins
Freyja helps you:
**The Scenario Init Process** (6 steps):
1. Feature selection - Which feature delivers value?
2. Entry point - Where does user encounter it?
3. Mental state - How are they feeling?
4. Mutual success - What's winning for both sides?
5. Shortest path - Minimum steps to success
6. **Create VTC** - Crystallize scenario strategy
See: [Scenario Initialization Guide](../workflows/4-ux-design/scenario-init/scenario-init/00-SCENARIO-INIT-GUIDE.md)
**Value Trigger Chain for Each Scenario:**
Each scenario gets its own [VTC](./value-trigger-chain-guide.md) that serves as strategic guidance:
- Extracted from Trigger Map (if Selection Workshop - 10-15 mins)
- Created from scratch (if Creation Workshop - 20-30 mins)
The VTC guides every page, every interaction, every word in the scenario.
**Then Exploration:**
Freya helps you:
- Think through the user's journey
- Explore content and feature options
- Explore content and feature options
- Consider psychological triggers from your Trigger Map
- Reference the scenario's VTC for driving forces
- Arrive at a clear solution ready for sketching
### 4B: UI Sketch Analysis
**When:** You have a sketch and you need feedback on it
Freyja helps you:
Freya helps you:
- Analyze what the sketch shows
- Ask clarifying questions
@ -54,7 +75,7 @@ Freyja helps you:
**When:** Design is clear, need development-ready specs
Freyja helps you:
Freya helps you:
- Document every detail systematically
- Assign Object IDs for testing
@ -65,7 +86,7 @@ Freyja helps you:
**When:** Specifications complete, and we make the sketch come alive to test the concept
Freyja helps you:
Freya helps you:
- Create interactive prototypes
- Test the design in browser
@ -77,7 +98,7 @@ Freyja helps you:
**When:** Page design is complete, before moving to the next scenario
Freyja helps you:
Freya helps you:
- Identify what features this page requires
- Add functional requirements to the PRD
@ -292,7 +313,7 @@ Your specifications enable:
## Tips for Great Sessions
**Think out loud with Freyja**
**Think out loud with Freya**
- Share your reasoning
- Explore alternatives together
@ -326,4 +347,23 @@ See: `examples/dog-week-patterns/C-Scenarios/` for complete scenario specificati
---
## Related Resources
**Method Guides:**
- [Value Trigger Chain Guide](./value-trigger-chain-guide.md) - Creating VTCs for each scenario
- [Phase 2: Trigger Mapping Guide](./phase-2-trigger-mapping-guide.md) - Source for VTC extraction
- [Phase 3: PRD Platform Guide](./phase-3-prd-platform-guide.md) - Technical constraints
- [Phase 5: Design System Guide](./phase-5-design-system-guide.md) - Component extraction (parallel)
**Strategic Models:**
- [Customer Awareness Cycle](../models/customer-awareness-cycle.md) - User awareness positioning (used in VTC)
- [Action Mapping](../models/action-mapping.md) - User actions in scenario steps
- [Kathy Sierra: Badass Users](../models/kathy-sierra-badass-users.md) - Making users feel capable
**Workflows:**
- Scenario Initialization: `workflows/4-ux-design/scenario-init/scenario-init/00-SCENARIO-INIT-GUIDE.md`
- VTC Workshop: `workflows/shared/vtc-workshop/vtc-workshop-guide.md`
---
_Phase 4 of the Whiteport Design Studio method_

511
src/modules/wds/docs/method/phase-6-integration-guide.md
View File

@ -1,511 +0,0 @@
# Phase 6: PRD Finalization
**Agent:** Freyja the PM
**Output:** Complete PRD in `C-Requirements/` + Handoff materials in `E-UI-Roadmap/`
**Duration:** 2-4 hours
---
## What This Phase Does
PRD Finalization compiles all the functional requirements discovered during Phase 4 into a complete, development-ready Product Requirements Document.
**The key insight:** Your PRD started in Phase 3 with platform/infrastructure. During Phase 4, each page added functional requirements (via step 4E). Now you organize, prioritize, and finalize everything for development handoff.
By the end, developers have a complete PRD covering both technical foundation and all UI-driven features.
---
## What You'll Create
**Updated PRD (C-Requirements/) includes:**
**From Phase 3 (Technical Foundation):**
- Platform architecture
- Data model
- Integration map
- Technical proofs of concept
- Experimental endpoints
- Security framework
**Added from Phase 4 (Functional Requirements):**
- All features discovered during page design
- Page-to-feature traceability
- Priority rankings
- Feature dependencies
- Implementation notes
**New in Phase 6:**
- Feature organization by epic/area
- Development sequence
- MVP scope definition
- Technical dependencies mapped
**Handoff Package (E-UI-Roadmap/):**
- Priority sequence document
- Scenario-to-development mapping
- Component inventory (if Design System enabled)
- Open questions for dev team
---
## How It Works
### Stage 1: Review Collected Requirements (30-45 minutes)
**Gather all functional requirements added during Phase 4:**
Go through each scenario specification and extract the requirements added in step 4E:
```
From 1.1-Start-Page:
- User authentication system
- Session management
- Password reset flow
From 1.2-Sign-Up:
- Email validation (format, domain check, duplicate prevention)
- Phone number validation with country code
- Account activation via email
From 2.1-Dog-Calendar:
- Availability calendar API
- Real-time updates via WebSocket
- Date/time localization
```
**Compile into master feature list** with page references preserved.
### Stage 2: Organize by Epic/Feature Area (30-45 minutes)
**Group related features together:**
```markdown
## Epic 1: User Authentication & Account Management
### Features
**User Registration**
- Required by: 1.2-Sign-Up
- Email validation (format, domain, duplicates)
- Phone validation with country codes
- Account activation flow
**User Login**
- Required by: 1.1-Start-Page, multiple pages
- Email/password authentication
- Session management (30-day persistence)
- "Remember me" functionality
**Password Management**
- Required by: 1.1-Start-Page (reset link)
- Password reset via email
- Password strength validation
- Secure token generation
```
### Stage 3: Define Priorities & Sequence (45-60 minutes)
**Based on your Phase 2 Feature Impact Analysis:**
Reference the scoring you did in Phase 2 to inform priorities:
```markdown
## Development Sequence
### Priority 1: MVP - Core User Flow
**Target:** Weeks 1-4
Features from Epic 1 (Authentication) + Epic 2 (Core Booking):
- User registration (Impact Score: 14)
- User login (Impact Score: 16)
- Availability calendar (Impact Score: 16)
- Basic booking flow (Impact Score: 18)
**Why this order:**
Serves Priority 1 target group, addresses highest-impact drivers.
### Priority 2: Enhanced Features
**Target:** Weeks 5-8
Features from Epic 3 (Payments) + Epic 4 (Notifications):
- Payment processing (Impact Score: 12)
- Booking confirmations (Impact Score: 11)
- Calendar sync (Impact Score: 8)
```
### Stage 4: Map Dependencies (20-30 minutes)
**Technical dependencies between features:**
```markdown
## Feature Dependencies
**Booking Flow** depends on:
- ✓ User authentication (must be logged in)
- ✓ Availability calendar (must see open slots)
- ⚠️ Payment system (can launch with "pay in person" temporarily)
- ⚠️ Notifications (can launch without, add later)
**Recommendation:** Launch MVP with auth + calendar, add payments in Sprint 2.
```
### Stage 5: Create Handoff Package (30-45 minutes)
**Organize for development team:**
In `E-UI-Roadmap/` folder, create:
1. **`priority-sequence.md`** - What to build when and why
2. **`scenario-to-epic-mapping.md`** - How WDS scenarios map to dev epics
3. **`component-inventory.md`** (if Design System enabled) - All components needed
4. **`open-questions.md`** - Decisions for dev team to make
---
## The Complete PRD Structure
Your finalized PRD in `C-Requirements/` combines all phases:
```markdown
# Product Requirements Document
## 1. Technical Foundation (from Phase 3)
### Platform Architecture
- Technology stack decisions
- Infrastructure approach
- Hosting and deployment
### Data Model
- Core entities and relationships
- Database schema
- Data flow diagrams
### Integrations
- External services (Google Maps, Stripe, etc.)
- API specifications
- Authentication providers
### Security & Performance
- Authentication/authorization approach
- Data protection
- Performance requirements
- Proofs of concept results
## 2. Functional Requirements (from Phase 4)
### Epic 1: User Authentication & Account Management
**Features:**
- User registration (Required by: 1.2-Sign-Up)
- User login (Required by: 1.1-Start-Page, multiple)
- Password management (Required by: 1.1-Start-Page)
[Detailed specifications for each feature]
### Epic 2: [Next Epic]
[...]
## 3. Development Roadmap (from Phase 6)
### Priority 1: MVP (Weeks 1-4)
- Features list with Impact Scores
- Why these first (references Trigger Map)
- Timeline estimate
- Dependencies
### Priority 2: Enhanced Features (Weeks 5-8)
[...]
## 4. Dependencies & Constraints
- Technical dependencies between features
- Design constraints from Phase 4
- Third-party limitations discovered in Phase 3
## 5. Success Metrics
- Business goals from Phase 1
- Feature-specific KPIs
- How we measure success
```
---
## Continuous vs. Final Handoff
**The pattern:**
- **Phase 3:** Initial PRD with technical foundation
- **Phase 4:** PRD grows with each page (step 4E adds requirements)
- **Phase 6 (First time):** Organize MVP scope from completed scenarios
- Create first handoff package
- Development can begin
- **Phase 4 continues:** More pages designed, more requirements added
- **Phase 6 (Ongoing):** Update PRD priorities, create new handoff packages
- Weekly or bi-weekly updates
- Keep dev team synced
**You can run Phase 6 multiple times as design progresses.**
---
## When to Use This Phase
**First PRD Finalization when:**
- You have MVP-level scenarios complete (enough for dev to start)
- Core user flows are specified
- Critical features are documented
- Enough work for 2-4 week sprint
**Ongoing PRD Updates as:**
- Additional scenarios complete
- New feature areas designed
- Priorities shift based on learning
- Sprint planning needs updated scope
**Timeline example:**
```
Week 1-2: Phase 1-3 (Strategy, Research, Platform foundation)
Week 3-4: Phase 4 Scenarios 1-3 (Core MVP flows)
Week 5: Phase 6 First Finalization
└──► PRD v1.0: MVP scope ready
└──► Development Sprint 1 begins
Week 6-7: Phase 4 Scenarios 4-6 (Additional features)
Phase 5 Design System (extract components)
Week 8: Phase 6 Update
└──► PRD v1.1: Sprint 2 scope added
└──► Development Sprint 2 begins
Week 9+: Design continues in parallel with development
Regular Phase 6 updates for new sprints
```
**The beauty:** Design doesn't block development. You hand off in waves.
Complete list for test automation:
| Scenario | Object ID | Element Type | Notes |
| -------- | --------------------- | ------------ | ------------------ |
| 1.1 | `welcome-hero-cta` | Button | Primary action |
| 1.1 | `welcome-signin-link` | Link | Secondary action |
| 1.2 | `signin-email-input` | Input | Required field |
| 1.2 | `signin-error-email` | Error | Validation message |
---
## How It Works
### Review Completeness
Before handoff, verify:
- All scenarios specified and reviewed
- Design system covers all components
- Object IDs assigned throughout
- Multilingual content complete
- HTML prototypes validated
### Identify Priorities
With Freyja, map your Trigger Map priorities to development order:
- Which user triggers are most critical?
- What's the minimum viable experience?
- What can wait for later releases?
### Document Technical Context
Capture what developers need to know:
- Design decisions and their rationale
- Technical constraints discovered during design
- Interaction patterns that need special attention
- Performance considerations
### Create the Handoff
Organize everything into the UI Roadmap folder:
- Clear priority sequence
- Complete component inventory
- Technical notes and open questions
- Verification checklist
---
## The Handoff Checklist
```markdown
## Design Handoff Verification
### Product Foundation
- [ ] Product Brief complete and current
- [ ] Trigger Map with prioritized users and goals
- [ ] ICP clearly defined
### Requirements
- [ ] PRD with technical specifications
- [ ] Platform architecture documented
- [ ] Integration requirements listed
### Visual Design
- [ ] All scenarios have specifications
- [ ] All pages have Object IDs
- [ ] States documented (empty, loading, error, success)
### Design System
- [ ] All components documented
- [ ] Design tokens defined
- [ ] Usage guidelines written
### Validation
- [ ] HTML prototypes created for key scenarios
- [ ] Stakeholder review complete
- [ ] Open questions documented
### Ready for Development ✅
```
---
## When to Use This Phase
**First handoff when:**
- You have enough scenarios for MVP
- Core user flows are specified
- Critical components are documented
- Developers can start building foundational features
**Ongoing handoffs as:**
- Each major scenario completes
- New component patterns emerge
- Design decisions affect development
- Sprint planning needs updated priorities
**The rhythm:**
```
Week 1-2: Design Phase 1-3 (Strategy, Research, Platform)
Week 3-4: Design Phase 4 Scenarios 1-2 (Core flows)
└──► First Handoff: MVP scope
Week 5-6: Design Phase 4 Scenarios 3-4
Design Phase 5 (Components from 1-2)
└──► Second Handoff: Additional features
Week 7+: Design continues...
Development builds in parallel
└──► Ongoing handoffs as design progresses
```
**You DON'T need to finish all design before handing off.**
Development and design work in parallel streams, with regular sync points.
---
## What to Prepare
Bring:
- Completed scenario specifications (Phase 4)
- Design System (Phase 5)
- PRD (Phase 3)
- Trigger Map priorities (Phase 2)
---
## What Comes Next
Your UI Roadmap enables:
- **Development kickoff** - Clear starting point
- **Sprint planning** - Prioritized work items
- **Test automation** - Object ID inventory
- **QA validation** - Specifications to verify against
---
## Tips for Great Sessions
**Think from dev perspective**
- What questions will developers have?
- What decisions can't you make for them?
- What context will save them time?
**Be explicit about priorities**
- Not everything is Priority 1
- Make trade-offs visible
- Connect priorities to business goals
**Document the unknowns**
- Open questions are valuable
- Don't pretend certainty you don't have
- Let dev team contribute decisions
**Keep it updated**
- Handoff is ongoing, not one-time
- Update as design evolves
- Maintain as source of truth
---
## Integration with BMM
When handing off to BMad Method (BMM) for development:
```
WDS → E-UI-Roadmap/ → BMM Architecture & Stories
```
The UI Roadmap provides:
- Context for architecture decisions
- Specifications for story creation
- Priorities for sprint planning
- Test automation foundations
---
## Example Output
See: `examples/dog-week-patterns/E-UI-Roadmap/` for a complete UI Roadmap from a real project.
---
_Phase 6 of the Whiteport Design Studio method_

4
src/modules/wds/docs/method/phase-6-prd-finalization-guide.md
View File

@ -1,6 +1,6 @@
# Phase 6: PRD Finalization (Complete PRD)
**Agent:** Freyja the PM
**Agent:** Freya the PM
**Output:** Complete PRD in `C-Requirements/` + Handoff materials in `E-UI-Roadmap/`
---
@ -332,7 +332,7 @@ Before handoff, verify:
### Identify Priorities
With Freyja, map your Trigger Map priorities to development order:
With Freya, map your Trigger Map priorities to development order:
- Which user triggers are most critical?
- What's the minimum viable experience?

466
src/modules/wds/docs/method/tone-of-voice-guide.md Normal file
View File

@ -0,0 +1,466 @@
# Tone of Voice Guide
**Consistent communication personality for UI microcopy and system messages**
---
## What is Tone of Voice?
**Tone of Voice (ToV)** defines your product's communication personality—how your brand "speaks" to users through all UI microcopy and system messages.
It's the consistent voice users hear in:
- Form labels and placeholders
- Button text
- Error and success messages
- Empty states
- Loading states
- Tooltips and instructions
- System notifications
---
## Why Tone of Voice Matters
### Creates Consistency
- All UI microcopy feels like it comes from the same "person"
- Users develop a relationship with your brand voice
- Professional, cohesive experience
### Builds Brand Personality
- Differentiates you from competitors
- Reinforces brand values and positioning
- Creates emotional connection
### Guides Decisions
- Designers/developers know how to write microcopy
- No need to debate every button label
- Faster, more consistent implementation
---
## Tone of Voice vs Strategic Content
### Tone of Voice (Product-Wide Consistency)
**Applies to UI Microcopy:**
- ✅ Form field labels
- ✅ Button text (standard actions)
- ✅ Error messages
- ✅ Success/confirmation messages
- ✅ Empty states
- ✅ Loading states
- ✅ Tooltips
- ✅ System notifications
- ✅ Navigation labels
**Characteristics:**
- Consistent across entire product
- Defined once in Product Brief
- Applied systematically
- Based on brand personality and target users
---
### Strategic Content (Context-Specific Purpose)
**Applies to Marketing/Feature Content:**
- ❌ Headlines and hero sections
- ❌ Feature descriptions
- ❌ Value propositions
- ❌ Testimonials and case studies
- ❌ Landing page content
- ❌ Onboarding narratives
**Characteristics:**
- Varies by page/context
- Created using Content Creation Workshop
- Purpose-driven (each piece has a job)
- Uses strategic models (CAC, Golden Circle, Badass Users, etc.)
---
## Defining Your Tone of Voice
### Step 1: Choose 3-5 Tone Attributes
**Common attributes:**
- Friendly vs Professional
- Casual vs Formal
- Playful vs Serious
- Warm vs Cool
- Technical vs Accessible
- Empathetic vs Straightforward
- Quirky vs Traditional
- Authoritative vs Humble
**Example combinations:**
**Consumer Social App:**
- Friendly
- Casual
- Playful
- Warm
**Enterprise B2B SaaS:**
- Professional
- Clear
- Supportive
- Authoritative
**Healthcare App:**
- Empathetic
- Warm
- Professional
- Reassuring
**Developer Tool:**
- Technical
- Precise
- Straightforward
- Respectful
### Step 2: Write Examples
Show don't tell. For each tone attribute, provide examples:
**Format:**
```
[Tone Attribute]: [Brief description]
Examples:
❌ Generic: [Standard industry phrasing]
✅ Our Tone: [Rewritten in your voice]
```
### Step 3: Create Guidelines
**Do's and Don'ts:**
Clear rules for what fits your tone and what doesn't:
- Do use contractions / Don't be overly formal
- Do acknowledge user feelings / Don't be robotic
- Do keep it concise / Don't over-explain
---
## Tone of Voice by Context
### Error Messages
**Generic (no tone):**
- "Error: Invalid input"
- "404 Not Found"
- "Authentication failed"
**Friendly & Empathetic:**
- "Hmm, that doesn't look quite right. Mind double-checking?"
- "We couldn't find that page. Let's get you back on track."
- "We couldn't log you in. Check your email and password?"
**Professional & Clear:**
- "Please enter a valid email address"
- "This page doesn't exist. Return to dashboard?"
- "Login failed. Verify your credentials and try again"
**Technical & Precise:**
- "Invalid email format. Expected: name@domain.com"
- "Resource not found. Check URL and retry"
- "Authentication error: Invalid credentials provided"
---
### Success Messages
**Generic (no tone):**
- "Success"
- "Operation completed"
- "Saved"
**Friendly & Empathetic:**
- "You're all set! 🎉"
- "Perfect! Your changes are saved."
- "Nice work! Everything's updated."
**Professional & Clear:**
- "Changes saved successfully"
- "Your profile has been updated"
- "Settings applied"
**Technical & Precise:**
- "Operation completed: Profile updated"
- "Save successful. Last modified: [timestamp]"
- "Configuration saved to database"
---
### Button Text
**Generic (no tone):**
- Submit
- Continue
- Cancel
- Delete
**Friendly & Empathetic:**
- Let's go!
- Next step
- Never mind
- Remove this
**Professional & Clear:**
- Confirm
- Proceed
- Go back
- Delete item
**Technical & Precise:**
- Execute
- Advance
- Abort
- Remove record
---
### Empty States
**Generic (no tone):**
- "No results"
- "Empty"
- "Nothing found"
**Friendly & Empathetic:**
- "Nothing here yet. Ready to add your first item?"
- "Your inbox is empty—enjoy the peace!"
- "No matches found. Try a different search?"
**Professional & Clear:**
- "No items to display. Add your first item to get started."
- "Your inbox is empty."
- "No results match your search criteria."
**Technical & Precise:**
- "Query returned 0 results"
- "No records in database"
- "Search yielded no matches for specified criteria"
---
## How to Apply Tone of Voice
### During Product Brief (Phase 1)
1. Agent analyzes product, users, positioning
2. Agent suggests appropriate tone attributes
3. Agent provides examples of tone in action
4. User confirms/refines
5. Tone of Voice documented in Product Brief
### During UI Design (Phase 4)
1. Designer creates UI elements
2. For standard microcopy (labels, buttons, errors), apply ToV
3. For strategic content (headlines, features), use Content Creation Workshop
4. ToV ensures all microcopy feels consistent
### During Development
1. Developers reference ToV guidelines
2. Write new microcopy following established tone
3. No need to ask designer for every button label
4. Consistency maintained automatically
---
## Examples by Product Type
### Consumer Social App: FriendCircle
**Tone Attributes:** Friendly, Casual, Playful, Warm
**Error Messages:**
- ✅ "Oops! We couldn't upload that photo. Try again?"
- ✅ "Hmm, we're having trouble connecting. Check your wifi?"
**Button Text:**
- ✅ "Share with friends"
- ✅ "Love it!"
- ✅ "Maybe later"
**Empty States:**
- ✅ "No posts yet. Be the first to share!"
- ✅ "Your feed is empty. Follow some friends to get started!"
---
### Enterprise SaaS: TaskFlow
**Tone Attributes:** Professional, Clear, Supportive, Efficient
**Error Messages:**
- ✅ "Please enter a valid project name"
- ✅ "We couldn't save your changes. Check your connection and try again"
**Button Text:**
- ✅ "Create project"
- ✅ "Save changes"
- ✅ "Cancel"
**Empty States:**
- ✅ "No projects yet. Create your first project to get started."
- ✅ "All tasks complete. Well done!"
---
### Healthcare App: WellPath
**Tone Attributes:** Empathetic, Warm, Professional, Reassuring
**Error Messages:**
- ✅ "We couldn't record your reading. Please try again, or contact support if this continues"
- ✅ "That date doesn't look quite right. Check and try again?"
**Button Text:**
- ✅ "Log today's reading"
- ✅ "I'm done"
- ✅ "Skip for now"
**Empty States:**
- ✅ "No readings yet. Let's record your first one."
- ✅ "You're all caught up. Great work staying on track!"
---
### Developer Tool: CodeStream
**Tone Attributes:** Technical, Precise, Straightforward, Respectful
**Error Messages:**
- ✅ "Build failed: Syntax error on line 47"
- ✅ "API request failed: Invalid authentication token"
**Button Text:**
- ✅ "Run build"
- ✅ "Deploy"
- ✅ "Abort"
**Empty States:**
- ✅ "No builds configured. Add your first build pipeline."
- ✅ "Query returned 0 results"
---
## Common Mistakes
### ❌ Inconsistent Tone
**Problem:** Mixing tones within the same product
**Example:**
- Error: "Oops! Something went wrong 😅" (playful)
- Success: "Operation completed successfully" (formal)
**Fix:** Choose one tone and apply it consistently
---
### ❌ Over-Personification
**Problem:** Treating software like a person with feelings
**Example:**
- "I'm sorry, I couldn't do that" (who is "I"?)
- "I'm confused by your input"
**Fix:** Keep focus on user and their action
- "We couldn't complete that action"
- "Please check your input and try again"
---
### ❌ Forced Personality
**Problem:** Trying too hard to be clever/funny
**Example:**
- "Whoopsie-daisy! Our hamsters fell off their wheels!"
- "Houston, we have a problem..."
**Fix:** Be helpful first, personality second
- "We're experiencing technical difficulties. Please try again"
---
### ❌ Tone-Deaf to Context
**Problem:** Same tone regardless of severity
**Example:**
- Critical error: "Uh oh, looks like we lost your data! 🙈"
- (Playful tone inappropriate for serious situation)
**Fix:** Adjust tone for serious/critical situations
- "We encountered an error saving your data. Please contact support immediately"
---
## Testing Your Tone of Voice
### Consistency Check
Write 10 different UI messages (errors, success, buttons, empty states). Do they all sound like they're from the same "person"?
### User Testing
Show microcopy examples to target users. Ask:
- "How does this make you feel?"
- "Does this match how you'd expect [brand] to communicate?"
- "Is this helpful/clear/respectful?"
### Edge Cases
Test tone in difficult situations:
- Critical errors
- Data loss
- Payment failures
- Account suspensions
Does your tone still work, or does it feel inappropriate?
---
## Integration with WDS
### Phase 1: Product Brief
- **Step 10.5:** Define Tone of Voice
- Agent suggests tone based on product context
- User confirms/refines
- ToV documented in brief
### Phase 4: UX Design
- **UI Microcopy:** Apply ToV guidelines
- **Strategic Content:** Use Content Creation Workshop
- Clear distinction prevents confusion
### Development
- Reference ToV guidelines from Product Brief
- Apply consistently to all microcopy
- No need for case-by-case decisions
---
## Resources
**Related WDS Guides:**
- [Content Purpose Guide](content-purpose-guide.md) - For strategic content
- [Content Creation Workshop](../../workflows/shared/content-creation-workshop/content-creation-workshop-guide.md) - For headlines/features
- [Product Brief Workflow](../../workflows/1-project-brief/) - Where ToV is defined
**External Resources:**
- Mailchimp's Voice & Tone Guide
- GOV.UK Content Design Principles
- Nielsen Norman Group: Tone of Voice articles
---
**Make every microcopy decision easier. Define your tone once, apply it everywhere.** 🎯

474
src/modules/wds/docs/method/value-trigger-chain-guide.md Normal file
View File

@ -0,0 +1,474 @@
# Value Trigger Chain (VTC)
**A lightweight strategic framework for connecting business goals to user psychology**
---
## What It Is
A **Value Trigger Chain (VTC)** is the minimum viable strategic context for creating purposeful design. It's a selected path through your strategic landscape that shows:
- **Business Goal** - What success looks like for the organization
- **Solution** - The specific thing being built to achieve that goal
- **User** - Who will use this solution
- **Driving Forces** - What motivates that user (wishes and fears)
- **Customer Awareness** - Where the user starts and where we want to move them
**Why VTC Matters:**
Without explicit strategic understanding of the business behind a digital product and the reasons why a user might wish to benefit from using it, design decisions become mere guess work ("I like this") rather than purposeful ("This serves our business goal by triggering the user's wish to X"). While you *can* design without a VTC, you risk:
- Creating beautiful but ineffective solutions
- Making decisions based on personal preference rather than user psychology
- Missing opportunities to align design with business goals
- Difficulty explaining or defending design choices
- Lower conversion rates and user satisfaction
**What VTC Provides:**
A VTC is a heuristic - a quick strategic shortcut. True strategic grounding requires business analysis, user research, and ideally a full Trigger Map with prioritization. However, as a rapid way to establish rough direction, VTC is remarkably effective:
- Disqualifies catastrophic ideas early ("This doesn't serve any user driving force")
- Gets discussions moving in a productive direction
- Provides enough context for meaningful design decisions
- Far better than no strategic grounding at all
- Can evolve into a full Trigger Map when project scope warrants it
Think of it as strategic scaffolding: sufficient to build on, but not the complete architectural blueprint.
**Structure:**
```
Business Goal → Solution → User → Driving Forces → Customer Awareness Progression
```
**Example:**
| Business Goal | Solution | User | Driving Forces | Customer Awareness |
|--------------|----------|------|----------------|--------------------|
| 500 newsletter signups | Landing page with trend insights | Harriet (hairdresser, ambitious, small town) | • Wish to be local beauty authority<br>• Fear of missing industry trends | Problem Aware → Product Aware |
---
## Why It Matters
### The Problem Without VTC
Designers often create without strategic grounding:
- Content lacks purpose
- Messaging feels generic
- Design decisions are subjective ("I like this color")
- No clear success criteria
- Hard to prioritize features or content
### The Solution With VTC
Every design decision has strategic context:
- Content targets specific driving forces
- Messaging addresses user psychology
- Design serves measurable goals
- Clear prioritization based on VTC impact
- Objective evaluation of design effectiveness
**The core insight:** Value is TRIGGERED when a user's driving forces are TRIGGERED. The VTC makes this triggering intentional rather than accidental.
---
## How It's Valuable in Strategic Design
### 1. **Prioritization**
When you have multiple design options, ask: "Which best serves our VTC?" Clear answer emerges.
### 2. **Content Creation**
Every piece of content can reference its VTC to ensure strategic alignment and emotional resonance.
### 3. **Stakeholder Alignment**
VTCs create shared understanding. Everyone knows WHY we're building WHAT for WHOM.
### 4. **Measurement**
Each VTC element is measurable:
- Business Goal: Quantifiable metric
- User: Identifiable segment
- Driving Forces: Observable behaviors
- Customer Awareness: Progression tracking
### 5. **Scalability**
- 1 VTC: Quick prototype
- 3 VTCs: Focused product
- 10+ VTCs: Complex platform with multiple user types
Start small, scale strategically.
---
## Derived From
The VTC method derives from **Effect Management** (inUse, Sweden) and **Impact Mapping** (Gojko Adzic), which pioneered the concept of visually connecting business goals to user behaviors.
VTC is Whiteport's lightweight adaptation, adding:
- **Customer Awareness positioning** (from Eugene Schwartz)
- **Negative driving forces** (fears and frustrations)
- **Standalone usability** (can exist without full Trigger Map)
**Related Whiteport Methods:**
- [Trigger Mapping Guide](./phase-2-trigger-mapping-guide.md) - Comprehensive version containing multiple VTCs
- [Scenario Definition](./phase-4-ux-design-guide.md) - VTCs anchor each scenario
**Foundational Models:**
- [Customer Awareness Cycle](../models/customer-awareness-cycle.md) - Eugene Schwartz (positioning users)
- [Impact Mapping](../models/impact-effect-mapping.md) - Gojko Adzic (strategic connections)
---
## When to Use VTC
### Use Direct VTC When:
- **Timeline:** < 2 weeks
- **Scope:** 1-3 key flows, prototype, MVP
- **Users:** Single primary user type
- **Budget:** < $10k
- **Goal:** Quick strategic grounding without extensive mapping
### Use Full Trigger Map (Contains Many VTCs) When:
- **Timeline:** > 1 month
- **Scope:** Complex product, many scenarios
- **Users:** Multiple distinct user types
- **Budget:** > $25k
- **Goal:** Long-term strategic foundation
**The relationship:** Trigger Map = Multiple VTCs + Relationships + Prioritization
---
## How to Create a VTC
### Step 1: Define Business Goal (5 minutes)
What does success look like? Be specific and measurable.
**Good:** "500 newsletter signups in Q1"
**Bad:** "More engagement"
### Step 2: Identify Solution (2 minutes)
What are you building to achieve this goal?
**Examples:**
- Landing page with lead magnet
- Onboarding flow
- Feature upgrade prompt
- Email campaign + dashboard
### Step 3: Describe User (5 minutes)
Who will use this solution? Go beyond demographics to psychology.
**Template:**
```
[Name] ([role], [key traits])
- Context: [when/where they encounter solution]
- Current state: [what they're trying to accomplish]
```
**Example:**
```
Harriet (hairdresser, ambitious, small-town)
- Context: Late evening, researching industry trends
- Current state: Wants to stay ahead of competitors
```
### Step 4: Identify Driving Forces (10 minutes)
What motivates this user? Include both wishes (positive) and fears (negative).
**Wishes (Positive Driving Forces):**
- What do they want to achieve?
- What would make them feel successful?
- What aspirations drive their actions?
**Fears (Negative Driving Forces):**
- What do they want to avoid?
- What keeps them up at night?
- What would feel like failure?
**Example:**
- ✅ Wish to be local beauty authority
- ❌ Fear of missing industry trends
- ✅ Wish to attract premium clients
- ❌ Fear of being seen as outdated
**Pro tip:** Positive and negative are often two sides of the same coin. Include both for fuller picture.
### Step 5: Position Customer Awareness (5 minutes)
Where is this user NOW in their awareness journey? Where do we want to move them?
**Customer Awareness Stages:**
1. **Unaware** - Doesn't know problem exists
2. **Problem Aware** - Knows problem, doesn't know solutions
3. **Solution Aware** - Knows solutions exist, doesn't know yours
4. **Product Aware** - Knows your solution exists
5. **Most Aware** - Has used, loved, and advocates for your solution
**VTC Format:** `[Start] → [End]`
**Examples:**
- "Problem Aware → Solution Aware" (introducing new approach)
- "Product Aware → Most Aware" (onboarding flow)
- "Unaware → Problem Aware" (educational content)
### Step 6: Document & Validate (3 minutes)
Write your VTC in table format:
| Business Goal | Solution | User | Driving Forces | Customer Awareness |
|--------------|----------|------|----------------|--------------------|
| [goal] | [solution] | [user description] | • [positive force]<br>• [negative force]<br>• [another force] | [start] → [end] |
**Validation Questions:**
1. Is the business goal measurable?
2. Does the solution serve both the goal AND the user?
3. Are driving forces specific enough to inform design?
4. Does the customer awareness progression make sense for this solution?
5. Can we design/write content differently based on this VTC?
If you answered "no" to any question, refine that element.
---
## Using VTCs in Your Design Process
### In Project Pitch
- Define 1 simplified VTC to communicate strategic vision
- Helps stakeholders understand WHO, WHY, and HOW
### In Scenario Definition
- Assign primary VTC to each scenario
- All pages in scenario inherit this VTC by default
- Optional: Define secondary VTCs for specific page sections
### In Content Creation
- Before writing any content, identify applicable VTC
- Generate content that triggers the driving forces
- Move user along customer awareness spectrum
- Explain reasoning: "This content serves VTC-01 by..."
### In Component Specifications
- Microcopy references VTC
- Error messages address fears (negative driving forces)
- Success states celebrate wishes (positive driving forces)
### In Design Deliveries
- Show which VTC each flow serves
- Helps developers understand strategic intent
- Informs prioritization decisions
### In Testing
- Validate: Did we trigger the driving forces?
- Measure: Did user progress in customer awareness?
- Test: Does design serve the business goal?
---
## Imaginary Examples
### Example 1: SaaS Onboarding
**VTC:**
| Business Goal | Solution | User | Driving Forces | Customer Awareness |
|--------------|----------|------|----------------|--------------------|
| 60% activation rate | Interactive onboarding flow | Sarah (marketing manager, stretched thin) | • Wish to prove ROI to boss<br>• Fear of wasting time on complex tools | Product Aware → Most Aware |
**Design Implications:**
- Show ROI immediately (addresses "prove ROI" wish)
- Make first value moment < 2 minutes (addresses "fear of wasting time")
- Progress indicators show "almost done" (reduces anxiety)
- Success state: "You're ready to show your team"
### Example 2: E-commerce Product Page
**VTC:**
| Business Goal | Solution | User | Driving Forces | Customer Awareness |
|--------------|----------|------|----------------|--------------------|
| 15% conversion rate | Product page with social proof | James (first-time buyer, cautious) | • Wish to make smart purchase<br>• Fear of buying wrong product | Solution Aware → Product Aware |
**Design Implications:**
- Detailed specs (addresses "smart purchase" wish)
- Return policy prominent (reduces "wrong product" fear)
- Customer reviews front and center (social proof reduces risk)
- Comparison table (helps make informed decision)
### Example 3: Newsletter Signup (Context-Specific Goals)
**VTC:**
| Business Goal | Solution | User | Driving Forces | Customer Awareness |
|--------------|----------|------|----------------|--------------------|
| 500 signups | Landing page with trend insights | Harriet (hairdresser, ambitious, small-town) | • Wish to be local beauty authority<br>• Fear of missing industry trends | Problem Aware → Product Aware |
**Understanding Context:**
Harriet has many life goals (parent, business owner, friend), but in the context of **discovering a beauty trends newsletter**, only her professional goals are active:
*Active in this context:*
- Professional status and influence
- Staying current with industry
- Competitive advantage locally
*Not active in this context:*
- Her parenting goals
- Her financial planning
- Her social life
**Design Implications:**
- Headline: "Never Miss a Trend" (addresses fear directly in THIS context)
- Subhead: "Become Your Town's Beauty Authority" (speaks to wish in THIS situation)
- Lead magnet: "This Week's Top 5 Trends" (immediate professional value)
- Testimonial: "My clients always ask how I stay so current!"
**Why Context Matters:**
The same landing page wouldn't mention:
- "Balance work and family" (different context)
- "Manage salon finances" (different usage situation)
- "Plan your social calendar" (different need)
VTCs focus on the **active goals in the specific usage situation**.
---
## Real Applications
### WDS Presentation Project
The WDS Presentation landing page uses VTCs to guide content creation and design decisions.
**See:** [WDS Presentation Example](../examples/WDS-Presentation/)
**VTCs Defined:**
- Stina the Strategist (designer wanting better tools)
- Lars the Leader (executive wanting team efficiency)
- Felix the Full-Stack (developer wanting clearer specs)
Each section of the page targets specific driving forces from these VTCs, demonstrating how strategic grounding shapes content and design.
**Explore:**
- [Product Brief](../examples/WDS-Presentation/docs/1-project-brief/01-product-brief.md) - Shows business goals and positioning
- [Trigger Map](../examples/WDS-Presentation/docs/2-trigger-map/00-trigger-map.md) - Contains all VTCs for the project
- [Personas](../examples/WDS-Presentation/docs/2-trigger-map/) - Detailed user profiles with driving forces
---
## VTC in Different Contexts
### Lightweight VTC (Direct Definition)
**When:** Quick projects, prototypes, single-feature work
**Process:**
1. 30-minute VTC workshop
2. Define 1-3 VTCs directly
3. Use VTCs to guide design
4. No full Trigger Map needed
**Output:** Simple table or YAML file with VTCs
### VTC from Trigger Map (Extracted)
**When:** Complex projects with multiple user types
**Process:**
1. Create full Trigger Map (1-2 days)
2. Extract VTCs from map for each scenario
3. VTCs reference back to richer context
4. Update map as project evolves
**Output:** VTCs with deep context and relationships
### The Spectrum
```
Quick (1 day) Medium (1 week) Large (months)
│ │ │
1 VTC directly → 2-3 VTCs directly → Full Trigger Map
Single scenario Focused scope containing 10+ VTCs
Minimal docs Some prioritization Complete strategic map
```
**Start where your project needs to start. Scale up if needed.**
---
## Common Questions
### Q: How many VTCs do I need?
**A:** Start with one per major user type or key scenario. For a simple product: 1-3 VTCs. For a complex platform: 10-20 VTCs.
### Q: Can a page serve multiple VTCs?
**A:** Yes! Often a page serves a primary VTC but specific sections address secondary VTCs. Document this in your page specification.
### Q: What if I have multiple business goals?
**A:** Create separate VTCs for each. One VTC might serve multiple goals, but each VTC should have a clear primary goal.
### Q: How detailed should driving forces be?
**A:** Specific enough to inform design decisions. "Want to save time" is too vague. "Fear of spending hours learning yet another tool" informs design.
### Q: When do I need a full Trigger Map instead of just VTCs?
**A:** When you have:
- Multiple user types with complex relationships
- Need to prioritize across many scenarios
- Long-term product requiring strategic foundation
- Stakeholders needing comprehensive strategic view
---
## VTC Template
Copy this template to create your VTCs:
```yaml
vtc-01:
business_goal: "[Measurable goal]"
solution: "[What you're building]"
user: "[Name] ([role/traits])"
context: "[When/where they encounter solution]"
driving_forces:
positive:
- "[Wish/aspiration]"
- "[Another wish]"
negative:
- "[Fear/frustration]"
- "[Another fear]"
customer_awareness: "[Start Stage] → [End Stage]"
# Add notes
notes: |
[Any additional context about this VTC]
[Why this combination matters]
[How it connects to other VTCs]
```
---
## Next Steps
1. **Try it:** Define your first VTC for your current project (30 minutes)
2. **Use it:** Reference your VTC when making next design decision
3. **Validate it:** Does your VTC actually inform your choices?
4. **Expand:** Add more VTCs as you discover more user types or scenarios
5. **Consider Trigger Map:** If you have 5+ VTCs, consider creating a full map for better prioritization
**Related Guides:**
- [Trigger Mapping Guide](./phase-2-trigger-mapping-guide.md) - When you need comprehensive strategic mapping
- [Scenario Definition Guide](./phase-4-ux-design-guide.md) - How VTCs anchor scenarios
- [Customer Awareness Cycle Model](../models/customer-awareness-cycle.md) - Deep dive into awareness positioning
---
*Value Trigger Chain - Minimum viable strategic context for purposeful design.*

8
src/modules/wds/docs/method/wds-method-guide.md
View File

@ -81,7 +81,7 @@ Connect business goals to user psychology through Trigger Mapping. Discover not
### Phase 3: PRD Platform (Technical Foundation)
**Output:** `C-Requirements/`
**Agent:** Freyja the PM
**Agent:** Freya the PM
Prove your concept works technically - in parallel with design work. Validate platform decisions, create proofs of concept, and set up experimental endpoints.
@ -137,7 +137,7 @@ Build your component library following atomic design principles. This phase is *
### Phase 6: PRD Finalization (Complete PRD)
**Output:** Complete PRD in `C-Requirements/` + `E-UI-Roadmap/`
**Agent:** Freyja the PM
**Agent:** Freya the PM
Compile all functional requirements discovered during Phase 4 into a complete, development-ready PRD. This phase runs **continuously** - hand off as soon as you have MVP scope, then update as design progresses.
@ -228,11 +228,11 @@ Saga guides you through discovery and research. She's curious, patient, and help
- Phase 1: Product Exploration
- Phase 2: Trigger Mapping
### Freyja the PM ⚔️
### Freya the PM ⚔️
_"The strategic leader who sees what must be done"_
Freyja helps you define technical requirements and finalize the PRD for development. She balances passion with strategy, knowing when to be fierce and when to be patient.
Freya helps you define technical requirements and finalize the PRD for development. She balances passion with strategy, knowing when to be fierce and when to be patient.
**Works with you on:**

681
src/modules/wds/docs/models/action-mapping.md Normal file
View File

@ -0,0 +1,681 @@
# Action Mapping
**A visual approach to designing training and experiences that focuses on what people DO, not what they KNOW**
**Originated by:** Cathy Moore
**Source:** Action Mapping website and workshops (2008+)
**Applied in WDS:** Scenario design, interaction design, UX specifications
---
## What It Is
**Action Mapping** is a visual design process that helps create effective training and user experiences by focusing on observable actions rather than information delivery.
**The Core Structure:**
```
1. Business Goal (What measurable outcome do we want?)
↓
2. Actions (What must people DO to achieve it?)
↓
3. Practice (How can they practice those actions?)
↓
4. Information (What minimum info do they need?) - ONLY IF NECESSARY
```
**Revolutionary Insight:** People don't need more information. They need to practice better actions. Information should support action, not replace it.
---
## Why It Matters
### The Problem Without Action Mapping
Traditional approach to design and training:
- Dumps information on people
- Assumes knowledge = ability
- "Here's everything you might need to know"
- No practice, just reading/watching
- Boring, ineffective, forgettable
- People leave informed but unable
**Example Bad Training:**
"Here are 47 slides about our CRM system. Now go use it!"
### The Solution With Action Mapping
Action-focused approach:
- Identifies what people must DO
- Provides realistic practice
- Information only when needed
- Engaging, effective, memorable
- People leave capable and confident
**Example Good Training:**
"Here's a real customer scenario. Show me how you'd handle it. [Practice] Need help? Here's the relevant info. [Just-in-time] Try again."
**The Core Insight:** Behavior change, not information transfer, achieves business goals.
---
## How It's Valuable in Strategic Design
### 1. **Scenario Design**
Instead of "What should users know about this feature?", ask:
**"What should users be able to DO?"**
**Traditional Feature Design:**
```
New Feature: Advanced Reporting
Content Needed:
- What reports are
- Types of reports available
- How reporting engine works
- Report customization options
```
**Action Mapping Approach:**
```
Business Goal: Managers make data-driven decisions daily
Actions Needed:
- Generate weekly team report (Tuesday mornings)
- Spot performance outliers in <30 seconds
- Share insights with team
Practice Scenarios:
- "It's Tuesday. Get your team report."
- "Sales dropped last week. Find out why."
- "Show Sarah this insight."
Info: Only what's needed to complete these actions
```
**Result:** Users learn by DOING, not reading documentation.
### 2. **Onboarding Flows**
Traditional onboarding = product tour (information dump)
Action Mapping onboarding = guided practice
**Instead of:**
"Here's where tasks live. Here's how to create them. Here's how to assign them..."
**Do:**
"Let's create your first task. [Do it] Great! Now assign it to yourself. [Do it] Perfect! You've got the basics."
### 3. **Help Documentation**
Traditional docs = reference manual
Action Mapping docs = action-oriented guides
**Instead of:**
"Reporting Module: The reporting module allows users to generate various types of reports..."
**Do:**
"Generate Your Weekly Report: 1. Click Reports, 2. Select 'Team Performance', 3. Choose date range, 4. Click Generate"
### 4. **Error Messages and Empty States**
Traditional = explain what went wrong
Action Mapping = guide toward successful action
**Instead of:**
"Error: No data available for selected parameters"
**Do:**
"Let's find your data: Try expanding your date range or selecting a different filter"
### 5. **Component Design**
Traditional = show all options
Action Mapping = guide user toward most common successful actions
**Example: File Upload**
- Most common action: Drag and drop
- Make that HUGE and obvious
- Other options smaller (browse, paste URL)
- Result: Users DO the happy path naturally
---
## Attribution and History
### Cathy Moore - The Creator
**Cathy Moore** is an instructional designer who developed Action Mapping in response to ineffective traditional training approaches. She noticed that most training focused on delivering information rather than changing behavior.
Her background in journalism and instructional design led her to ask: "What do people need to DO differently?" rather than "What do they need to know?"
### Development and Influence
**Timeline:**
- Late 2000s: Developed Action Mapping methodology
- 2008+: Shared freely on blog.cathy-moore.com
- 2010s: Became widely adopted in e-learning community
- Now: Influences UX design, product onboarding, and user experience beyond training
**Impact:**
- Shifted e-learning from "page-turners" to interactive scenarios
- Influenced UX onboarding design
- Changed how designers think about user education
- Emphasis on practice over information now standard in good UX
### Philosophy
Moore's core belief: **"People come to work to do a job, not to learn."**
Therefore:
- Focus on job performance, not knowledge transfer
- Provide practice, not presentations
- Give information only when needed (just-in-time)
- Measure behavior change, not quiz scores
---
## Source Materials
### Website and Blog
🔗 **[Blog.Cathy-Moore.com](https://blog.cathy-moore.com)**
- Original source for Action Mapping
- Free detailed explanations
- Case studies and examples
- Downloads and templates
- "The best training blog you're not reading"
🔗 **[Action Mapping: The Infographic](https://blog.cathy-moore.com/action-mapping-a-visual-approach-to-training-design/)**
- Visual guide to the process
- Free to download and share
### Books and Resources
📚 **Map It: The Hands-On Guide to Strategic Training Design**
By Cathy Moore (2017)
- Comprehensive guide to Action Mapping
- Step-by-step worksheets
- Real project examples
- [Available on Amazon](https://www.amazon.com/Map-Hands-Guide-Strategic-Training/dp/1973967812)
### Workshops and Courses
🎓 **Action Mapping Workshops**
- Cathy Moore offers periodic workshops
- Check blog.cathy-moore.com for schedule
🎓 **Online Training on Action Mapping**
- Various platforms offer courses teaching the methodology
- Search for "Action Mapping course" on LinkedIn Learning, Udemy
### Articles
🔗 **"Action Mapping: A Visual Approach to Training Design"**
- Core article explaining the methodology
- Available on Cathy Moore's blog
🔗 **"Saving the World from Boring Training"**
- Philosophy and approach
- [Blog.Cathy-Moore.com](https://blog.cathy-moore.com)
---
## Whiteport Methods That Harness This Model
### [Phase 4: UX Design Guide](../method/phase-4-ux-design-guide.md)
Scenario design uses Action Mapping principles:
**Instead of "What does user need to know about this page?"**
**Ask:**
1. What is the user trying to DO here?
2. What actions lead to success?
3. How can we guide those actions?
4. What info supports (not replaces) action?
**Result:** Scenarios focused on user actions, not information architecture.
### Page Specifications
Component specs describe actions, not features:
**Traditional Spec:**
```
Component: Dashboard Widget
Features: Data display, filters, export button
```
**Action Mapping Spec:**
```
User Action: Check team performance at glance
Success: Spot issues in <10 seconds
Design: Key metrics prominent, issues red, drill-down on click
Info: Only when drilling down, not upfront
```
### Interaction Design
Flows prioritize action paths:
**Traditional Flow:**
```
1. Welcome screen (info)
2. Feature tour (info)
3. Tutorial (info)
4. Dashboard (finally do something!)
```
**Action Mapping Flow:**
```
1. "Let's create your first project" (action)
2. [User does it] (practice)
3. "Great! Now add a task" (next action)
4. [User does it] (more practice)
5. "You're ready! Here's your dashboard" (info only if needed)
```
---
## Imaginary Examples
### Example 1: Project Management Tool Onboarding
**Traditional Information-Focused:**
```
Screen 1: "Welcome to TaskMaster!"
Screen 2: "Here's your dashboard. This is where you'll see all your projects."
Screen 3: "Click here to create projects. Projects contain tasks."
Screen 4: "Tasks can be assigned to team members and have due dates."
Screen 5: "You can view tasks in list or board view."
Screen 6: "Reports help you track progress."
Screen 7: "Now try it yourself!"
```
**Action Mapping Approach:**
```
Screen 1: "Let's create your first project"
User: [Types project name, clicks create] ✅
Screen 2: "Every project needs tasks. Add one:"
User: [Types task, clicks add] ✅
Screen 3: "Who's doing this? Assign it:"
User: [Selects person] ✅
Screen 4: "You're all set! Here's your project."
[Show completed project with task assigned]
Tip available: "Want to add more? Click + to add tasks anytime."
```
**Result:** User has created project, added task, assigned it within 60 seconds. They KNOW how because they DID it.
### Example 2: Design System Documentation
**Traditional (Information Dump):**
```
# Button Component
The button component is used for user actions. It has several variants:
## Variants
- Primary: Main call-to-action
- Secondary: Secondary actions
- Tertiary: Low-priority actions
- Danger: Destructive actions
## Properties
- size: 'sm' | 'md' | 'lg'
- variant: 'primary' | 'secondary' | 'tertiary' | 'danger'
- disabled: boolean
- onClick: function
## Examples
[Code examples]
## Usage Guidelines
[More information]
```
**Action Mapping Approach:**
```
# Button Component
## What Are You Trying to Do?
→ Create a main call-to-action
Use: <Button variant="primary">
Example: "Sign Up", "Save", "Continue"
→ Add a secondary action
Use: <Button variant="secondary">
Example: "Cancel", "Back", "Learn More"
→ Warn about destructive action
Use: <Button variant="danger">
Example: "Delete", "Remove", "Clear All"
## Quick Copy-Paste
[Most common code snippets ready to use]
→ Need all the details? [Expand full documentation]
```
**Result:** Designer finds what they need to DO, gets it done. Deep reference available but not required reading.
### Example 3: Feature Announcement
**Traditional (Broadcast Information):**
```
Subject: "Introducing Advanced Reporting!"
We're excited to announce Advanced Reporting is now available!
What's new:
- Custom report builder
- 15 new visualization types
- Scheduled report delivery
- Export to multiple formats
Advanced Reporting allows you to create sophisticated reports...
[Several more paragraphs explaining features]
Check it out in the Reports menu!
```
**Action Mapping Approach:**
```
Subject: "Generate Your Custom Report in 60 Seconds"
Hi [Name],
Want to see which features drove growth last month?
→ Click here to try the new report builder [Button]
You'll create a custom report in 3 steps:
1. Pick your data (sales, signups, usage)
2. Choose visualization (we'll suggest best one)
3. Save or schedule it
[Video: 45-second demo of doing exactly this]
Questions? Reply to this email.
```
**Result:** User clicks, DOES the thing, experiences value. Learns through action.
---
## Real Applications
### WDS Scenario Specifications
WDS scenario specs focus on actions:
**See:** [WDS Presentation Scenarios](../examples/WDS-Presentation/docs/4-scenarios/)
Each scenario specifies:
- **User Goal:** What user is trying to achieve (action-oriented)
- **Success Criteria:** Observable action completed
- **Key Interactions:** What user DOES at each step
- **Supporting Information:** Only what's needed for action
Not:
- Everything user might want to know
- All possible features explained
- Comprehensive tutorial
**Philosophy:** Users learn by doing, not reading. Guide action.
---
## The Four-Step Action Mapping Process
### Step 1: Define Business Goal (10 minutes)
**Not a learning objective!** What business outcome do we want?
**Good Goals:**
- "Reduce support tickets by 30%"
- "Increase feature adoption from 20% to 50%"
- "Managers make weekly data-driven decisions"
**Bad Goals:**
- "Users understand how reporting works"
- "Increase knowledge of features"
- "Complete training module"
**Why:** You want behavior change, not information transfer.
### Step 2: Identify Necessary Actions (20-30 minutes)
What must people DO (not know) to achieve that goal?
**For "Reduce support tickets by 30%":**
Actions users must take:
- Solve common problems themselves (not contact support)
- Find answers in help docs quickly
- Use self-service troubleshooting tools
**Key Question:** "If I could watch people working, what would I see them DOING that shows we're succeeding?"
**Avoid:**
- "Understand how system works" (not observable)
- "Know where help docs are" (not an action)
- "Be familiar with features" (vague)
**Want:**
- "Search help docs and find answer in <2 minutes"
- "Reset own password without help"
- "Check system status before contacting support"
### Step 3: Design Practice Activities (30-45 minutes)
How can people practice those actions?
**For each action, create realistic scenarios:**
**Action:** "Search help docs and find answer"
**Practice:**
```
Scenario: Your report isn't generating. The screen just says "Processing..."
What do you do? [Simulation where user can try actions]
- Search help docs? ✅ Shows article on report timeouts
- Contact support? ❌ "Could you solve this yourself first?"
- Wait longer? ❌ "It's been 10 minutes..."
[User finds answer, applies solution, report generates]
"Perfect! You saved 2 hours waiting for support."
```
**Characteristics of good practice:**
- Realistic context (not abstract)
- Consequences of choices (not just "right/wrong")
- Challenge appropriate to learner
- Feedback that guides, not lectures
### Step 4: Identify Minimum Information (15-20 minutes)
What information do people need to complete the actions?
**Critical Question:** "Can they DO the action without this information?"
**If YES → Don't include it**
**If NO → Include it just-in-time**
**Example:**
**Action:** Generate weekly team report
**Info they DON'T need upfront:**
- Complete feature list of reporting module
- History of how reporting was built
- All possible customization options
- Technical architecture of reports
**Info they DO need:**
- Where to click to start ("Reports menu")
- Which report template to use ("Team Performance")
- How to set date range (quick inline guide)
**Provide info:**
- Right when they need it (not before)
- In context of action (not separate tutorial)
- As briefly as possible (then let them do it)
---
## Action Mapping vs. Information Dumping
| **Information Dumping** | **Action Mapping** |
|-------------------------|-------------------|
| "Here's everything about this feature" | "Here's how to accomplish your goal" |
| Starts with information | Starts with business goal |
| Explains how system works | Guides what user does |
| "Know this, then apply it" | "Do this, learn along the way" |
| Passive reading/watching | Active practice |
| Tests knowledge | Observes behavior |
| "Did they remember?" | "Can they do it?" |
| Front-loaded learning curve | Progressive disclosure |
| Boring | Engaging |
---
## Common Questions
### Q: What if people need conceptual understanding before acting?
**A:** Provide JUST enough concept to enable action, not comprehensive explanation. Example:
**Don't:** "Branches in Git are pointers to commits in the commit graph. When you create a branch..."
**Do:** "Think of branches like parallel workspaces. Let's create one: [command]. Try it."
Concept → minimal. Action → immediate.
### Q: What about reference documentation?
**A:** It still exists! Action Mapping is for learning and onboarding. Reference docs are for looking up details later. Users should be able to DO the common actions without reading reference docs.
### Q: Isn't this just good UX design?
**A:** Increasingly, yes! Action Mapping originated in training but its principles apply broadly:
- Onboarding
- Feature adoption
- Help systems
- Product design
- Any context where you want behavior change
### Q: What if the business goal isn't about behavior?
**A:** Usually is, indirectly. "Increase awareness" isn't measurable behavior. But "Attend webinar" or "Sign up for newsletter" are. Find the observable action.
### Q: How much practice is enough?
**A:** Enough that person can perform action independently with confidence. Usually:
- Simple action: 1-2 practice scenarios
- Complex action: 3-5 scenarios with increasing difficulty
- Critical action: Practice until automatic
---
## Using Action Mapping in Your Process
### For Onboarding Design
1. **Define success:** What does activated user DO?
2. **List actions:** What specific actions show activation?
3. **Design practice:** Guide user through those exact actions with real data
4. **Minimize info:** Remove any explanation not essential to action
**Test:** Can user complete key action within first session?
### For Feature Adoption
1. **Goal:** X% of users use feature monthly
2. **Actions:** What must they DO to use it successfully?
3. **Entry point:** Where do they encounter opportunity to practice?
4. **Guide action:** Show, don't tell
**Test:** Do users try feature after seeing it?
### For Documentation
1. **Identify common tasks:** What are people trying to DO?
2. **Action-oriented structure:** Organize by task, not feature
3. **Minimal explanation:** Just enough to complete task
4. **Quick examples:** Copy-paste ready
**Test:** Can users complete task from docs without asking for help?
### For Error Handling
1. **User goal:** What were they trying to DO?
2. **What went wrong:** Why can't they do it?
3. **Corrective action:** What specific action fixes it?
4. **Guide repair:** Show path forward
**Test:** Can users recover without frustration?
---
## Action Mapping Template
```markdown
## Business Goal
[What measurable outcome?]
## Actions Needed
[What must people DO to achieve goal?]
- Action 1: [Observable behavior]
- Action 2: [Observable behavior]
- Action 3: [Observable behavior]
## Practice Scenarios
[How will people practice each action?]
Action 1: [Observable behavior]
- Scenario: [Realistic context]
- User does: [Actual action]
- Feedback: [Result/guidance]
## Minimum Information
[Only what's needed to complete actions]
- Info bit 1: [Just-in-time, just-enough]
- Info bit 2: [Provided in context]
## Success Metric
[How do we measure behavior change?]
```
---
## Next Steps
1. **Read:** Cathy Moore's blog (blog.cathy-moore.com) - start with Action Mapping intro
2. **Try:** Take one feature/onboarding flow and redesign using Action Mapping
3. **Test:** Does new version enable action faster than old info-dump version?
4. **Apply:** Use action-focus in next scenario specification
**Related Resources:**
- [Phase 4: UX Design Guide](../method/phase-4-ux-design-guide.md) - Scenario design using action focus
- [Value Trigger Chain Guide](../method/value-trigger-chain-guide.md) - Connect actions to driving forces
- [Blog.Cathy-Moore.com](https://blog.cathy-moore.com) - Original source and examples
---
*Action Mapping - People don't need to know, they need to DO.*

530
src/modules/wds/docs/models/customer-awareness-cycle.md Normal file
View File

@ -0,0 +1,530 @@
# Customer Awareness Cycle
**A framework for understanding where users are in their buying journey and how to meet them there**
**Originated by:** Eugene Schwartz
**Source:** *Breakthrough Advertising* (1966)
**Applied in WDS:** Scenario definition, content strategy, user positioning
---
## What It Is
The **Customer Awareness Cycle** is a five-stage framework that describes a user's journey from complete unawareness to enthusiastic advocacy. It answers the critical question: *"What does my user already know, and what do they need to know next?"*
### The Five Stages
1. **Unaware** - Doesn't know problem exists
2. **Problem Aware** - Knows problem, doesn't know solutions exist
3. **Solution Aware** - Knows solutions exist, doesn't know about yours specifically
4. **Product Aware** - Knows your solution exists, hasn't committed
5. **Most Aware** - Has used, loved, and advocates for your solution
**The Core Insight:** You can't sell a solution to someone who doesn't know they have a problem. You must meet users where they are and guide them forward one stage at a time.
---
## Why It Matters
### The Problem Without Customer Awareness
Content and design often assume too much or too little:
- Landing page assumes visitors know the problem (they don't)
- Onboarding explains WHY when users already bought (they know)
- Messaging speaks to wrong awareness level
- Conversion funnels skip critical awareness stages
- Content feels irrelevant or condescending
### The Solution With Customer Awareness
Every interaction meets users where they are:
- Content depth matches awareness level
- Messaging addresses current questions
- Next steps feel natural and logical
- Progression through stages is intentional
- Success rates improve dramatically
**Example:**
- Problem Aware user needs: "Here's how solutions work"
- Product Aware user needs: "Here's why OURS is right for you"
Same user type, different content, different design.
---
## How It's Valuable in Strategic Design
### 1. **Content Strategy**
Each awareness level requires different content depth and focus:
**Unaware → Problem Aware:**
- Educational content
- "Did you know..." framing
- Problem agitation
- Relatable scenarios
**Problem Aware → Solution Aware:**
- Solution categories
- "Here's how people solve this"
- Approach explanation
- No product pitch yet
**Solution Aware → Product Aware:**
- Your specific approach
- Differentiation
- "Why us" messaging
- Product introduction
**Product Aware → Most Aware:**
- Proof and trust signals
- Onboarding and activation
- Success stories
- Community building
### 2. **Scenario Design**
Every scenario should move users forward in awareness:
```yaml
scenario:
name: "Landing Page Visit"
awareness_start: "Solution Aware"
awareness_goal: "Product Aware"
design_implication: "Show how OUR solution works, not ALL solutions"
```
This creates measurable goals and clear design direction.
### 3. **Messaging Hierarchy**
Homepage serves multiple awareness levels:
- **Hero:** Problem Aware → Solution Aware
- **Features:** Solution Aware → Product Aware
- **Testimonials:** Product Aware → Most Aware
Each section progresses the journey.
### 4. **Microcopy and Tone**
Awareness level affects everything:
- Button labels
- Error messages
- Empty states
- Help text
**Example - Empty State:**
- Problem Aware: "Projects help you organize work. Create your first one!"
- Product Aware: "No projects yet. Ready to start?"
### 5. **Measurement and Optimization**
Track awareness progression:
- What % move from Problem → Solution Aware?
- Where do users get stuck?
- Which content advances awareness most effectively?
---
## Attribution and History
### Eugene Schwartz - The Pioneer
**Eugene Schwartz** (1927-1995) was a legendary direct response copywriter who wrote *Breakthrough Advertising* in 1966. This book, considered one of the greatest marketing books ever written, introduced the awareness stages framework.
Schwartz observed that the most successful ads matched message to awareness level. He codified this into a framework that has influenced marketing and UX for over 50 years.
### Modern Applications
While Schwartz focused on advertising copy, his framework applies powerfully to:
- User experience design
- Content strategy
- Product onboarding
- Marketing funnels
- Educational platforms
**Timeless Principle:** *"You can't tell people what they're not ready to hear."*
---
## Source Materials
### Books
📚 **Breakthrough Advertising** by Eugene Schwartz (1966)
- *The original source*
- Out of print but available as reprints
- Dense, challenging, rewarding read
- [Available on Amazon](https://www.amazon.com/Breakthrough-Advertising-Eugene-M-Schwartz/dp/0887232981) (reprints ~$125-200)
📚 **The Adweek Copywriting Handbook** by Joseph Sugarman (2006)
- Accessible introduction to Schwartz's concepts
- Practical applications
- [Available on Amazon](https://www.amazon.com/Adweek-Copywriting-Handbook-Ultimate-Writing/dp/0470051248)
### Articles and Resources
🔗 **[Copyhackers: The 5 Stages of Awareness](https://copyhackers.com/2017/05/customer-awareness/)** - Modern application to web copy
🔗 **[Digital Marketer: Customer Awareness](https://www.digitalmarketer.com/blog/customer-awareness/)** - Practical framework for online marketing
### Videos
🎥 **[Customer Awareness - The Copywriter's Secret Weapon](https://www.youtube.com/results?search_query=eugene+schwartz+customer+awareness)** - Various explainer videos on YouTube
---
## Whiteport Methods That Harness This Model
### [Value Trigger Chain Guide](../method/value-trigger-chain-guide.md)
VTCs include Customer Awareness positioning:
- Starting point: Where is user NOW?
- Target point: Where do we want to move them?
- Design serves this progression
**Example:**
```
Customer Awareness: Problem Aware → Product Aware
Design Implication: Introduce OUR solution after establishing problem
```
### [Trigger Mapping Guide](../method/phase-2-trigger-mapping-guide.md)
Trigger Maps can include awareness positioning for each persona:
- Different users at different awareness levels
- Scenarios designed to progress awareness
- Content strategy matches awareness
### [Scenario Definition (Phase 4)](../method/phase-4-ux-design-guide.md)
Each scenario defines awareness progression:
- Entry point awareness level
- Exit point awareness level
- Interactions designed to bridge the gap
### [Content Creation Workflow](../method/value-trigger-chain-guide.md#using-vtcs-in-your-design-process)
Before creating any content:
1. Identify user's current awareness level
2. Determine target awareness level
3. Create content that bridges the gap
4. Validate: Does this advance awareness?
---
## Imaginary Examples
### Example 1: SaaS Landing Page
**User:** Startup founder, Problem Aware (knows they need better project management)
**Awareness Progression:** Problem Aware → Solution Aware → Product Aware
**Page Structure:**
**Section 1 - Problem Aware → Solution Aware:**
- Headline: "Your Team Scattered Across Slack, Email, and Spreadsheets?"
- Body: Brief description of how modern teams centralize work
- CTA: "See How It Works" (not "Sign Up")
**Section 2 - Solution Aware → Product Aware:**
- Headline: "Meet [Product]: Where Work Happens"
- Body: Your specific approach and differentiators
- CTA: "Try It Free" (awareness sufficient for commitment)
### Example 2: Onboarding Flow
**User:** New signup, Product Aware → Most Aware progression needed
**Wrong Approach (assuming Unaware):**
```
"Welcome! Did you know teams waste 2.5 hours daily switching between tools?"
```
*User thinks: "I know, that's why I signed up. Get to the point."*
**Right Approach (Product Aware):**
```
"Welcome! Let's get your first project set up."
```
*User thinks: "Perfect, let's go."*
### Example 3: Feature Documentation
**User:** Existing customer, Most Aware of product but Unaware of new feature
**Structure:**
1. **Problem Agitation:** "Tired of manually updating status?" (Unaware → Problem Aware)
2. **Solution Introduction:** "Status Automations do it for you" (Problem → Solution Aware)
3. **How to Use:** "Click Settings → Automations" (Solution → Product Aware on this feature)
4. **Advanced Tips:** "Pro tip: Chain automations for..." (Product → Most Aware)
---
## Real Applications
### WDS Presentation Project
The WDS Presentation landing page considers multiple awareness levels:
**Stina (Designer):**
- Current: Solution Aware (knows design tools exist)
- Target: Product Aware (knows WDS specifically)
- Content: Shows WDS's unique approach vs generic "design tools are great"
**Lars (Executive):**
- Current: Problem Aware (knows design-dev handoff is broken)
- Target: Solution Aware (learns modern AI-assisted approaches exist)
- Content: Educates on solution category before pitching WDS
**See:** [WDS Presentation Trigger Map](../examples/WDS-Presentation/docs/2-trigger-map/00-trigger-map.md)
Each persona's current awareness level shapes how the landing page speaks to them.
---
## Detailed Stage Characteristics
### Stage 1: Unaware
**What They Know:** Nothing about problem or solutions
**What They Need:**
- Problem revelation
- Relatable scenarios
- "You're not alone" messaging
- Educational framing
**Content Types:**
- Blog posts about industry challenges
- Research reports
- "State of [Industry]" content
- Social media education
**Example Messaging:**
- "Most designers waste 15 hours/week recreating components that already exist..."
- "Did you know 73% of projects fail due to unclear requirements?"
**Don't:**
- Pitch your product
- Assume they know the problem
- Use jargon
### Stage 2: Problem Aware
**What They Know:** Problem exists and affects them
**What They Need:**
- Validation that problem is solvable
- Overview of solution approaches
- Hope and direction
- Not product-specific yet
**Content Types:**
- "How to solve [problem]" guides
- Solution category overviews
- Comparison of approaches
- Educational webinars
**Example Messaging:**
- "There are three main approaches to [problem]: [A], [B], and [C]..."
- "Teams solve this by establishing shared design systems..."
**Don't:**
- Pitch product before educating on solutions
- Assume they know solution categories
### Stage 3: Solution Aware
**What They Know:** Solution categories exist, exploring options
**What They Need:**
- Your specific approach explained
- Differentiation from other solutions
- Why YOUR way is different/better
- Still some education, less selling
**Content Types:**
- "Our approach to [problem]"
- Product overview (not features list)
- Philosophy and methodology
- Comparison content (you vs others)
**Example Messaging:**
- "Unlike traditional design tools that focus on pixels, WDS starts with user psychology..."
- "Most solutions require developers to interpret designs. WDS creates specs developers can actually use..."
**Don't:**
- List features without context
- Assume they know your differentiation
### Stage 4: Product Aware
**What They Know:** Your solution exists, evaluating it
**What They Need:**
- Proof it works (case studies, demos)
- Trust signals (testimonials, security)
- Clear path to start (pricing, trial)
- Answers to objections
**Content Types:**
- Product demos and walkthroughs
- Case studies and testimonials
- Pricing and packaging info
- FAQs and objection handling
- Free trial or demo signup
**Example Messaging:**
- "Join 1,000+ designers who've reduced handoff time by 60%..."
- "See how [Company] shipped their redesign in half the time..."
- "Start free, upgrade when you're ready"
**Don't:**
- Over-educate (they're ready to evaluate)
- Hide pricing or next steps
### Stage 5: Most Aware
**What They Know:** Your product intimately, are users/advocates
**What They Need:**
- Advanced tips and best practices
- Community and belonging
- New feature announcements
- Ways to go deeper
- Recognition and advocacy opportunities
**Content Types:**
- Advanced guides and tutorials
- Community forums and events
- Beta features and early access
- Referral and advocacy programs
- Power user showcases
**Example Messaging:**
- "Pro tip: Did you know you can chain automations?"
- "Meet Sarah, who uses WDS to design 3x faster..."
- "Invite your team, get [benefit]"
**Don't:**
- Explain basics they already know
- Treat them like newbies
---
## Common Questions
### Q: Can users skip stages?
**A:** Sometimes, but rarely. Most users progress sequentially. Trying to force jumps (Problem Aware → Most Aware) usually fails. Design for stage-by-stage progression.
### Q: Can the same content serve multiple awareness levels?
**A:** Advanced content can serve different parts to different users (Most Aware read deep, Solution Aware skim headlines). But forcing one page to serve Unaware AND Most Aware usually serves neither well.
### Q: How do I know what awareness level my users are?
**A:** Research, analytics, and testing:
- User interviews: "How did you hear about us?"
- Analytics: What content do they consume before converting?
- Surveys: "How familiar are you with [solution category]?"
- A/B testing: Which messaging resonates?
### Q: What if I have users at all levels?
**A:** Design entry points for each level:
- Blog (Unaware → Problem Aware)
- Resource Center (Problem → Solution Aware)
- Product Pages (Solution → Product Aware)
- App Login (Most Aware)
Or design sections of pages for progression (homepage hero → features → testimonials).
---
## Using Customer Awareness in Your Process
### Step 1: Identify Current Awareness
For each key user type:
- Where are they NOW?
- What research have they done?
- How did they find you?
- What do they already know?
### Step 2: Define Target Awareness
For this interaction:
- Where do we want to move them?
- What's the next stage they're ready for?
- What prevents them from progressing?
### Step 3: Design the Bridge
Create content and interactions that:
- Acknowledge current awareness
- Provide what they need to progress
- Don't assume too much knowledge
- Don't over-explain what they know
### Step 4: Measure Progression
Track:
- What % progress to next stage?
- Where do users get stuck?
- Which content advances awareness?
- What stage converts best?
### Step 5: Optimize
Adjust content and design based on data:
- Strengthen weak transitions
- Add missing bridges
- Remove awareness mismatches
---
## Customer Awareness Template
Use this template when defining scenarios or content:
```yaml
scenario: "[scenario name]"
user:
name: "[User name/type]"
current_awareness: "[Unaware/Problem/Solution/Product/Most]"
target_awareness: "[Problem/Solution/Product/Most Aware]"
content_strategy:
focus: "[What this awareness transition requires]"
tone: "[How to speak to this awareness level]"
depth: "[How much detail to include]"
call_to_action: "[What action is appropriate for target awareness]"
measurement:
success: "[User reached target awareness]"
metric: "[How we measure awareness progression]"
```
---
## Next Steps
1. **Audit current content:** What awareness level does each piece assume? Does it match your users?
2. **Map user journey:** Where do users enter (awareness level) and where should they exit?
3. **Identify gaps:** Which awareness transitions are weak or missing?
4. **Design bridges:** Create content that moves users forward stage by stage
5. **Test and measure:** Track progression through awareness stages
**Related Resources:**
- [Value Trigger Chain Guide](../method/value-trigger-chain-guide.md) - Includes Customer Awareness positioning
- [Trigger Mapping Guide](../method/phase-2-trigger-mapping-guide.md) - Uses awareness to position personas
- [Phase 4: UX Design Guide](../method/phase-4-ux-design-guide.md) - Applies awareness to scenarios
---
*Customer Awareness Cycle - Meet users where they are, guide them where they need to go.*

532
src/modules/wds/docs/models/golden-circle.md Normal file
View File

@ -0,0 +1,532 @@
# The Golden Circle
**A framework for inspiring action by starting with WHY**
**Originated by:** Simon Sinek
**Source:** *Start With Why* (2009), TEDx Talk (2009)
**Applied in WDS:** Product Brief discovery, messaging hierarchy, value proposition
---
## What It Is
The **Golden Circle** is a communication framework that explains why some leaders and organizations inspire action while others don't. It consists of three concentric circles:
```
WHY (Purpose, Cause, Belief)
↓
HOW (Process, Values, Differentiators)
↓
WHAT (Products, Services, Features)
```
**The Core Insight:** Most organizations communicate from the outside-in (WHAT → HOW → WHY), but inspiring leaders communicate from the inside-out (WHY → HOW → WHAT).
**Example:**
**Outside-In (Uninspiring):**
> "We make great computers. (WHAT) They're beautifully designed and easy to use. (HOW) Want to buy one? (Meh)"
**Inside-Out (Inspiring):**
> "We believe in challenging the status quo and thinking differently. (WHY) We do this by making products beautifully designed and simple to use. (HOW) We just happen to make great computers. (WHAT) Want to buy one? (YES!)"
Same company, same products, radically different impact.
---
## Why It Matters
### The Problem Without Starting With WHY
Communication falls flat:
- Features and benefits feel hollow
- "So what?" response from audience
- No emotional connection
- Customers buy on price (commoditization)
- Hard to inspire team or attract talent
- Marketing feels like convincing, not connecting
### The Solution With Starting With WHY
Communication resonates deeply:
- Purpose creates emotional connection
- Customers become believers and advocates
- Premium pricing justified by belief alignment
- Team motivated by mission, not just paycheck
- Marketing feels like finding kindred spirits
- Loyalty transcends product features
**Biological Basis:** The WHY speaks to the limbic brain (emotions, decision-making). The WHAT speaks to neocortex (rational thought). **People make decisions emotionally, then justify rationally.**
---
## How It's Valuable in Strategic Design
### 1. **Product Discovery and Positioning**
Before defining features, ask:
- WHY does this product need to exist?
- WHAT belief or purpose drives it?
- WHO shares this belief?
**Example Product Brief Questions:**
- "Why are you building this?" (not "what")
- "What would the world lose if this didn't exist?"
- "What keeps you up at night?" (purpose/passion)
### 2. **Messaging Hierarchy**
Structure all communication WHY → HOW → WHAT:
**Homepage Example:**
- **Hero (WHY):** "Empowering every designer to create software people love"
- **Subhead (HOW):** "Through AI-assisted strategic design methodology"
- **Features (WHAT):** "Trigger mapping, UX specifications, design systems"
### 3. **Content Strategy**
Each piece of content can lead with purpose:
**Blog Post Title:**
- Bad (WHAT): "10 Features of Our Design Tool"
- Good (WHY): "Why Designers Deserve Better Tools: The Mission Behind WDS"
**About Page:**
- Don't start with company history (WHAT)
- Start with founding belief (WHY)
- Then explain unique approach (HOW)
- Finally list products/services (WHAT)
### 4. **Stakeholder Alignment**
Get team aligned on WHY before discussing WHAT:
**Project Kickoff:**
1. "WHY are we building this?" (Purpose discussion)
2. "HOW will we approach it differently?" (Strategy)
3. "WHAT will we build?" (Features)
**Result:** Team united by shared purpose, not just task list.
### 5. **User Interview and Research**
Ask WHY before HOW or WHAT:
**Interview Structure:**
- Start: "Why does [problem] matter to you?"
- Middle: "How have you tried to solve it?"
- End: "What would an ideal solution include?"
**Uncovers:** Driving forces, emotional motivations, not just functional needs.
---
## Attribution and History
### Simon Sinek - The Popularizer
**Simon Sinek** is a British-American author and motivational speaker who introduced the Golden Circle in his 2009 book *Start With Why: How Great Leaders Inspire Everyone to Take Action*.
His 2009 TEDx Talk "How Great Leaders Inspire Action" became one of the most-viewed TED talks of all time (50+ million views), bringing the Golden Circle framework to global attention.
### The Origin Story
Sinek developed the Golden Circle while studying successful leaders and organizations. He noticed patterns:
- Companies like Apple, Southwest Airlines, and Harley-Davidson inspire fierce loyalty
- These organizations communicate differently than competitors
- They start with WHY (purpose), not WHAT (products)
**His Discovery:** The pattern matches how the human brain makes decisions (limbic system for WHY/HOW, neocortex for WHAT).
### Influence
The Golden Circle has influenced:
- Business strategy and marketing
- Leadership development
- Brand positioning
- Product design methodology (including WDS)
- Public speaking and storytelling
---
## Source Materials
### Books
📚 **Start With Why: How Great Leaders Inspire Everyone to Take Action**
By Simon Sinek (2009)
- The original source explaining the Golden Circle
- Case studies from Apple, MLK Jr., Wright Brothers, and more
- Practical application for businesses and individuals
- [Available on Amazon](https://www.amazon.com/Start-Why-Leaders-Inspire-Everyone/dp/1591846447)
📚 **Find Your Why: A Practical Guide for Discovering Purpose**
By Simon Sinek, David Mead, Peter Docker (2017)
- Step-by-step workshops to discover your WHY
- Tools for individuals and organizations
- Templates and facilitation guides
- [Available on Amazon](https://www.amazon.com/Find-Your-Why-Practical-Discovering/dp/0143111728)
### Videos
🎥 **"How Great Leaders Inspire Action" - TEDx Talk**
Simon Sinek (2009) - 50+ million views
- The original 18-minute talk introducing the Golden Circle
- Clear explanation with compelling examples
- [Watch on TED.com](https://www.ted.com/talks/simon_sinek_how_great_leaders_inspire_action)
🎥 **"Start With Why" - Book Summary Videos**
Various channels on YouTube
- [Search for "Start With Why summary"](https://www.youtube.com/results?search_query=start+with+why+simon+sinek)
### Articles and Resources
🔗 **[SimonSinek.com](https://simonsinek.com)**
- Official website with resources
- Blog posts and additional content
- Speaking and workshop information
🔗 **"Find Your Why" Worksheet**
- Free downloadable worksheets
- Available on Simon Sinek's website
---
## Whiteport Methods That Harness This Model
### [Phase 1: Product Exploration Guide](../method/phase-1-product-exploration-guide.md)
The Product Brief discovery conversation uses Golden Circle structure:
**Discovery Flow:**
1. **WHY Questions First:**
- "Why does this product need to exist?"
- "What problem keeps you up at night?"
- "What would success look like for your users?"
2. **HOW Questions Second:**
- "How is your approach different?"
- "How will users experience this differently?"
- "How will you measure success?"
3. **WHAT Questions Last:**
- "What features are must-haves?"
- "What is explicitly out of scope?"
- "What are the key deliverables?"
**Result:** Product Brief grounded in purpose, not just feature list.
### [Value Trigger Chain Guide](../method/value-trigger-chain-guide.md)
VTC implicitly uses Golden Circle:
- **Business Goal:** The WHY (organizational purpose)
- **Driving Forces:** User's personal WHY (motivation)
- **Solution:** The HOW (approach)
- **(Implicit features):** The WHAT (implementation)
### Content Creation Workflow
When creating any content, structure using Golden Circle:
1. **Lead with WHY:** Purpose, benefit, emotional hook
2. **Explain HOW:** Approach, process, differentiation
3. **Describe WHAT:** Features, specifics, implementation
---
## Imaginary Examples
### Example 1: SaaS Landing Page
**Traditional Approach (WHAT → HOW → WHY):**
```
Headline: "Advanced Project Management Software"
Subhead: "With AI-powered automation and real-time collaboration"
Body: "Manage tasks, track time, generate reports..."
CTA: "Start Free Trial"
```
**Golden Circle Approach (WHY → HOW → WHAT):**
```
Headline: "Your Team Deserves to Do Their Best Work" (WHY)
Subhead: "We eliminate busywork so you can focus on what matters" (WHY)
Body: "Through intelligent automation that learns your workflow,
we handle the repetitive stuff while you handle the creative" (HOW)
Features: "Smart task routing, automated standups, AI reports" (WHAT)
CTA: "Reclaim Your Time"
```
**Notice:** Same product, radically different emotional impact.
### Example 2: About Page
**Traditional Structure:**
```
"Founded in 2020, we are a team of 50 engineers and designers
who have worked at Apple, Google, and Microsoft. We've raised $10M
in funding and serve 10,000 customers globally. Our platform
includes features like..."
```
**Golden Circle Structure:**
```
WHY: "We believe designers shouldn't have to choose between
creativity and clarity. Every designer deserves a thinking
partner that turns vision into reality."
HOW: "We combine strategic frameworks from 20+ years of UX practice
with AI assistance, creating a methodology that bridges
design and development seamlessly."
WHAT: "Today, 10,000 designers use WDS to create specifications
that developers love. Our team of 50 has helped ship
over 1,000 products."
```
**Result:** Reader understands purpose and values, creating emotional connection before credentials.
### Example 3: Job Posting
**Traditional:**
```
"We're hiring a Senior Designer. Requirements: 5+ years experience,
Figma expert, portfolio required. Responsibilities: Create UI designs,
work with developers, iterate based on feedback."
```
**Golden Circle:**
```
WHY: "We're on a mission to give every designer on the planet a
thinking partner. If you believe designers can change the
world but need better tools to do it, read on."
HOW: "We approach design tool-building differently: we start with
methodology, not pixels. We're creating instruments that
amplify designer thinking, not just drawing tools."
WHAT: "We need a Senior Designer who will help shape our
methodology, create specifications, and work with AI
to make design more strategic. 5+ years experience,
Figma proficiency, portfolio showcasing strategic thinking."
```
**Result:** Attracts people who share the WHY, not just people with skills.
---
## Real Applications
### WDS Presentation Project
The WDS landing page messaging uses Golden Circle structure:
**WHY (Hero Section):**
"Providing a thinking partner to every designer on the planet"
**HOW (Value Proposition):**
"Strategic design methodology combined with AI assistance bridges the gap between vision and implementation"
**WHAT (Features Section):**
"Trigger mapping, UX specifications, design system generation, developer handoff"
**See:** [WDS Presentation Product Brief](../examples/WDS-Presentation/docs/1-project-brief/01-product-brief.md)
The Product Brief was developed using WHY-first discovery conversations, ensuring the messaging hierarchy reflects true purpose.
---
## The Biology Behind the Golden Circle
### Three Levels of the Brain
**Neocortex (Outer Brain):**
- Rational thought
- Language
- Analysis
- Processes the WHAT
**Limbic Brain (Middle Brain):**
- Emotions
- Trust
- Loyalty
- Decision-making
- Processes the WHY and HOW
- **NO language capacity** (can't articulate "gut feelings")
**Reptilian Brain (Inner Brain):**
- Survival instincts
- Fight or flight
### Why This Matters
When you communicate WHAT → HOW → WHY:
- You speak to the neocortex (rational)
- People understand but don't feel compelled
- Decisions get stuck in analysis
- "It makes sense but I'm not sure..."
When you communicate WHY → HOW → WHAT:
- You speak to limbic brain (emotional decision center)
- People feel it in their gut
- Decisions feel right
- Then rationalize with WHAT
- "I just know this is right. Plus, look at the features!"
**People don't buy WHAT you do, they buy WHY you do it.**
---
## Common Questions
### Q: What if my WHY is just "to make money"?
**A:** That's not a WHY, that's a result. Ask deeper: WHY does this product need to exist? What problem moved you to solve it? What would the world lose if it didn't exist? Money is the outcome of serving a genuine purpose.
### Q: Doesn't everyone have basically the same WHY?
**A:** No! Compare:
- Apple: "Challenge the status quo"
- Southwest Airlines: "Democratize air travel"
- Harley-Davidson: "Enable personal freedom"
All different WHYs, all inspiring.
### Q: Should I literally say "Our WHY is..."?
**A:** No. Demonstrate it through messaging. Show, don't tell. The Golden Circle is a structural framework, not a script.
### Q: What if I'm building something boring like accounting software?
**A:** Nothing is boring when you start with WHY. Example:
- **Bad WHAT:** "We make accounting software"
- **Good WHY:** "We believe small business owners shouldn't need accounting degrees to understand their finances"
### Q: Can I have multiple WHYs?
**A:** Ideally one core WHY, but it can have dimensions. Don't confuse WHY (purpose) with HOW (values/differentiators).
---
## Using Golden Circle in Your Process
### Step 1: Discover Your WHY
**Personal Exercise (45 minutes):**
1. List stories of when you felt most fulfilled in your work
2. Identify patterns in those stories
3. Look for the purpose beneath the tasks
4. Craft a simple statement: "To [contribution] so that [impact]"
**Team Workshop (2 hours):**
1. Each person shares a story of team at its best
2. Capture themes that emerge
3. Discuss: What do these stories reveal about our purpose?
4. Craft collective WHY statement
**Product-Specific:**
Ask founding team: "Why does this product need to exist beyond making money?"
### Step 2: Define Your HOWs
Your HOWs are your values and differentiators:
**Questions:**
- What makes our approach unique?
- What principles guide our decisions?
- How do we do things differently?
- What would we never compromise on?
**Result:** 3-5 HOWs that explain your methodology
### Step 3: List Your WHATs
This is easy - your products, services, features. But NOW they're contextualized by WHY and HOW.
### Step 4: Restructure Communication
**Audit current messaging:**
- Website: Does it start with WHY?
- Product descriptions: Are they WHAT-heavy?
- About page: Does it lead with purpose?
- Job postings: Do they inspire or just list requirements?
**Rewrite from inside-out (WHY → HOW → WHAT)**
### Step 5: Test With Audience
Show both versions:
- Version A: Traditional (WHAT → HOW → WHY)
- Version B: Golden Circle (WHY → HOW → WHAT)
**Measure:**
- Which resonates more emotionally?
- Which creates stronger intent to act?
- Which people remember better?
---
## Golden Circle Template
Use this template for messaging:
```markdown
## WHY (Purpose/Belief)
We believe [core belief about the world]...
## HOW (Approach/Values)
We do this by [unique approach/methodology]...
Our values:
- [Value 1]
- [Value 2]
- [Value 3]
## WHAT (Products/Services)
We offer:
- [Product/Service 1]
- [Product/Service 2]
- [Product/Service 3]
```
**For Content:**
```markdown
[Headline expressing WHY]
[Subhead explaining HOW]
[Body describing WHAT]
[CTA aligned with WHY]
```
---
## Next Steps
1. **Watch:** Simon Sinek's TEDx talk (18 minutes)
2. **Reflect:** What's your personal or organizational WHY?
3. **Audit:** Review current messaging - does it start with WHY?
4. **Experiment:** Rewrite one piece of content using Golden Circle
5. **Apply:** Use WHY-first approach in next product discovery session
**Related Resources:**
- [Product Exploration Guide](../method/phase-1-product-exploration-guide.md) - Uses WHY-first discovery
- [Value Trigger Chain Guide](../method/value-trigger-chain-guide.md) - Captures user's WHY (driving forces)
- [Trigger Mapping Guide](../method/phase-2-trigger-mapping-guide.md) - Connects business WHY to user WHY
---
*The Golden Circle - People don't buy what you do, they buy why you do it.*

600
src/modules/wds/docs/models/impact-effect-mapping.md Normal file
View File

@ -0,0 +1,600 @@
# Impact/Effect Mapping
**A visual strategic planning technique that connects business goals to user behaviors and features**
**Originated by:** Mijo Balic & Ingrid Domingues (Ottersten) at inUse, Sweden
**Popularized by:** Gojko Adzic, *Impact Mapping* (2012)
**Applied in WDS:** Trigger Mapping, Value Trigger Chains, strategic alignment
---
## What It Is
**Effect Mapping** (the original methodology) and **Impact Mapping** (Gojko Adzic's adaptation) are visual strategic planning techniques that create a map connecting:
1. **Business Goals** (Why are we building this?)
2. **Actors** (Who will help us achieve the goal?)
3. **Impacts** (How should their behavior change?)
4. **Deliverables** (What can we build to create those impacts?)
The result is a visual map that shows the strategic connections between what you build and what you want to achieve.
**Core Structure:**
```
WHY → WHO → HOW → WHAT
Goal → Actors → Behavioral Changes → Features/Deliverables
```
**Example:**
```
Goal: 30% increase in premium conversions
↓
→ Free users
↓
→ Use advanced features more
↓
→ Feature usage analytics dashboard
→ In-app upsell prompts
↓
→ See clear ROI from upgrade
↓
→ ROI calculator
→ Case studies
```
---
## Why It Matters
### The Problem Without Impact/Effect Mapping
Traditional feature roadmaps start with "what to build":
- Features disconnected from business goals
- No clear understanding of WHO will drive success
- Assumptions about user behavior go untested
- Hard to prioritize features objectively
- Teams argue about opinions, not strategy
### The Solution With Impact/Effect Mapping
Strategic clarity from goal to execution:
- Every feature traces back to a business goal
- Clear identification of whose behavior drives success
- Explicit assumptions about behavioral change
- Objective prioritization based on strategic impact
- Alignment across team on WHY before arguing about WHAT
**The Revolutionary Insight:** Users drive business success through their behaviors. Map those connections visually to make better decisions.
---
## How It's Valuable in Strategic Design
### 1. **Prevents Feature Bloat**
Question: "Should we build [feature]?"
Answer: "Does it appear on our Impact Map? Which goal and actor does it serve?"
If it's not on the map, you probably don't need it.
### 2. **Enables Rapid Prioritization**
When features connect to:
- Most important goals
- Most impactful actors
- Most significant behavioral changes
...they rise to the top naturally.
### 3. **Facilitates Strategic Conversations**
Instead of debating features, discuss:
- Are these the right goals?
- Who else could help achieve them?
- What other behavioral changes could work?
- What's the cheapest way to test this impact?
### 4. **Supports Iterative Delivery**
Build minimum features to test behavioral assumptions:
- Ship smallest feature that could change behavior
- Measure actual vs. expected impact
- Adjust based on data
- Add features only if needed
### 5. **Creates Shared Understanding**
Visual map shows entire team:
- Strategic priorities
- How their work connects to goals
- Who they're building for
- What success looks like
---
## Attribution and History
### Effect Management - The Origin (inUse, Sweden)
**Effect Management** was pioneered in the early 2000s by **Mijo Balic** and **Ingrid Domingues (Ottersten)** at **inUse**, a Swedish user experience consultancy.
Their breakthrough insight: Software projects fail not from technical problems, but from building things that don't achieve desired business effects through user behavior.
**Effect Mapping** was their visual technique for:
- Identifying whose behavior drives business success
- Mapping connections from goals → users → behaviors → features
- Making strategic assumptions explicit and testable
**Key Innovation:** Putting USERS in the middle of strategic planning, not just at the end (UX testing).
### Impact Mapping - The Book (Gojko Adzic, 2012)
**Gojko Adzic**, a software consultant, learned about Effect Mapping and saw its power for agile software development. He wrote **"Impact Mapping: Making a Big Impact with Software Products and Projects"** (2012), which:
- Brought Effect Mapping concepts to wider software community
- Adapted the methodology for agile/iterative development
- Added techniques for collaborative map-building
- Provided extensive examples and templates
- Credited Effect Mapping as foundational influence
**Adzic's Contribution:** Making the methodology accessible, practical, and adapted for modern agile workflows.
### Founder's Note
> I personally acquired the insights about the power of the Effect Map back in 2007, and it has served as the philosophical basis for all of my work in UX for almost 20 years. I am eternally grateful for this model that I now have the pleasure to share with the world in an updated version suitable for modern projects.
>
> — _Martin Eriksson, WDS Creator_
---
## Source Materials
### Books
📚 **Impact Mapping: Making a Big Impact with Software Products and Projects**
By Gojko Adzic (2012)
- The most accessible introduction to the methodology
- Practical workshop techniques
- Extensive examples
- Template and guide included
- [Available on Amazon](https://www.amazon.com/Impact-Mapping-Software-Products-Projects/dp/0955683645)
### Websites
🔗 **[ImpactMapping.org](https://www.impactmapping.org)**
- Official Impact Mapping website
- Free resources and templates
- Community examples
- Workshop guides
🔗 **[inUse - Effect Management](https://inuse.se)**
- Original creators of Effect Mapping
- Swedish consultancy pioneering user-centered strategic planning
### Articles
🔗 **"Introducing Impact Mapping"** - Gojko Adzic
[https://www.impactmapping.org/book.html](https://www.impactmapping.org/book.html)
🔗 **"Effect Mapping: Making the right thing"** - Various authors
Search for "Effect Mapping inUse" for historical context
### Videos
🎥 **"Impact Mapping" by Gojko Adzic** - Various conference talks
[Search YouTube for "Gojko Adzic Impact Mapping"](https://www.youtube.com/results?search_query=gojko+adzic+impact+mapping)
🎥 **Workshop recordings and tutorials** - Multiple practitioners
[Search for "Impact Mapping workshop"](https://www.youtube.com/results?search_query=impact+mapping+workshop)
---
## Whiteport Methods That Harness This Model
### [Trigger Mapping Guide](../method/phase-2-trigger-mapping-guide.md)
Whiteport's enhanced adaptation of Effect/Impact Mapping:
**Keeps:**
- Goals → Actors (Users) structure
- Visual mapping technique
- Strategic alignment from business goals to user psychology
**Critical Differences:**
**Solutions NOT on the map:**
- Original Impact/Effect Mapping: Features/deliverables connected to each usage goal
- Problem: Created enormous wall-sized maps, very short shelf life when scope changed
- Trigger Map: Solutions are NOT on the map at all
- Solutions are envisioned AGAINST all driving forces after mapping
- Result: Map stays relevant as features and solutions evolve
**Driving Forces (not just Impacts):**
- Clear distinction between positive (wishes) and negative (fears) driving forces
- Both are mapped and prioritized
- Solutions address both types of forces
**Smaller, Focused Maps:**
- Maximum 3-4 target groups per map
- Manageable number of driving forces per user
- Large projects use multiple Trigger Maps for different software parts
- Not one enormous map covering entire system
**Prioritization:**
- Driving forces and target groups are prioritized
- Some matter more than others
- Guides which forces to address first
**Result:** A compact, long-lived strategic map that guides solution design without becoming outdated.
### [Feature Impact Analysis](../method/phase-2-trigger-mapping-guide.md)
A separate method (also derived from Impact Mapping) that uses the Trigger Map:
**Purpose:** Score and prioritize features based on strategic impact
**Process:**
- Take completed Trigger Map (with prioritized goals, users, driving forces)
- For each potential feature, score its impact on driving forces
- Calculate total strategic value
- Rank features by impact, not opinion
**Result:** Objective feature prioritization based on which features serve the most important driving forces for the most important users toward the most important goals.
**Note:** This is a distinct method that USES the Trigger Map data, to be fair to Impact Mapping's influence on this approach.
### [Value Trigger Chain Guide](../method/value-trigger-chain-guide.md)
Lightweight version extracting core strategic elements:
- Business Goal (from Effect/Impact Mapping)
- Solution (combines Actor context + Impact)
- User (Actor with psychological depth)
- Driving Forces (Positive and negative impacts)
- Customer Awareness (Added positioning layer)
**Result:** Minimum viable strategic context, perfect for quick projects or prototypes.
---
## Imaginary Examples
### Example 1: E-Learning Platform
**Traditional Feature List:**
- Video hosting
- Quiz builder
- Certificate generation
- Discussion forums
- Mobile app
**Impact Map:**
```
GOAL: 50% course completion rate (currently 15%)
WHO: Course students
HOW: Practice more consistently
WHAT:
- Daily practice reminders
- Streak tracking
- Quick 5-min exercises
HOW: Feel accountable to others
WHAT:
- Study groups
- Peer check-ins
- Social progress sharing
WHO: Course instructors
HOW: Identify struggling students early
WHAT:
- Analytics dashboard
- At-risk student alerts
HOW: Provide timely encouragement
WHAT:
- One-click praise
- Automated milestone celebrations
```
**Notice:** No video hosting, no mobile app on the map. Why? They don't directly increase completion rates. The map reveals this.
### Example 2: SaaS Product
**Traditional Roadmap:**
- Advanced reporting
- API integrations
- Custom workflows
- White labeling
**Impact Map:**
```
GOAL: $500K ARR from enterprise customers
WHO: IT managers at mid-size companies
HOW: Reduce security review time from 3 months to 2 weeks
WHAT:
- SOC 2 compliance package
- Security documentation
- Pre-filled questionnaires
HOW: Get buy-in from reluctant teams
WHAT:
- Gradual rollout features
- Team-by-team permissions
- Change management guide
WHO: End users at those companies
HOW: Adopt tool without training
WHAT:
- Import from old tool
- Familiar keyboard shortcuts
- Contextual help
```
**Notice:** Custom workflows appear nowhere. White labeling might not matter. Security and adoption are what drive enterprise sales.
### Example 3: E-Commerce Site
**Goal:** 25% increase in average order value
**Impact Map:**
```
WHO: First-time buyers
HOW: Discover complementary products
WHAT:
- "Complete the look" suggestions
- "Frequently bought together"
HOW: Feel confident about quality
WHAT:
- Detailed product descriptions
- Customer photos/reviews
- Easy returns
WHO: Repeat customers
HOW: Try premium products
WHAT:
- "Upgrade to [premium]" suggestions
- Side-by-side comparisons
- Loyalty rewards toward premium items
HOW: Stock up on favorites
WHAT:
- Subscribe and save
- Bulk discounts
- Replenishment reminders
```
---
## Real Applications
### WDS Presentation Project
The WDS Presentation uses Trigger Mapping (Whiteport's adaptation of Effect/Impact Mapping) to connect business goals to user psychology.
**See:** [WDS Presentation Trigger Map](../examples/WDS-Presentation/docs/2-trigger-map/00-trigger-map.md)
**Strategic Structure:**
- **Business Goals:** Newsletter signups, demo bookings, community growth
- **Actors:** Stina (designer), Lars (executive), Felix (developer)
- **Impacts/Driving Forces:** Each persona's wishes and fears mapped
- **Deliverables:** Landing page sections targeting specific driving forces
The Trigger Map shows WHY each section of the landing page exists and WHO it serves.
---
## How Effect/Impact Mapping Works
### Step 1: Define the Goal (5-10 minutes)
What business outcome do you want?
**Good Goals:**
- Measurable: "30% increase in conversions"
- Time-bound: "500 signups in Q1"
- Specific: "Reduce churn from 8% to 5%"
**Bad Goals:**
- Vague: "Better engagement"
- No metric: "More satisfied users"
- Too many: "Increase revenue, satisfaction, and features"
**Pro Tip:** One map = one primary goal. Make multiple maps if needed.
### Step 2: Identify Actors (15-20 minutes)
WHO can help achieve this goal through their behavior?
**Brainstorm:**
- Direct users (buyers, subscribers, active users)
- Indirect influencers (administrators, decision makers, reviewers)
- Internal actors (support team, sales team)
- External actors (partners, integration users)
**Prioritize:**
- Which actors have biggest potential impact?
- Which are easiest to influence?
- Which represent low-hanging fruit?
### Step 3: Define Impacts (20-30 minutes)
For each key actor: HOW should their behavior change?
**Good Impacts:**
- Specific: "Use feature X twice per week"
- Observable: "Refer at least one colleague"
- Connected to goal: Clear link between behavior and business outcome
**Bad Impacts:**
- Vague: "Be more engaged"
- Internal state: "Understand our value" (not a behavior)
- Disconnected: No clear link to goal
**Brainstorm multiple impacts per actor** - not just one "right" answer.
### Step 4: Generate Deliverables (30-45 minutes)
For each impact: WHAT could we build to enable it?
**Brainstorm widely:**
- Features
- Content
- Processes
- Integrations
- Services
**Don't commit yet** - list options, don't design solutions.
**Pro Tip:** Ask "What's the cheapest way to test if this impact actually helps?" before building the big solution.
### Step 5: Prioritize and Plan (20-30 minutes)
Which deliverables to build first?
**Consider:**
- Strategic importance (closest to goal)
- Certainty (known vs. assumed impact)
- Effort (quick wins vs. major projects)
**Build iteratively:**
1. Start with highest-value, lowest-effort, highest-certainty
2. Measure actual impact
3. Adjust based on data
4. Continue
---
## Common Questions
### Q: How is Impact Mapping different from user stories?
**A:** User stories describe WHAT to build ("As a user, I want..."). Impact Mapping explains WHY we're building it (to change this actor's behavior to achieve this goal). Use Impact Mapping first for strategy, then write user stories for execution.
### Q: How often should I update the map?
**A:** When assumptions prove wrong, goals change, or you discover new actors/impacts. The map is a living document, not a one-time exercise.
### Q: Can I have multiple goals on one map?
**A:** Technically yes, but it gets messy. Better to create separate maps for distinct goals and see where they overlap or conflict.
### Q: What if an actor helps multiple goals?
**A:** That actor appears on multiple maps (or multiple branches if goals are related). This highlights high-leverage users who drive multiple outcomes.
### Q: Should features appear on the map?
**A:** In traditional Impact Mapping, yes. In Whiteport's Trigger Mapping, no - we focus on goals, users, and driving forces for longer shelf life. Features live in separate planning documents.
### Q: How detailed should impacts be?
**A:** Specific enough to measure. "Use more" is too vague. "Log in 3x per week" or "Complete onboarding" are measurable.
---
## Impact Mapping vs. Trigger Mapping
### Traditional Impact Mapping
```
Goal
→ Actor
→ Impact (behavioral change)
→ Deliverable (feature)
→ Deliverable (feature)
→ Impact
→ Deliverable
```
**Pros:**
- Direct connection to features
- Complete strategic picture
- Good for short-term planning
**Cons:**
- Map becomes outdated as features change
- Focuses on behaviors, not psychology
- Positive impacts only (what users DO, not what they AVOID)
### Whiteport Trigger Mapping
```
Goal
→ User (Actor with psychological depth)
→ Driving Force (positive - wish to achieve)
→ Driving Force (negative - fear to avoid)
→ Customer Awareness positioning
[Features live in separate planning docs, reference the map]
```
**Pros:**
- Map stays relevant as features evolve
- Richer psychological insight
- Both positive and negative motivation
- Awareness positioning adds strategic layer
**Cons:**
- Slightly less direct connection to features
- Requires separate feature planning step
**Bottom Line:** Both use the same core strategic insight (users drive business success). Trigger Mapping optimizes for longevity and psychological depth.
---
## Getting Started with Impact/Effect Mapping
### For Your Next Project
1. **Gather team** (30-90 minutes total)
2. **Start with goal:** What business outcome matters most?
3. **List actors:** Who can help achieve it?
4. **Brainstorm impacts:** How should their behavior change?
5. **Generate ideas:** What could we build?
6. **Prioritize:** What to test first?
7. **Build and measure:** Did it work?
### Tools Needed
- Whiteboard or large paper (physical)
- Miro/Mural/FigJam (digital)
- Sticky notes (physical)
- Team with diverse perspectives
### Workshop Format
- **30 minutes:** Intro and goal definition
- **45 minutes:** Actors and impacts
- **30 minutes:** Deliverable ideas
- **15 minutes:** Prioritization and next steps
**Total: 2 hours well spent**
---
## Next Steps
1. **Read:** Get Gojko Adzic's book for full methodology
2. **Try:** Run a simple Impact Mapping session for current project
3. **Compare:** See how Whiteport's Trigger Mapping adapts the concepts
4. **Choose:** Decide if you need quick VTC, full Impact Map, or comprehensive Trigger Map
**Related Resources:**
- [Trigger Mapping Guide](../method/phase-2-trigger-mapping-guide.md) - Whiteport's adaptation
- [Value Trigger Chain Guide](../method/value-trigger-chain-guide.md) - Lightweight version
- [ImpactMapping.org](https://www.impactmapping.org) - Official resources
---
*Impact/Effect Mapping - Strategic clarity from why to what, with users driving success.*

672
src/modules/wds/docs/models/kathy-sierra-badass-users.md Normal file
View File

@ -0,0 +1,672 @@
# Kathy Sierra Badass Users Principles
**User capability, not product features: Making users awesome at what they want to do**
**Originated by:** Kathy Sierra
**Source:** Books, blog (Creating Passionate Users), conference talks (2000s-2010s)
**Applied in WDS:** Component design, microcopy, interaction patterns, user experience optimization
---
## What It Is
**Kathy Sierra's Badass Users Principles** are a collection of user experience insights focused on one revolutionary idea:
**Don't make a better product. Make users better at what they want to do.**
**Core Concepts:**
1. **Badass Users:** Focus on making users feel capable and awesome
2. **Cognitive Resources:** Treat user's mental energy as precious and finite
3. **Perceptual Exposure:** Repeated micro-exposures create expertise
4. **The Suck Zone:** Get users through beginner frustration to competence quickly
5. **Post-UX:** Experience extends beyond your app/product
**The Revolutionary Insight:** Users don't care about your product. They care about being good at something your product helps them do.
---
## Why It Matters
### The Problem Without Kathy Sierra Thinking
Traditional product focus:
- "Look at all our features!"
- Success = feature usage
- UX = making product easy to use
- Help = explaining product
- Marketing = product benefits
**Result:** Products users tolerate but don't love.
### The Solution With Kathy Sierra Thinking
User capability focus:
- "Look at what you can now do!"
- Success = user competence and confidence
- UX = making user feel capable
- Help = making user better at their goal
- Marketing = user transformation
**Result:** Products users evangelize because they feel awesome using them.
**Example:**
**Camera Company A (Product-Focused):**
"Our camera has 47 features! 12 shooting modes! Advanced ISO controls!"
**Camera Company B (Sierra-Style):**
"Take amazing photos in any light. You'll get shots you're proud to share. We'll help you get there fast."
**Which sells more? B. Because people want to be good photographers, not feature-operated.**
---
## How It's Valuable in Strategic Design
### 1. **Component Design**
Traditional: "What does this component do?"
Sierra: "How does this help user feel capable?"
**Example: File Upload**
**Traditional Thinking:**
```
Component: File uploader
Features:
- Drag and drop
- File browser
- Multiple file support
- Progress indicator
```
**Sierra Thinking:**
```
User Goal: Get my files uploaded without thinking about it
Design for Capability:
- HUGE drop zone: "I got this, just drop anywhere"
- Instant visual feedback: "It's working"
- Clear success state: "You did it! 5 files ready"
- Error recovery: "This one didn't work. Try this instead." (not "Error 402")
Result: User feels confident, not anxious
```
### 2. **Microcopy and Messaging**
Traditional: Explain product
Sierra: Build user confidence
**Examples:**
**Empty State:**
- ❌ "No projects available"
- ✅ "Ready to create your first project?"
**Success Message:**
- ❌ "File uploaded successfully"
- ✅ "You're all set! Your report is ready."
**Error Message:**
- ❌ "Invalid input. Error code 422"
- ✅ "Almost there! Try using letters and numbers only."
**Tone Shift:** From system status → to user progress
### 3. **Onboarding Strategy**
Traditional: Teach all features
Sierra: Get to "I can do this!" moment FAST
**Goal:** Cross the "Suck Zone" (frustrating beginner phase) as quickly as possible to reach "I got this!" feeling.
**Approach:**
1. One clear, achievable task
2. Guide through completion
3. Celebrate success
4. User now feels capable
5. Build from there
**Not:**
1. Here's feature 1, 2, 3, 4, 5...
2. Now try yourself
3. Good luck!
### 4. **Progressive Disclosure**
Traditional: Show everything upfront
Sierra: Reveal complexity as user grows
**Principle:** Don't overwhelm beginner with expert features. Let users discover depth as they gain competence.
**Example: Code Editor**
- **Day 1:** Basic editing, syntax highlighting
- **Week 1:** Code completion, snippets
- **Month 1:** Extensions, customization
- **Year 1:** Advanced debugging, profiling
User discovers capabilities aligned with growing skill, never overwhelmed.
### 5. **Cognitive Load Reduction**
Traditional: Assume unlimited mental energy
Sierra: Treat cognitive resources as finite and precious
**Every decision users make depletes mental energy.**
**Design Implications:**
- Sensible defaults (reduce decisions)
- Clear recommended path (reduce analysis)
- Consistent patterns (reduce learning)
- Remove unnecessary choices (reduce paralysis)
**Result:** Users have mental energy for what matters - their actual work.
---
## Attribution and History
### Kathy Sierra - The Teacher Who Changed UX
**Kathy Sierra** is a game developer, programming instructor, and author who revolutionized how we think about user experience in the 2000s.
**Background:**
- Co-created "Head First" book series (O'Reilly)
- Game developer interested in learning and motivation
- Java programmer and teacher
- Conference speaker and blogger
**Breakthrough Work:**
Her blog **"Creating Passionate Users"** (2004-2006) was required reading for UX designers and product people. Though she stopped blogging in 2007, her insights remain foundational.
### Core Teachings
**From "Creating Passionate Users" and Talks:**
1. **"Make users badass, not your product"** - Focus on user capability
2. **"Cognitive resources are precious"** - Reduce mental load
3. **"Get through the suck zone fast"** - Early competence crucial
4. **"Passionate users evangelize"** - Best users are those who feel awesome
5. **"Death by 1000 cuts"** - Small frustrations compound
6. **"Brain-friendly design"** - Work with how brains actually learn
### Influence
Kathy Sierra influenced:
- Modern UX design philosophy
- Product-led growth thinking
- User onboarding best practices
- Technical writing and documentation
- Software craftsmanship movement
- Game design and gamification
**Her Legacy:** Shifted focus from "usability" (can users use it?) to "capability" (do users feel awesome?).
---
## Source Materials
### Books
📚 **Badass: Making Users Awesome**
By Kathy Sierra (2015)
- Her comprehensive book on user capability
- Covers cognitive resources, expertise development, motivation
- Practical framework for creating "badass users"
- [Available on Amazon](https://www.amazon.com/Badass-Making-Awesome-Kathy-Sierra/dp/1491919019)
📚 **Head First Series** (Various Authors, Co-created by Kathy Sierra)
- Revolutionary approach to technical books
- Brain-friendly learning design
- Shows Sierra's principles in action
- Multiple titles on Java, Design Patterns, etc.
### Blog (Archive)
🔗 **Creating Passionate Users (Archive)**
- Original blog (2004-2007)
- Still valuable, still relevant
- [Archived at headrush.typepad.com](http://headrush.typepad.com/)
- Many posts on user capability, cognitive load, learning
**Must-Read Posts:**
- "Kicking Ass"
- "The Physics of Passion: The Koolaid Point"
- "Be a Better [...] by Tomorrow"
- "Cognitive seduction"
- "Users don't care about your product"
### Conference Talks
🎥 **"Building the minimum Badass User"** and others
- Various conferences 2005-2015
- [Search YouTube for "Kathy Sierra"](https://www.youtube.com/results?search_query=kathy+sierra)
### Articles About Her Work
🔗 **"Kathy Sierra on Creating Passionate Users"** - Various interviews and retrospectives
---
## Whiteport Methods That Harness This Model
### Component Specifications
Components designed to make users feel capable:
**Questions to Ask:**
- Does this component make the user feel smart or stupid?
- Does it reduce or increase cognitive load?
- Does it build confidence or create anxiety?
- Does success feel like user's achievement or system's gift?
**Example: Form Validation**
**Traditional:**
```
[User fills form, clicks submit]
"Error: Invalid email format"
"Error: Password must be 8+ characters"
[User feels stupid, frustrated]
```
**Sierra Approach:**
```
[User typing email]
✓ "Got it" [green checkmark appears]
[User typing password]
"Almost there... 6 more characters" → "Perfect! ✓"
[User feels smart, capable]
```
### Microcopy Guidelines
Every piece of text asks: "Does this make the user feel capable?"
**Error Messages:**
- Not: "Error occurred"
- Yes: "Let's fix this together" + specific guidance
**Success States:**
- Not: "Operation completed"
- Yes: "You did it! [What they accomplished]"
**Help Text:**
- Not: "This field requires..."
- Yes: "Pro tip: Use your work email for..." (implies user is becoming pro)
### Interaction Design
Patterns that reduce cognitive load:
**Defaults:** Sensible, let users accept and move on
**Recommendations:** "Most people like this" (reduce analysis)
**Undo:** Fearless exploration, not anxiety
**Progressive Disclosure:** Complexity revealed as skill grows
**Consistent Patterns:** Learn once, apply everywhere
---
## Imaginary Examples
### Example 1: Photo Editing App
**Traditional Product-Focused:**
```
Features Available:
- Brightness
- Contrast
- Saturation
- Hue
- Curves
- Levels
- Color Balance
- Exposure
- Highlights
- Shadows
- [30 more options...]
User: "I just want my photo to look good. I don't know what 'curves' are."
Result: Overwhelmed, gives up, photo still looks bad
```
**Sierra User-Capability-Focused:**
```
What do you want to do?
→ Make colors pop [Quick fix applied] "Looking better!"
→ Fix dark photo [Auto adjustment] "That's brighter!"
→ Get creative [3 curated styles] "Which vibe?"
Result after 30 seconds: Photo looks great
User feeling: "I made this look amazing!"
[Advanced controls available in menu, for when user is ready]
```
**Same app, different philosophy. Second version creates capable, confident users.**
### Example 2: Code Review Tool
**Traditional:**
```
Dashboard shows:
- Open PRs (37)
- Awaiting your review (12)
- Comments (184)
- Approval rate
- Activity feed (endless scroll)
Developer: *anxiety* "Where do I even start?"
Feels: Overwhelmed, behind, stressed
Does: Avoids tool
```
**Sierra Approach:**
```
Good morning, Alex! You've got 3 PRs to review today.
Here's where you'll make the biggest impact:
→ Sarah's login fix (urgent, 5 min) [Review Now]
→ Team's API refactor (big decision needed) [Review Now]
→ Junior dev's first PR (needs guidance) [Review Now]
That's it for today! You're staying on top of things.
[Other 9 PRs in "Later" section, not prominent]
After reviewing Sarah's PR: "Nice catch on that edge case! 2 to go."
Developer: Feels capable, helpful, on track
Does: Reviews PRs confidently
```
### Example 3: Language Learning App
**Traditional:**
```
Lesson 1: Greetings
- Hello = Hola
- Goodbye = Adiós
- Please = Por favor
[10 more phrases]
Quiz:
1. What is "hello" in Spanish?
2. Translate "goodbye"
...
User: Memorizes words for quiz, forgets next day
Feeling: "I'm bad at languages"
```
**Sierra Approach:**
```
You're meeting Maria at a café!
Maria: "¡Hola! ¿Cómo estás?"
[Hola highlighted, sound plays]
→ Tap to say "Hola!" back
You: "¡Hola!"
Maria: *smiles* "¿Cómo te llamas?"
→ "Me llamo [Your name]"
After 5 minutes: You've had a conversation!
"You just ordered coffee in Spanish! 🎉"
User: Had actual (simulated) conversation
Feeling: "I can do this! I spoke Spanish!"
Motivation: Through the roof
```
**Result:** User feels capable, wants to continue.
---
## Real Applications
### WDS Component Specifications
WDS component specs include "User Capability Considerations":
**For each component:**
- What is user trying to accomplish?
- How does this help them feel capable?
- What cognitive load does this add/remove?
- What's the "aha moment" (competence feeling)?
- How do we get them there fast?
**Microcopy Standards:**
- Error messages guide toward success (not blame)
- Success states celebrate user achievement
- Empty states encourage confident action
- Help text implies user competence ("Pro tip" not "Warning")
**See:** [WDS Presentation Example](../examples/WDS-Presentation/) - Components designed for capability
---
## Key Concepts in Detail
### 1. Badass Users (The Goal)
**Not:** Users who tolerate your product
**Yes:** Users who are awesome at what they want to do, partly thanks to your product
**Badass User Characteristics:**
- Feels confident and capable
- Achieves goals efficiently
- Evangelizes to others (because they feel awesome)
- Continues to grow skills
- Values the product (because it makes them valuable)
**Design Question:** "Does this make the user more badass?"
### 2. Cognitive Resources (The Constraint)
**Key Insight:** Users have limited mental energy. Every decision depletes it.
**The Cognitive Budget:**
- User starts day with X units of mental energy
- Every decision costs energy
- Complex decisions cost more
- When depleted: Poor decisions, frustration, giving up
**Design Implication:** Reduce unnecessary cognitive load so users have energy for what matters.
**How to Reduce Cognitive Load:**
- Good defaults (no decision needed)
- Consistent patterns (no re-learning)
- Clear recommendations ("Most popular" saves analysis)
- Remove options (paradox of choice)
- Undo easily (remove fear of mistakes)
### 3. The Suck Zone (The Challenge)
**The Suck Zone:** The frustrating phase between "I want to do this" and "I can do this."
```
Stage 1: "I want to [skill]!" (Excited)
↓
Stage 2: "This is harder than I thought..." (Frustrated)
↓ [The Suck Zone - most users quit here]
↓
Stage 3: "Oh! I get it!" (Breakthrough)
↓
Stage 4: "I can do this!" (Competent, Confident)
```
**Design Goal:** Get users through Suck Zone as fast as possible.
**Strategies:**
- Quick wins early (small success = "I can do this!")
- Clear progress indicators
- Guided practice (not theory)
- Remove unnecessary complexity initially
- Celebrate every success
**Anti-Pattern:** Lengthy tutorials before user does anything = extending Suck Zone
### 4. Perceptual Exposure (The Method)
**Key Insight:** Expertise comes from repeated micro-exposures, not comprehensive study.
**Example: Bird Watching**
- Beginner: "That's a bird"
- Learning: Sees 100 robins (unconsciously absorbs patterns)
- Expert: "That's a robin" (instant recognition without thought)
**Design Application:**
Instead of explaining everything upfront:
- Show patterns repeatedly in context
- Let users absorb unconsciously
- Recognize becomes automatic
- Expertise emerges without feeling like "learning"
**Example: Keyboard Shortcuts**
- Don't make users memorize list
- Show shortcut hint next to menu item (repeated exposure)
- User sees "Cmd+S" every time they click Save
- Eventually: Muscle memory, no thought
### 5. Post-UX (The Context)
**Key Insight:** User experience doesn't end when they close your app.
**Post-UX Questions:**
- Did using our product make them better at their goal?
- Do they feel more capable NOW in their work/life?
- Did we reduce frustration in their broader context?
- Are they better off for having used this?
**Example: Project Management Tool**
**Traditional Metric:** Daily active users
**Sierra Metric:** Do teams ship better products because they used our tool?
**Design Shift:** Optimize for user's life success, not just product engagement.
---
## Common Questions
### Q: Isn't "making users feel capable" just good UX?
**A:** It's a specific lens on UX. Traditional UX asks "Can users complete tasks?" Sierra asks "Do users feel awesome doing it?" Subtle but profound difference.
### Q: What if users actually need to learn complex things?
**A:** Still applies! Get them to first competence quickly, then progressively reveal depth. Expert features come after beginner confidence. Sierra's "Head First" books teach complex programming this way successfully.
### Q: How do I measure "feeling capable"?
**A:**
- Net Promoter Score (but ask WHY)
- "Did you achieve your goal?" (confidence question)
- "How do you feel about your [skill] now?" (capability question)
- Voluntary advocacy (do users tell others?)
- Time to first success (crossing Suck Zone)
### Q: What about power users who want all features visible?
**A:** Progressive disclosure serves them too. They get there faster because they weren't overwhelmed at start. Plus, power users were once beginners - you're making more power users by not losing them early.
### Q: Isn't "celebrating success" patronizing?
**A:** Not if genuine. "You uploaded 5 files" = patronizing. "You're all set! Your team can now access the report" = acknowledging real achievement.
---
## Applying Sierra Principles in Your Design
### Audit Current Design
For each screen/component, ask:
**Capability:**
- Does this make user feel capable or confused?
- What "aha moment" does this create?
- How quickly do they reach "I can do this"?
**Cognitive Load:**
- How many decisions does this require?
- Can we reduce them?
- Are defaults sensible?
- Is this consistent with elsewhere?
**Suck Zone:**
- How long until first success?
- What's blocking quick competence?
- Can we delay complexity?
**Post-UX:**
- Does using this make user better at their real goal?
- Is their life better for this interaction?
### Redesign Toward Capability
**Before:** Feature-focused
**After:** Capability-focused
**Changes:**
- Microcopy: From system status → user progress
- Defaults: From neutral → sensible for user goal
- Errors: From blame → guidance
- Success: From confirmation → celebration
- Order: From complete → progressive
- Focus: From product → user becoming badass
---
## Sierra Principles Checklist
**For Any Design:**
- [ ] Does this make the user feel smart?
- [ ] Have we reduced cognitive load?
- [ ] Can user succeed quickly (cross Suck Zone)?
- [ ] Are we revealing complexity progressively?
- [ ] Does microcopy build confidence?
- [ ] Do errors guide without blaming?
- [ ] Do successes feel like user's achievement?
- [ ] Are defaults sensible for user's goal?
- [ ] Does this work with how brains actually work?
- [ ] Will user be better at their real goal after this?
**If you answered "no" to any:** Redesign opportunity.
---
## Next Steps
1. **Read:** "Badass: Making Users Awesome" by Kathy Sierra
2. **Archive:** Browse her old blog "Creating Passionate Users"
3. **Audit:** Choose one component - does it make users feel capable?
4. **Redesign:** Rewrite microcopy for one flow with capability focus
5. **Test:** Do users feel more confident after new version?
**Related Resources:**
- [Value Trigger Chain Guide](../method/value-trigger-chain-guide.md) - Driving forces include capability desires
- [Action Mapping Model](./action-mapping.md) - Similar philosophy: focus on what users DO
- [Phase 4: UX Design Guide](../method/phase-4-ux-design-guide.md) - Scenario design with user capability in mind
---
*Kathy Sierra Principles - Don't make a better product. Make users better at what they want to do.*

266
src/modules/wds/docs/models/models-guide.md Normal file
View File

@ -0,0 +1,266 @@
# Strategic Design Models
Foundational frameworks from thought leaders that inform WDS methodology.
---
## What This Folder Contains
**Models** are external frameworks created by industry pioneers. These are NOT Whiteport inventions - they're time-tested approaches we've adapted and integrated into our methods.
Each model includes:
- What it is and why it matters
- Full attribution to original creators
- Source materials (books, articles, videos)
- How WDS methods harness it
- Practical examples and applications
---
## Available Models
### [Customer Awareness Cycle](./customer-awareness-cycle.md)
**By:** Eugene Schwartz (1966)
**Core Idea:** Meet users where they are in their awareness journey (Unaware → Problem Aware → Solution Aware → Product Aware → Most Aware)
**Applied in WDS:**
- Scenario definition (where user starts/ends)
- Content strategy (matching depth to awareness)
- Messaging hierarchy
**When to Use:** Positioning content, defining scenario goals, structuring communication
---
### [Impact/Effect Mapping](./impact-effect-mapping.md)
**By:** Mijo Balic & Ingrid Domingues (inUse), popularized by Gojko Adzic
**Core Idea:** Visual strategic planning connecting business goals → actors → behavioral impacts → deliverables
**Applied in WDS:**
- Trigger Mapping (Whiteport's enhanced adaptation)
- Value Trigger Chains (lightweight version)
- Strategic alignment from why to what
**When to Use:** Strategic planning, feature prioritization, aligning team on goals
---
### [Golden Circle](./golden-circle.md)
**By:** Simon Sinek (2009)
**Core Idea:** Inspire action by communicating WHY → HOW → WHAT (inside-out), not outside-in
**Applied in WDS:**
- Product Brief discovery conversations
- Messaging hierarchy and positioning
- Stakeholder alignment
- Content structure
**When to Use:** Defining product purpose, structuring communication, conducting discovery
---
### [Action Mapping](./action-mapping.md)
**By:** Cathy Moore (2008+)
**Core Idea:** Focus on what people DO (actions), not what they KNOW (information). Design practice, not presentations.
**Applied in WDS:**
- Scenario design (action-oriented)
- Onboarding flows (guided practice)
- Help documentation (task-focused)
- Component specifications (enabling action)
**When to Use:** Designing scenarios, onboarding, help systems, any behavior change context
---
### [Kathy Sierra Badass Users](./kathy-sierra-badass-users.md)
**By:** Kathy Sierra (2000s-2015)
**Core Idea:** Don't make a better product. Make users better at what they want to do. Focus on user capability.
**Applied in WDS:**
- Component design (making users feel capable)
- Microcopy (building confidence, not just informing)
- Interaction patterns (reducing cognitive load)
- Success/error messaging (celebrating/guiding)
**When to Use:** Any design decision - always ask "Does this make the user feel capable?"
---
## Models vs. Methods
### Models (This Folder)
**What:** External frameworks from thought leaders
**Purpose:** Foundational knowledge
**Attribution:** Full credit to original creators
**Content:** What it is, why it matters, how to use it
**Location:** `docs/models/`
### Methods (Method Folder)
**What:** Whiteport's instruments and processes
**Purpose:** Practical application
**Attribution:** Derived from models (with credit)
**Content:** Step-by-step how-to, integration into WDS
**Location:** `docs/method/`
**Example:**
- **Model:** Impact/Effect Mapping (Adzic/inUse)
- **Method:** Trigger Mapping (Whiteport's adaptation)
---
## How These Models Work Together
### In Product Discovery
**Golden Circle** → Structure discovery conversations (WHY → HOW → WHAT)
**Impact/Effect Mapping** → Map strategic connections
**Customer Awareness** → Position target users
**Result:** Product Brief with purpose, strategy, and positioning
### In Trigger Mapping
**Impact/Effect Mapping** → Core structure (Goals → Users → Impacts)
**Customer Awareness** → Add awareness positioning
**Golden Circle** → Understand user's WHY (driving forces)
**Result:** Trigger Map connecting business goals to user psychology
### In Scenario Design
**Action Mapping** → Focus on what users DO
**Customer Awareness** → Define awareness progression
**Kathy Sierra** → Make users feel capable
**Result:** Scenarios that change behavior and build confidence
### In Component Design
**Kathy Sierra** → User capability focus
**Action Mapping** → Enable action, not just display
**Customer Awareness** → Match content depth to user
**Result:** Components that make users feel awesome
---
## Using These Models
### 1. Learn the Model
Read the model guide to understand:
- Core concepts
- Why it was created
- How it works
### 2. See WDS Application
Each model guide shows how Whiteport methods harness it. Follow those links to see practical integration.
### 3. Apply in Your Work
Use the templates and examples to apply the model in your projects.
### 4. Combine Multiple Models
Most powerful when used together. Each model addresses different aspects of strategic design.
---
## Recommended Reading Order
### For Beginners
1. **Golden Circle** - Easiest to grasp, immediately applicable
2. **Customer Awareness Cycle** - Changes how you see content
3. **Action Mapping** - Shifts focus to behavior
4. **Kathy Sierra Principles** - Deepens UX thinking
5. **Impact/Effect Mapping** - Strategic planning foundation
### For Strategic Planning
1. **Impact/Effect Mapping** - Core strategic framework
2. **Golden Circle** - Purpose and communication
3. **Customer Awareness Cycle** - User positioning
### For UX Design
1. **Kathy Sierra Principles** - User capability focus
2. **Action Mapping** - Behavior over information
3. **Customer Awareness Cycle** - Content depth matching
### For Content Creation
1. **Customer Awareness Cycle** - Positioning content
2. **Golden Circle** - Structure and hierarchy
3. **Kathy Sierra Principles** - Building confidence
---
## Attribution and Gratitude
These models represent decades of insight from brilliant thinkers who've shaped how we approach design and strategy:
- **Eugene Schwartz** - Understanding awareness and positioning
- **Mijo Balic & Ingrid Domingues** - Connecting goals to user behavior
- **Gojko Adzic** - Making strategic planning accessible
- **Simon Sinek** - Teaching us to start with WHY
- **Cathy Moore** - Focusing on action over information
- **Kathy Sierra** - Championing user capability
**Whiteport stands on the shoulders of giants. We're grateful for their contributions to the field.**
---
## Contributing to This Collection
Have a model you think should be included? Consider these criteria:
**Inclusion Criteria:**
- External (not created by Whiteport)
- Well-documented by original creator
- Time-tested (proven over years)
- Applicable to strategic design
- Influences WDS methodology
- Proper attribution possible
**Doesn't Include:**
- Whiteport-created methods (those go in `method/`)
- Temporary trends or fads
- Frameworks without clear attribution
- Overly niche or specialized concepts
---
## External Resources
Want to dive deeper? Each model guide includes books, articles, videos, and websites from the original creators. Start there for comprehensive understanding.
**Quick Links:**
- [ImpactMapping.org](https://www.impactmapping.org) - Impact Mapping resources
- [Blog.Cathy-Moore.com](https://blog.cathy-moore.com) - Action Mapping blog
- [SimonSinek.com](https://simonsinek.com) - Golden Circle resources
- Eugene Schwartz's "Breakthrough Advertising" (book)
- Kathy Sierra's "Badass: Making Users Awesome" (book)
---
## Related Documentation
- **[WDS Method Guides](../method/)** - How Whiteport applies these models
- **[Learn WDS Course](../learn-wds/)** - Step-by-step learning path
- **[Examples](../examples/)** - See models in action
- **[Getting Started](../getting-started/)** - Quick start with WDS
---
*Strategic Design Models - Standing on the shoulders of giants.*

4
src/modules/wds/docs/wds-workflows-guide.md
View File

@ -14,7 +14,7 @@ wds/
├── agents/ # WDS specialized agents (Norse Pantheon)
│ ├── saga-analyst.agent.yaml # Saga-Analyst - Business & Product Analyst
│ ├── idunn-pm.agent.yaml # Idunn-WDS-PM - Product Manager
│ └── freyja-ux.agent.yaml # Freyja-WDS-Designer - UX/UI Designer
│ └── freya-ux.agent.yaml # Freya-WDS-Designer - UX/UI Designer
├── workflows/ # Phase-selectable design workflows
├── data/ # Standards, frameworks, presentations
│ └── presentations/ # Agent introduction presentations
@ -58,7 +58,7 @@ WDS creates an alphabetized folder structure in the user's `docs/` folder:
| ----------------------- | ------------------------- | -------------------------- | ----------------------------------- |
| **Saga the Analyst** | `saga-analyst.agent.yaml` | Business & Product Analyst | Goddess of stories & wisdom |
| **Idunn the PM** | `idunn-pm.agent.yaml` | Product Manager | Goddess of renewal & youth |
| **Freyja the Designer** | `freyja-ux.agent.yaml` | UX/UI Designer | Goddess of beauty, magic & strategy |
| **Freya the Designer** | `freya-ux.agent.yaml` | UX/UI Designer | Goddess of beauty, magic & strategy |
## Conventions

4
src/modules/wds/workflows/00-system/language-flow-diagram.md
View File

@ -63,7 +63,7 @@ config:
## 3. Phase 4 Agent Reads Config
**Agent:** Freyja (WDS Designer)
**Agent:** Freya (WDS Designer)
**When starting Phase 4:**
@ -313,7 +313,7 @@ function setLanguage(lang: 'en' | 'se') {
▼
┌─────────────────────────────────────┐
│ 3. Phase 4: UX Design │
│ Freyja agent loads config │
│ Freya agent loads config │
│ Knows: Specs in EN, Content in │
│ EN + SE │
└──────────────┬──────────────────────┘

4
src/modules/wds/workflows/00-system/wds-workflow-status-template.yaml
View File

@ -86,12 +86,12 @@ workflow_status: "{{workflow_items}}"
# - proofs-of-concept/
# phase_4_ux_design:
# status: required
# agent: freyja-wds-designer
# agent: freya-wds-designer
# folder: C-Scenarios/
# artifacts: [] # Grows as scenarios are created
# phase_5_design_system:
# status: conditional # or skipped
# agent: freyja-wds-designer
# agent: freya-wds-designer
# folder: D-Design-System/
# artifacts:
# - component-showcase.html

19
src/modules/wds/workflows/1-project-brief/alignment-signoff/pitch.template.md
View File

@ -68,6 +68,25 @@
---
## Value Trigger Chain
**Strategic Summary** - [View full VTC](./vtc-primary.yaml)
This project serves:
- **Business Goal:** {{vtc_business_goal}}
- **Solution:** {{vtc_solution}}
- **Primary User:** {{vtc_user}}
**What drives them:**
- *Wants to:* {{vtc_positive_forces}}
- *Wants to avoid:* {{vtc_negative_forces}}
**Awareness Journey:** {{vtc_awareness_start}} → {{vtc_awareness_end}}
This strategic chain ensures every design decision serves the user's psychology while achieving business goals.
---
## Next Steps
**After approval**, proceed to:

2
src/modules/wds/workflows/1-project-brief/alignment-signoff/substeps/03-synthesize-present/18-synthesize-document.md
View File

@ -37,5 +37,5 @@ Help crystallize into a clear, compelling narrative using framework thinking:
## Next Step
After creating the alignment document:
→ `19-present-for-approval.md` (same folder)
→ `18.5-create-vtc.md` (same folder)

76
src/modules/wds/workflows/1-project-brief/alignment-signoff/substeps/03-synthesize-present/18.5-create-vtc.md Normal file
View File

@ -0,0 +1,76 @@
# Substep 18.5: Create Value Trigger Chain
**Purpose**: Create a simplified VTC to strengthen the pitch with strategic clarity
---
## Instruction
**After creating the alignment document**:
"Before we present this for approval, let's create a Value Trigger Chain (VTC) to add strategic clarity to your pitch.
A VTC is a simplified strategic summary that captures:
- **Business Goal** - What measurable outcome you want
- **Solution** - What you're building
- **User** - Who the primary user is
- **Driving Forces** - What motivates them (positive + negative)
- **Customer Awareness** - Where they start and where you move them
This takes about 20-30 minutes and gives stakeholders a clear, strategic view of the project. It will be added to your pitch document.
Shall we create the VTC now?"
---
## If User Agrees
Load and execute the VTC Workshop Router:
`../../../shared/vtc-workshop/vtc-workshop-router.md`
**Note:** At pitch stage, there's typically NO Trigger Map yet, so router will likely send you to the **Creation Workshop**.
### Leverage Pitch Context
**Important:** You have extensive context from the pitch sections! Use it:
- **Business Goal:** From "Value We'll Create" and "Why It Matters"
- **Solution:** From "Recommended Solution"
- **User:** From "Why It Matters" (who we help)
- **Driving Forces:** Infer from "Why It Matters" and "Cost of Inaction"
- **Customer Awareness:** Infer from "The Realization" and solution approach
**Don't start from zero** - use the strategic work already completed.
### Save VTC
VTC should be saved to:
`docs/1-project-brief/vtc-primary.yaml`
### Add VTC to Pitch
After VTC is created, add it to the pitch document using the template placeholders.
---
## If User Declines
**If user says:** "Let's skip the VTC for now"
**Response:**
> "No problem! You can create a VTC later using:
> `src/modules/wds/workflows/shared/vtc-workshop/vtc-workshop-router.md`
>
> However, I recommend creating it before presenting to stakeholders. It takes 30 minutes and provides powerful strategic clarity that helps secure buy-in.
>
> You can also add it after stakeholder feedback if needed."
Then proceed to next step.
---
## Next Step
After VTC is created (or declined):
→ `19-present-for-approval.md` (same folder)

9
src/modules/wds/workflows/1-project-brief/alignment-signoff/workflow.md
View File

@ -86,7 +86,7 @@
**Workflow Phases** (organized in subfolders):
1. **Start & Understand** (`01-start-understand/`) - substeps 01-05
2. **Explore Sections** (`02-explore-sections/`) - substeps 06-16 (flexible order)
3. **Synthesize & Present** (`03-synthesize-present/`) - substeps 17-19
3. **Synthesize & Present** (`03-synthesize-present/`) - substeps 17-19 (includes VTC creation at 18.5)
4. **Generate Signoff** (`04-generate-signoff/`) - substeps 20-21
5. **Build Contract** (`05-build-contract/`) - substeps 22-33
6. **Build Internal Signoff** (`06-build-signoff-internal/`) - substeps 34-35
@ -119,8 +119,15 @@ The alignment document (pitch) covers 10 sections:
**Alignment Document (Pitch)**: `docs/1-project-brief/pitch.md` (Always generated)
- Clear, brief, readable in 2-3 minutes
- Makes the case for the project
- Includes Value Trigger Chain (VTC) for strategic clarity
- Share with clients/stakeholders for approval
**Value Trigger Chain**: `docs/1-project-brief/vtc-primary.yaml` (Recommended)
- Simplified strategic summary
- Business Goal → Solution → User → Driving Forces → Awareness
- Strengthens pitch with clear strategic reasoning
- Takes 20-30 minutes to create
**Signoff Document** (Generated AFTER alignment acceptance):
- **Project Contract**: `docs/1-project-brief/contract.md` - For consultant → client (after client accepts alignment document)
- **Service Agreement**: `docs/1-project-brief/service-agreement.md` - For business → suppliers (after suppliers accept alignment document)

60
src/modules/wds/workflows/1-project-brief/project-brief/complete/project-brief.template.md
View File

@ -82,12 +82,72 @@
---
## Tone of Voice
**For UI Microcopy & System Messages**
### Tone Attributes
1. **{{tone_attribute_1}}**: {{tone_description_1}}
2. **{{tone_attribute_2}}**: {{tone_description_2}}
3. **{{tone_attribute_3}}**: {{tone_description_3}}
{{#if tone_attribute_4}}4. **{{tone_attribute_4}}**: {{tone_description_4}}{{/if}}
{{#if tone_attribute_5}}5. **{{tone_attribute_5}}**: {{tone_description_5}}{{/if}}
### Examples
**Error Messages:**
- ✅ {{tone_example_error_good}}
- ❌ {{tone_example_error_bad}}
**Button Text:**
- ✅ {{tone_example_button_good}}
- ❌ {{tone_example_button_bad}}
**Empty States:**
- ✅ {{tone_example_empty_good}}
- ❌ {{tone_example_empty_bad}}
**Success Messages:**
- ✅ {{tone_example_success_good}}
- ❌ {{tone_example_success_bad}}
### Guidelines
**Do:**
{{tone_do_guidelines}}
**Don't:**
{{tone_dont_guidelines}}
---
*Note: Tone of Voice applies to UI microcopy (labels, buttons, errors, system messages). Strategic content (headlines, feature descriptions, value propositions) uses the Content Creation Workshop based on page-specific purpose and context.*
---
## Additional Context
{{additional_context}}
---
## Value Trigger Chain
**Strategic Summary** - [View full VTC](./vtc-primary.yaml)
- **Business Goal:** {{vtc_business_goal}}
- **Solution:** {{vtc_solution}}
- **User:** {{vtc_user}}
- **Driving Forces:**
- *Wants to:* {{vtc_positive_forces}}
- *Wants to avoid:* {{vtc_negative_forces}}
- **Awareness Journey:** {{vtc_awareness_start}} → {{vtc_awareness_end}}
This VTC provides quick strategic reference and will inform all design decisions.
---
## Next Steps
This complete brief provides strategic foundation for all design work:

2
src/modules/wds/workflows/1-project-brief/project-brief/complete/steps/step-03-positioning.md
View File

@ -22,7 +22,7 @@ Guide user through positioning framework. Ask them to complete the positioning s
## Next Step
After defining positioning, proceed to step-04-business-model.md
Load, read full file, and execute: `step-04-create-vtc.md`
## State Update

118
src/modules/wds/workflows/1-project-brief/project-brief/complete/steps/step-04-create-vtc.md Normal file
View File

@ -0,0 +1,118 @@
# Step 4: Create Value Trigger Chain
## Purpose
Create a simplified Value Trigger Chain (VTC) to crystallize strategic thinking early and guide all subsequent discovery.
## Context for Agent
You now have Vision and Positioning - the essential product idea. Before diving into detailed discovery, we'll create a VTC to serve as a **strategic benchmark**. This forces early clarity and ensures all subsequent work aligns with core strategy.
This VTC will be used for:
- **Strategic benchmark** - "Does this align with our VTC?"
- **Guiding discovery** - Informs questions about users, success criteria, etc.
- **Early validation** - If VTC isn't clear, vision needs work
- **Quick reference** - One-page strategy throughout project
## Instructions
### 1. Explain VTC to User
> "Now that we have your vision and positioning, let's create a Value Trigger Chain (VTC).
>
> This is a strategic benchmark that will guide all remaining discovery work. It captures:
> - **Business Goal** - What measurable outcome we want
> - **Solution** - What we're building
> - **User** - Who the primary user is
> - **Driving Forces** - What motivates them (positive + negative)
> - **Customer Awareness** - Where they start and where we move them
>
> This takes 20-30 minutes but is incredibly valuable. It forces strategic clarity NOW and gives us a benchmark to evaluate all future decisions against.
>
> As we continue discovery (business model, users, success criteria), we'll use this VTC to ensure everything aligns.
>
> Shall we create the VTC now?"
### 2. Route to VTC Workshop
**If user agrees:**
Load and execute the VTC Workshop Router:
`{project-root}/{bmad_folder}/wds/workflows/shared/vtc-workshop/vtc-workshop-router.md`
**Note:** Since Product Brief stage typically has NO Trigger Map yet, the router will likely send you to the **Creation Workshop**.
### 3. Leverage Vision and Positioning Context
**Important:** You have vision and positioning completed! Use it:
- **Solution:** From vision (what we're building)
- **Business Goal:** Infer from vision (what outcome we want)
- **User:** From positioning (target_customer)
- **Driving Forces:** Infer from positioning (need/opportunity, differentiator)
- **Customer Awareness:** Infer from positioning (where they are now)
**Don't start from zero** - use the strategic work already completed.
**Note:** At this stage, estimates are fine. The VTC will be validated and refined as we discover more detail in later steps.
### 4. Save VTC
VTC should be saved to:
`{output_folder}/A-Product-Brief/vtc-primary.yaml`
### 5. Save VTC (Brief Integration Later)
VTC is saved but NOT yet added to brief document.
**Why:** Product Brief document isn't complete yet. We'll add VTC section during final synthesis (Step 11).
**For now:** VTC exists as separate file and serves as strategic benchmark for remaining discovery steps.
### 6. Confirm Completion and Set Expectation
> "Excellent! We've created your Value Trigger Chain.
>
> This VTC will serve as our strategic benchmark. As we continue discovery (business model, target users, success criteria, etc.), we'll use this VTC to ensure everything aligns.
>
> If anything in remaining discovery contradicts this VTC, it means either:
> - The VTC needs adjustment (vision wasn't clear enough)
> - The discovery finding doesn't serve our strategy
>
> We'll validate and refine the VTC during final synthesis if needed.
>
> Let's continue with the detailed discovery!"
## Next Step
Load, read full file, and execute: `step-05-business-model.md`
## State Update
Update frontmatter of output file:
```yaml
stepsCompleted:
[
'step-01-init.md',
'step-02-vision.md',
'step-03-positioning.md',
'step-04-create-vtc.md',
]
status: 'in-progress'
```
## If User Declines VTC
**If user says:** "Let's skip the VTC for now"
**Response:**
> "No problem! You can create a VTC later using:
> `{bmad_folder}/wds/workflows/shared/vtc-workshop/vtc-workshop-router.md`
>
> However, I recommend creating it before pitching to stakeholders or starting Phase 4 (UX Design). It takes 30 minutes and provides valuable strategic clarity.
>
> Product Brief is complete. You can add VTC anytime."
Then proceed to mark workflow as complete.

2
src/modules/wds/workflows/1-project-brief/project-brief/complete/steps/step-04-business-model.md → src/modules/wds/workflows/1-project-brief/project-brief/complete/steps/step-05-business-model.md
View File

@ -21,6 +21,6 @@ After determining business model, proceed to step-05-business-customers.md if B2
Update frontmatter of output file:
```yaml
stepsCompleted: ['step-01-init.md', 'step-02-vision.md', 'step-03-positioning.md', 'step-04-business-model.md']
stepsCompleted: ['step-01-init.md', 'step-02-vision.md', 'step-03-positioning.md', 'step-04-create-vtc.md', 'step-05-business-model.md']
business_model: '[b2b/b2c/both]'
```

2
src/modules/wds/workflows/1-project-brief/project-brief/complete/steps/step-05-business-customers.md → src/modules/wds/workflows/1-project-brief/project-brief/complete/steps/step-06-business-customers.md
View File

@ -22,7 +22,7 @@ Update frontmatter of output file:
```yaml
stepsCompleted:
['step-01-init.md', 'step-02-vision.md', 'step-03-positioning.md', 'step-04-business-model.md', 'step-05-business-customers.md']
['step-01-init.md', 'step-02-vision.md', 'step-03-positioning.md', 'step-04-create-vtc.md', 'step-05-business-model.md', 'step-06-business-customers.md']
business_customer_profile: '[captured business customer profile]'
buying_roles: '[captured buying roles]'
```

5
src/modules/wds/workflows/1-project-brief/project-brief/complete/steps/step-06-target-users.md → src/modules/wds/workflows/1-project-brief/project-brief/complete/steps/step-07-target-users.md
View File

@ -31,8 +31,9 @@ stepsCompleted:
'step-02-vision.md',
'step-03-positioning.md',
'step-04-business-model.md',
'step-05-business-customers.md',
'step-06-target-users.md',
'step-05-business-model.md',
'step-06-business-customers.md',
'step-07-target-users.md',
]
ideal_user_profile: '[captured user profile]'
secondary_users: '[captured secondary users]'

5
src/modules/wds/workflows/1-project-brief/project-brief/complete/steps/step-07-success-criteria.md → src/modules/wds/workflows/1-project-brief/project-brief/complete/steps/step-08-success-criteria.md
View File

@ -32,8 +32,9 @@ stepsCompleted:
'step-03-positioning.md',
'step-04-business-model.md',
'step-05-business-customers.md',
'step-06-target-users.md',
'step-07-success-criteria.md',
'step-06-business-customers.md',
'step-07-target-users.md',
'step-08-success-criteria.md',
]
success_criteria: '[captured success criteria]'
```

5
src/modules/wds/workflows/1-project-brief/project-brief/complete/steps/step-08-competitive-landscape.md → src/modules/wds/workflows/1-project-brief/project-brief/complete/steps/step-09-competitive-landscape.md
View File

@ -33,8 +33,9 @@ stepsCompleted:
'step-04-business-model.md',
'step-05-business-customers.md',
'step-06-target-users.md',
'step-07-success-criteria.md',
'step-08-competitive-landscape.md',
'step-07-target-users.md',
'step-08-success-criteria.md',
'step-09-competitive-landscape.md',
]
competitive_landscape: '[captured competitive analysis]'
unfair_advantage: '[captured unfair advantage]'

7
src/modules/wds/workflows/1-project-brief/project-brief/complete/steps/step-09-constraints.md → src/modules/wds/workflows/1-project-brief/project-brief/complete/steps/step-10-constraints.md
View File

@ -18,7 +18,7 @@ Guide user to identify constraints including timeline, budget, technical require
## Next Step
After capturing constraints, proceed to step-10-synthesize.md
After capturing constraints, proceed to step-11-tone-of-voice.md
## State Update
@ -34,8 +34,9 @@ stepsCompleted:
'step-05-business-customers.md',
'step-06-target-users.md',
'step-07-success-criteria.md',
'step-08-competitive-landscape.md',
'step-09-constraints.md',
'step-08-success-criteria.md',
'step-09-competitive-landscape.md',
'step-10-constraints.md',
]
constraints: '[captured constraints]'
additional_context: '[captured additional context]'

133
src/modules/wds/workflows/1-project-brief/project-brief/complete/steps/step-11-create-vtc.md Normal file
View File

@ -0,0 +1,133 @@
# Step 11: Create Value Trigger Chain
## Purpose
Create a simplified Value Trigger Chain (VTC) to capture strategic essence for stakeholder communication.
## Context for Agent
The Product Brief contains comprehensive strategic foundation. Now we'll distill this into a focused VTC that captures the essential strategic chain: Business Goal → Solution → User → Driving Forces → Customer Awareness.
This VTC will be used for:
- Pitching the project to stakeholders
- Quick strategic reference during design
- Foundation for scenario-specific VTCs later
## Instructions
### 1. Explain VTC to User
> "Before we finalize the Product Brief, let's create a Value Trigger Chain (VTC).
>
> This is a simplified strategic summary that captures:
> - **Business Goal** - What measurable outcome we want
> - **Solution** - What we're building
> - **User** - Who the primary user is
> - **Driving Forces** - What motivates them (positive + negative)
> - **Customer Awareness** - Where they start and where we move them
>
> This will take about 20-30 minutes and gives you a powerful one-page strategic foundation.
>
> Shall we create the VTC now?"
### 2. Route to VTC Workshop
**If user agrees:**
Load and execute the VTC Workshop Router:
`{project-root}/{bmad_folder}/wds/workflows/shared/vtc-workshop/vtc-workshop-router.md`
**Note:** Since Product Brief stage typically has NO Trigger Map yet, the router will likely send you to the **Creation Workshop**.
### 3. Leverage Product Brief Context
**Important:** You have extensive context from the Product Brief! Use it:
- **Business Goal:** From success_criteria
- **Solution:** From vision
- **User:** From ideal_user_profile
- **Driving Forces:** Infer from positioning, need/opportunity, and user profile
- **Customer Awareness:** Infer from positioning and target customer
**Don't start from zero** - use the strategic work already completed.
### 4. Save VTC
VTC should be saved to:
`{output_folder}/A-Product-Brief/vtc-primary.yaml`
### 5. Add VTC to Brief
After VTC is created, add it to the Product Brief document BEFORE the "Next Steps" section:
```markdown
---
## Value Trigger Chain
**Strategic Summary** - [View full VTC](./vtc-primary.yaml)
- **Business Goal:** [primary goal]
- **Solution:** [solution]
- **User:** [user name/type]
- **Driving Forces:**
- *Wants to:* [positive forces]
- *Wants to avoid:* [negative forces]
- **Awareness Journey:** [start stage] → [end stage]
This VTC provides quick strategic reference and will inform all design decisions.
---
```
### 6. Confirm Completion
> "Excellent! Your Product Brief now includes a Value Trigger Chain.
>
> This VTC will:
> - Help you pitch the project to stakeholders
> - Guide early design decisions
> - Serve as foundation for scenario-specific VTCs in Phase 4
>
> Product Brief is now complete!"
## Next Step
Workflow complete. Update state and present completion.
## State Update
Update frontmatter of output file:
```yaml
stepsCompleted:
[
'step-01-init.md',
'step-02-vision.md',
'step-03-positioning.md',
'step-04-business-model.md',
'step-05-business-customers.md',
'step-06-target-users.md',
'step-07-success-criteria.md',
'step-08-competitive-landscape.md',
'step-09-constraints.md',
'step-10-synthesize.md',
'step-11-create-vtc.md',
]
status: 'complete'
```
## If User Declines VTC
**If user says:** "Let's skip the VTC for now"
**Response:**
> "No problem! You can create a VTC later using:
> `{bmad_folder}/wds/workflows/shared/vtc-workshop/vtc-workshop-router.md`
>
> However, I recommend creating it before pitching to stakeholders or starting Phase 4 (UX Design). It takes 30 minutes and provides valuable strategic clarity.
>
> Product Brief is complete. You can add VTC anytime."
Then proceed to mark workflow as complete.

258
src/modules/wds/workflows/1-project-brief/project-brief/complete/steps/step-11-tone-of-voice.md Normal file
View File

@ -0,0 +1,258 @@
# Step 11: Define Tone of Voice
## Purpose
Establish the product's communication personality and style for consistent UI microcopy and system messages throughout the product.
## Context for Agent
Now that you understand the product, users, positioning, and competitive landscape, you can suggest an appropriate Tone of Voice that aligns with the brand and resonates with target users.
**Important:** Tone of Voice is for **UI microcopy** (buttons, labels, errors, system messages), NOT strategic content (headlines, feature descriptions, value propositions).
## Key Elements
### What is Tone of Voice?
Tone of Voice defines:
- **Brand personality:** Who are we as a company?
- **Communication style:** How do we speak to users?
- **Emotional tone:** What feeling do we create?
- **Voice attributes:** Friendly, professional, quirky, authoritative, empathetic, technical, casual, formal, playful, serious, etc.
### Tone of Voice vs Strategic Content
**Tone of Voice applies to:**
- ✅ Form field labels ("Email" vs "Email address" vs "Your email")
- ✅ Button text ("Submit" vs "Continue" vs "Let's go")
- ✅ Error messages ("Invalid email" vs "Hmm, that doesn't look like an email")
- ✅ System messages ("Loading..." vs "Hang tight..." vs "Processing your request")
- ✅ Empty states ("No items" vs "Nothing here yet" vs "Your list is empty")
- ✅ Tooltips and instructions
**Strategic Content uses:**
- ❌ Content Creation Workshop (purpose-driven, context-specific)
- ❌ Headlines, hero sections, feature descriptions
- ❌ Value propositions, testimonials, case studies
## Instructions
### 1. Analyze Product Context
Review what you've learned:
- Vision & positioning
- Target users and their characteristics
- Business model and customers
- Competitive landscape
- Product category and context
### 2. Suggest Tone of Voice Attributes
Based on the product context, suggest 3-5 tone attributes:
**Present in this format:**
```
Based on [brief reasoning from product context], I suggest this Tone of Voice:
Tone Attributes:
1. [Attribute 1]: [Brief explanation why]
2. [Attribute 2]: [Brief explanation why]
3. [Attribute 3]: [Brief explanation why]
4. [Attribute 4]: [Brief explanation why]
Does this feel aligned with your brand vision?
```
**Example attributes:**
- Friendly & approachable (for consumer products)
- Professional & authoritative (for B2B/enterprise)
- Empathetic & supportive (for healthcare, education)
- Playful & quirky (for creative/youth products)
- Technical & precise (for developer tools)
- Casual & conversational (for social apps)
- Warm & personal (for services)
### 3. Provide Examples
Show the tone in action with side-by-side comparisons:
**Format:**
```
Example UI Microcopy:
Error Message:
❌ Generic: "Error: Invalid input"
✅ Our Tone: [Rewritten in proposed tone]
Button Text:
❌ Generic: "Submit"
✅ Our Tone: [Rewritten in proposed tone]
Empty State:
❌ Generic: "No results found"
✅ Our Tone: [Rewritten in proposed tone]
Form Label:
❌ Generic: "Email address"
✅ Our Tone: [Rewritten in proposed tone]
Success Message:
❌ Generic: "Operation successful"
✅ Our Tone: [Rewritten in proposed tone]
```
### 4. Refine Based on Feedback
**Ask:**
- "Does this tone feel right for your brand?"
- "Should we adjust any attributes? (more/less formal, friendly, technical, etc.)"
- "Are the examples aligned with how you want to communicate?"
**Iterate until confirmed.**
### 5. Document Final Tone of Voice
Once confirmed, document:
- Tone attributes (3-5 clear characteristics)
- Example microcopy showing tone in action
- Do's and Don'ts (brief guidelines)
## Questions to Ask
### If User Needs Guidance:
**"Let me ask a few questions to help define the tone:"**
1. **Relationship:** "How do you want users to feel about your brand? Like a trusted advisor? A helpful friend? An expert authority? A fun companion?"
2. **Formality:** "Should communication be more formal and professional, or casual and conversational?"
3. **Personality:** "If your product were a person, how would they speak? (serious, playful, quirky, straightforward, warm, technical)"
4. **User Context:** "Are users typically stressed/frustrated when using your product, or excited/curious? How should tone respond to their state?"
5. **Differentiation:** "How do competitors communicate? Should you match industry standards or stand out with a different voice?"
## Validation
Before proceeding:
- [ ] Tone attributes are clearly defined (3-5 specific characteristics)
- [ ] Attributes align with target users and positioning
- [ ] Examples demonstrate the tone clearly
- [ ] User confirms this feels right for their brand
- [ ] Tone is documented for reference
## Output Format
Document in Product Brief:
```markdown
## Tone of Voice
**For UI Microcopy & System Messages**
### Tone Attributes
1. **[Attribute 1]**: [Brief description]
2. **[Attribute 2]**: [Brief description]
3. **[Attribute 3]**: [Brief description]
### Examples
**Error Messages:**
- ✅ "Hmm, that doesn't look like an email. Check for typos?"
- ❌ "Error: Invalid email format"
**Button Text:**
- ✅ "Let's get started"
- ❌ "Submit"
**Empty States:**
- ✅ "Nothing here yet. Ready to add your first item?"
- ❌ "No results found"
**Success Messages:**
- ✅ "You're all set! We've sent a confirmation to your email."
- ❌ "Operation completed successfully"
### Guidelines
**Do:**
- [Tone-appropriate practice 1]
- [Tone-appropriate practice 2]
- [Tone-appropriate practice 3]
**Don't:**
- [Tone-inappropriate practice 1]
- [Tone-inappropriate practice 2]
---
*Note: Tone of Voice applies to UI microcopy. Strategic content (headlines, feature descriptions, value propositions) uses the Content Creation Workshop based on page-specific purpose and context.*
```
## Next Step
**→ Proceed to [Step 12: Synthesize and Create Brief](step-12-synthesize.md)**
## State Update
Update frontmatter of output file:
```yaml
stepsCompleted:
[
'step-01-init.md',
'step-02-vision.md',
'step-03-positioning.md',
'step-04-create-vtc.md',
'step-05-business-model.md',
'step-06-business-customers.md',
'step-07-target-users.md',
'step-08-success-criteria.md',
'step-09-competitive-landscape.md',
'step-10-constraints.md',
'step-11-tone-of-voice.md',
]
```
---
## Example: SaaS Onboarding Tool
**Context:** B2B SaaS for employee onboarding, target users are HR managers (stressed, overwhelmed, want to feel capable)
**Suggested Tone of Voice:**
### Tone Attributes
1. **Supportive & Reassuring**: HR managers are stressed about onboarding. Our tone should reduce anxiety, not add to it.
2. **Professional but Warm**: B2B context requires professionalism, but warmth builds trust.
3. **Clear & Concise**: Busy users need straightforward communication, no fluff.
4. **Empowering**: Frame actions around user capability, not system features.
### Examples
**Error Message:**
- ✅ "We couldn't find that email. Double-check for typos?"
- ❌ "Error 404: User not found"
**Button Text:**
- ✅ "Add your first employee"
- ❌ "Create new record"
**Empty State:**
- ✅ "Your onboarding dashboard is ready. Let's add your first employee to get started."
- ❌ "No employees added yet"
**Success Message:**
- ✅ "Perfect! Sarah's onboarding is set up. We'll send her the welcome email tomorrow at 9 AM."
- ❌ "Employee record created successfully"
---
**⚠️ ALPHA:** This is a new addition to the Product Brief workflow. Feedback welcome on placement, questions, and output format.

20
src/modules/wds/workflows/1-project-brief/project-brief/complete/steps/step-10-synthesize.md → src/modules/wds/workflows/1-project-brief/project-brief/complete/steps/step-12-synthesize.md
View File

@ -1,4 +1,4 @@
# Step 10: Synthesize and Create Brief
# Step 12: Synthesize and Create Brief
## Purpose
@ -14,7 +14,7 @@ This step compiles all strategic foundation elements into a cohesive document.
## Instructions
Present all captured information (vision, positioning, business model, business customers, target users, success criteria, competitive landscape, unfair advantage, constraints, and additional context). Ask for confirmation and make any requested adjustments. Generate final document using the template.
Present all captured information (vision, positioning, business model, business customers, target users, success criteria, competitive landscape, unfair advantage, constraints, tone of voice, and additional context). Ask for confirmation and make any requested adjustments. Generate final document using the template.
## Next Step
@ -30,13 +30,15 @@ stepsCompleted:
'step-01-init.md',
'step-02-vision.md',
'step-03-positioning.md',
'step-04-business-model.md',
'step-05-business-customers.md',
'step-06-target-users.md',
'step-07-success-criteria.md',
'step-08-competitive-landscape.md',
'step-09-constraints.md',
'step-10-synthesize.md',
'step-04-create-vtc.md',
'step-05-business-model.md',
'step-06-business-customers.md',
'step-07-target-users.md',
'step-08-success-criteria.md',
'step-09-competitive-landscape.md',
'step-10-constraints.md',
'step-11-tone-of-voice.md',
'step-12-synthesize.md',
]
status: 'complete'
```

2
src/modules/wds/workflows/2-trigger-mapping/REVIEW-FINDINGS.md
View File

@ -114,7 +114,7 @@
- Handover calls document generation internally
- Adds cross-references
- Performs quality check
- Creates handover package for Freyja
- Creates handover package for Freya
- Provides activation instructions
**Benefit:** Clean phase transition with proper context for next agent

2
src/modules/wds/workflows/2-trigger-mapping/handover/steps/step-04-create-handover-package.md
View File

@ -4,7 +4,7 @@
## Your Task
Create summary package for the UX Designer (Freyja).
Create summary package for the UX Designer (Freya).
---

4
src/modules/wds/workflows/2-trigger-mapping/handover/steps/step-05-provide-activation.md
View File

@ -4,7 +4,7 @@
## Your Task
Provide activation instructions for the UX Designer (Freyja) to begin UX Design.
Provide activation instructions for the UX Designer (Freya) to begin UX Design.
---
@ -12,7 +12,7 @@ Provide activation instructions for the UX Designer (Freyja) to begin UX Design.
<output>**Ready to Start UX Design!** 🎨
**To activate the UX Designer (Freyja):**
**To activate the UX Designer (Freya):**
**In a NEW conversation** (recommended for fresh context), load the UX agent with:

22
src/modules/wds/workflows/3-prd-platform/instructions.md
View File

@ -1,6 +1,6 @@
# Phase 3: PRD Platform (Technical Foundation)
**Agent:** Freyja the PM
**Agent:** Freya the PM
**Output Folder:** `C-Requirements/` (or user's configured prefix)
---
@ -47,7 +47,7 @@ Before starting, ensure you have:
### Step 1: Welcome and Context Review
**Freyja's Role:**
**Freya's Role:**
Greet the user and explain this phase:
@ -67,7 +67,7 @@ Review available context:
**Goal:** Define the technology stack and infrastructure through systematic discussion.
**Freyja's Approach:**
**Freya's Approach:**
"Let's establish your technical foundation. I'll walk through each major area, and we'll document your decisions, business rules, and constraints as we go."
@ -199,7 +199,7 @@ Ask systematically:
**Goal:** Systematically identify all external dependencies through intelligent, context-aware discussion.
**Freyja's Approach:**
**Freya's Approach:**
"Let me review your Product Brief to understand which integrations you'll likely need, then we'll go through each relevant category systematically."
@ -497,7 +497,7 @@ For each feature identified in Step 4:
**Goal:** Systematically define security, authentication, and compliance through detailed discussion.
**Freyja's Approach:**
**Freya's Approach:**
"Security is critical. Let's go through each security area methodically and document all business rules and requirements."
@ -627,7 +627,7 @@ Ask systematically about all regulatory requirements:
**Goal:** Define comprehensive API contracts through systematic category-by-category discussion.
**Freyja explains:**
**Freya explains:**
"We're taking an API-first approach. By defining clear service contracts now, we enable backend development to proceed in parallel with UX design. These APIs will serve as the foundation for all future UI work."
@ -719,7 +719,7 @@ For each:
**Goal:** Document database schemas and performance benchmarks.
**Freyja's Approach:**
**Freya's Approach:**
"Let's formalize the data model and set clear performance expectations."
@ -802,7 +802,7 @@ For each major platform area (auth, integrations, security, etc.):
**Goal:** Recommend platform infrastructure work for BMM to organize into epics and stories, prioritized by Feature Impact Analysis.
**Freyja explains:**
**Freya explains:**
"Based on all the technical requirements we've documented AND the Feature Impact Analysis from Phase 2, let me suggest how this platform work could be organized for development. We'll prioritize platform work that enables your highest-impact features first."
@ -923,7 +923,7 @@ Create a table:
**Goal:** Create the master PRD that references all Phase 3 work.
**Freyja explains:**
**Freya explains:**
"The PRD is your single source of truth. It starts here with technical foundation and will grow during Phase 4 as functional requirements are added from UX design."
@ -1039,7 +1039,7 @@ _Coming from Phase 4_
### Step 12: Summary and Completeness Check
**Freyja congratulates the user:**
**Freya congratulates the user:**
"Excellent work! We've systematically documented your technical foundation. Let me summarize what we've created:"
@ -1119,7 +1119,7 @@ _Coming from Phase 4_
## Tips for Great Sessions
### For Freyja the PM:
### For Freya the PM:
**Validate Early, Often:**

2
src/modules/wds/workflows/3-prd-platform/workflow.yaml
View File

@ -5,7 +5,7 @@ web_bundle: true
---
# WDS Phase 3: PRD Platform (Technical Foundation)
name: "Phase 3: PRD Platform (Technical Foundation)"
agent: "Freyja the PM"
agent: "Freya the PM"
version: "1.0.0"
paths:

2
src/modules/wds/workflows/4-ux-design/README.md
View File

@ -1,6 +1,6 @@
# Phase 4: UX Design Workflow
**Freyja's domain - From sketch to specification**
**Freya's domain - From sketch to specification**
---

20
src/modules/wds/workflows/4-ux-design/SKETCH-FIRST-IMPLEMENTATION-PLAN.md
View File

@ -1,7 +1,7 @@
# Sketch-First Workflow - Implementation Plan
**Feature**: Intelligent sketch-driven project initialization
**Agents**: Mimer (Detection), Freyja (UX), Saga (Brief), Cascade (Trigger Map)
**Agents**: Mimer (Detection), Freya (UX), Saga (Brief), Cascade (Trigger Map)
**When**: User uploads sketch(es) to repository
**Purpose**: Enable designers to start with sketches, build foundation retroactively
**Vision**: From "15 wireframes in a folder" → "Complete WDS project with specs & prototypes"
@ -72,9 +72,9 @@ Mimer: "👋 Hey! I noticed some changes:
```
User: [uploads landing-page.jpg]
Mimer: "I see a sketch! Activating Freyja..."
Mimer: "I see a sketch! Activating Freya..."
Freyja: "Hi! Let me analyze this sketch...
Freya: "Hi! Let me analyze this sketch...
🔍 Analysis:
- Landing page concept
@ -88,7 +88,7 @@ Freyja: "Hi! Let me analyze this sketch...
User: "A"
Freyja: "Perfect! Since this is a new project, let's
Freya: "Perfect! Since this is a new project, let's
build the foundation first.
I'll hand you to Saga for Product Brief,
@ -99,7 +99,7 @@ Freyja: "Perfect! Since this is a new project, let's
→ Product Brief workflow
→ Trigger Mapping workflow (if needed)
→ Return to Freyja for page specification
→ Return to Freya for page specification
```
**Human confirms:**
@ -160,7 +160,7 @@ Mimer: "Perfect! Here's the plan:
→ Establish navigation flow
**Phase 3: Specification** (iterative)
→ Freyja analyzes each sketch
→ Freya analyzes each sketch
→ You review and refine
**Phase 4: Prototypes** (automatic)
@ -198,7 +198,7 @@ User: "Begin"
```
User: [uploads landing-page-v2.jpg]
Freyja: "I see we already have specs for Landing Page.
Freya: "I see we already have specs for Landing Page.
Let me compare this to version 1...
🔍 **Changes detected:**
@ -215,7 +215,7 @@ Freyja: "I see we already have specs for Landing Page.
User: "A"
Freyja: "Great! I'll update:
Freya: "Great! I'll update:
1. Add search bar specs to Header
2. Complete Feature Card 3
3. Generate Footer specifications
@ -482,7 +482,7 @@ Agent: "I processed 5 sketches automatically:
### **Now (Week 1-2)**
1. Passive sketch detection (Mimer)
2. Single sketch analysis workflow (Freyja)
2. Single sketch analysis workflow (Freya)
3. Page init lightweight (navigation setup)
4. Basic change detection
@ -585,7 +585,7 @@ sketch_workflow:
---
**Created**: December 28, 2025
**Feature Owner**: Freyja (UX), Mimer (Detection)
**Feature Owner**: Freya (UX), Mimer (Detection)
**Status**: Planning Complete → Ready for Implementation
**Next Step**: Create v1.0 workflows (manual trigger, human-in-loop)

2
src/modules/wds/workflows/4-ux-design/handover/instructions.md
View File

@ -1,6 +1,6 @@
# Handover: UX Design → Design Delivery (Incremental)
<critical>You are Freyja the Designer preparing an incremental design delivery</critical>
<critical>You are Freya the Designer preparing an incremental design delivery</critical>
<handover>

2
src/modules/wds/workflows/4-ux-design/handover/steps/step-01-analyze-scenarios.md
View File

@ -1,6 +1,6 @@
# Step 1: Analyze Scenarios for Technical Needs
<critical>You are Freyja - extracting platform requirements from designs</critical>
<critical>You are Freya - extracting platform requirements from designs</critical>
## Your Task

2
src/modules/wds/workflows/4-ux-design/handover/steps/step-01-identify-delivery-scope.md
View File

@ -1,6 +1,6 @@
# Step 1: Identify Delivery Scope
<critical>You are Freyja - defining what's ready for implementation</critical>
<critical>You are Freya - defining what's ready for implementation</critical>
## Your Task

2
src/modules/wds/workflows/4-ux-design/handover/steps/step-02-create-summary.md
View File

@ -1,6 +1,6 @@
# Step 2: Create Handover Summary
<critical>You are Freyja - preparing handover package for Idunn</critical>
<critical>You are Freya - preparing handover package for Idunn</critical>
## Your Task

2
src/modules/wds/workflows/4-ux-design/handover/steps/step-02-extract-technical-needs.md
View File

@ -1,6 +1,6 @@
# Step 2: Extract Technical Needs
<critical>You are Freyja - identifying what development needs for this delivery</critical>
<critical>You are Freya - identifying what development needs for this delivery</critical>
## Your Task

2
src/modules/wds/workflows/4-ux-design/handover/steps/step-03-create-delivery-package.md
View File

@ -1,6 +1,6 @@
# Step 3: Create Design Delivery Package
<critical>You are Freyja - packaging design for development</critical>
<critical>You are Freya - packaging design for development</critical>
## Your Task

2
src/modules/wds/workflows/4-ux-design/handover/steps/step-03-provide-activation.md
View File

@ -1,6 +1,6 @@
# Step 3: Provide Next Phase Activation
<critical>You are Freyja - guiding to Phase 3</critical>
<critical>You are Freya - guiding to Phase 3</critical>
## Your Task

2
src/modules/wds/workflows/4-ux-design/handover/steps/step-04-log-delivery.md
View File

@ -1,6 +1,6 @@
# Step 4: Log Design Delivery
<critical>You are Freyja - tracking design deliveries</critical>
<critical>You are Freya - tracking design deliveries</critical>
## Your Task

2
src/modules/wds/workflows/4-ux-design/handover/steps/step-05-provide-activation.md
View File

@ -1,6 +1,6 @@
# Step 5: Provide Development Activation
<critical>You are Freyja - guiding to implementation</critical>
<critical>You are Freya - guiding to implementation</critical>
## Your Task

2
src/modules/wds/workflows/4-ux-design/page-specification-quality/README.md
View File

@ -50,7 +50,7 @@ Each step focuses on one structural element to ensure nothing is missed.
## Quick Start
### For Freyja (AI Agent)
### For Freya (AI Agent)
<action>Load and execute: instructions.md</action>

10
src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/00-SCENARIO-INIT-GUIDE.md
View File

@ -17,7 +17,7 @@ This process helps you identify:
---
## The 5 Questions
## The 6 Steps
### [1. What Feature Delivers Value?](01-feature-selection.md)
@ -39,6 +39,10 @@ What does winning look like for both business and user?
Minimum steps from starting point to mutual success
### [6. Create Value Trigger Chain](06-create-vtc.md)
Crystallize scenario strategy before sketching
---
## Examples
@ -59,9 +63,9 @@ Appointment-driven trust-building flow
## Next Step
Once you have clarity on all 5 questions, **start sketching the journey.**
Once you have clarity on all 6 steps (including VTC), **start sketching the journey.**
Each sketch serves the path from trigger to mutual success.
Each sketch serves the path from trigger to mutual success, guided by the VTC.
---

6
src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/05-shortest-path.md
View File

@ -73,7 +73,7 @@ Each step serves the journey. Nothing extra.
---
## Now You Can Sketch
## Next Step
With all 5 questions answered, you have:
@ -83,7 +83,9 @@ With all 5 questions answered, you have:
- ✅ Mutual success (where to end)
- ✅ Shortest path (how to get there)
**Start sketching each step of the journey.**
**→ Proceed to [Step 6: Create VTC](06-create-vtc.md)**
Before sketching, crystallize this scenario's strategy into a Value Trigger Chain.
---

132
src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/06-create-vtc.md Normal file
View File

@ -0,0 +1,132 @@
# 6. Create Value Trigger Chain for Scenario
**Purpose:** Crystallize scenario strategy before sketching
---
## Why Now?
You've defined:
- ✅ Feature that delivers value
- ✅ Entry point
- ✅ Mental state
- ✅ Mutual success
- ✅ Shortest path
**Perfect time to create a VTC** - you have everything needed.
This VTC will guide every page, every interaction, every word in this scenario.
---
## Agent Instructions
> "Before we start sketching, let's create a Value Trigger Chain for this scenario.
>
> This captures the strategic essence:
> - Business Goal (from mutual success - business side)
> - Solution (this scenario/feature)
> - User (primary target group)
> - Driving Forces (from mental state and Trigger Map)
> - Customer Awareness (where they start → where they end up)
>
> This takes 10-15 minutes since we have the Trigger Map. It'll guide every design decision.
>
> Shall we create the scenario VTC?"
---
## Route to VTC Workshop
**If user agrees:**
Load and execute the VTC Workshop Router:
`../../shared/vtc-workshop/vtc-workshop-router.md`
**Since Trigger Map exists:** Router will likely send you to **Selection Workshop** (10-15 mins).
---
## Leverage Context
**Important:** You have rich context from scenario init! Use it:
- **Business Goal:** From mutual success (business side)
- **Solution:** The feature/scenario just defined
- **User:** Primary target group from Trigger Map
- **Entry Point/Mental State:** For Customer Awareness starting point
- **Mutual Success:** For Customer Awareness ending point
- **Driving Forces:** From Trigger Map for this user
**Scenario init IS strategic discovery** - use it!
---
## Save VTC
VTC should be saved to:
`{output_folder}/D-UX-Design/[scenario-name]/vtc.yaml`
Example: `docs/D-UX-Design/1.1-parent-onboarding/vtc.yaml`
---
## Confirm and Set Expectation
> "Excellent! This scenario now has its own VTC.
>
> As we sketch each page, we'll use this VTC to ensure:
> - Every interaction addresses these driving forces
> - Every message moves them through awareness
> - Every design choice serves mutual success
>
> The VTC is your strategic compass. When in doubt, check the VTC.
>
> Ready to start sketching?"
---
## If User Declines VTC
**If user says:** "Let's skip the VTC and sketch"
**Response:**
> "I strongly recommend creating the VTC first. Here's why:
>
> Without it, design becomes opinion-based:
> - 'I like this button here'
> - 'This color feels right'
> - 'Users probably want this'
>
> With VTC, design becomes strategic:
> - 'This button triggers their wish to [driving force]'
> - 'This message addresses their fear of [driving force]'
> - 'This moves them from [awareness start] to [awareness end]'
>
> It takes 15 minutes and saves hours of redesign.
>
> Still want to skip?"
**If still declines:**
> "Okay, but I recommend creating VTC before presenting to stakeholders. You can add it anytime using:
> `../../shared/vtc-workshop/vtc-workshop-router.md`"
Then proceed to sketching without VTC (not ideal).
---
## Next Step
After VTC is created:
**Start sketching the scenario journey!**
Each sketch should:
- Serve the VTC driving forces
- Move user through awareness progression
- Support shortest path to mutual success
---
*Strategic clarity achieved - now sketch with purpose!*

Some files were not shown because too many files have changed in this diff Show More