whiteport-design-studio 0.1.0

package/docs/method/content-purpose-guide.md

@@ -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](../src/workflows/shared/content-creation-workshop/content-creation-workshop-guide.md) - Using purpose in content generation
+
+---
+
+**Make every word earn its place. Define its job.** 🎯
+

package/docs/method/phase-1-product-exploration-guide.md

@@ -0,0 +1,178 @@
+# Phase 1: Product Exploration
+
+**Agent:** Saga the Analyst  
+**Output:** `A-Product-Brief/` (or your configured prefix)
+
+---
+
+## What This Phase Does
+
+Product Exploration establishes your strategic foundation through conversational discovery. Instead of filling out questionnaires, you have a conversation that builds understanding organically.
+
+By the end, you'll have a Product Brief that captures your vision and serves as the north star for your entire project.
+
+---
+
+## What You'll Create
+
+Your Product Brief includes:
+
+- **Executive Summary** - The vision that inspires teams
+- **Problem Statement** - The "why" that drives decisions
+- **User Types** - The "who" that guides design (initial identification)
+- **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.
+
+---
+
+## How It Works
+
+### The Conversational Approach
+
+Traditional requirements gathering treats people like databases - extracting answers through rigid questionnaires. WDS does it differently.
+
+**Instead of:** "Please complete this 47-question requirements document"
+
+**WDS says:** "Tell me about your project in your own words"
+
+People light up when asked to share their vision. They become collaborators, not interrogation subjects.
+
+### The Session Flow
+
+**Opening (5-10 minutes)**
+
+Saga asks about your project in your own words. She listens for:
+
+- What you emphasize naturally
+- Where your energy goes
+- What excites vs. what stresses you
+- Your exact language and terminology
+
+**Exploration (15-30 minutes)**
+
+The conversation adapts to what you reveal:
+
+- If you mention users → deeper into user insights
+- If you mention problems → explore the cost of not solving
+- If you mention competition → discover differentiation
+- If you mention timeline → understand urgency drivers
+
+Each answer reveals the next question. It's jazz, not classical music.
+
+**Synthesis (10-15 minutes)**
+
+Saga reflects back your vision in organized form:
+
+- Connecting dots you shared across topics
+- Highlighting insights you might not have seen
+- Building the foundation for next phases
+
+### Living Document
+
+As you talk, the Product Brief grows in real-time:
+
+- Immediate validation and refinement
+- Real-time course correction
+- You own the content because you helped create it
+- "Yes, exactly!" moments that build trust
+
+---
+
+## When to Use This Phase
+
+**Always start here if:**
+
+- Building something new
+- Starting a new project
+- Need strategic clarity before diving into design
+
+**Skip if:**
+
+- You already have a clear, documented product brief
+- Just enhancing an existing feature
+- Working on a design system without new product context
+
+---
+
+## What to Prepare
+
+Come ready to share:
+
+- Your project idea (even if rough)
+- The problem you're solving
+- Who might use it
+- Why it matters to you
+
+You don't need polished answers. The conversation will help clarify everything.
+
+---
+
+## What Comes Next
+
+Your Product Brief enables:
+
+- **Phase 2: User Research** - Deeper into user psychology with your strategic context
+- **Phase 3: Requirements** - Technical decisions aligned with your vision
+- **Phase 4: UX Design** - Design work grounded in strategic purpose
+
+The brief becomes the reference point everyone shares.
+
+---
+
+## Tips for Great Sessions
+
+**Let the conversation flow**
+
+- Share what feels important, even if it seems tangential
+- Follow your energy - where you're excited matters
+
+**Think out loud**
+
+- Half-formed thoughts are welcome
+- will help you refine them
+
+**Be honest about uncertainty**
+
+- "I'm not sure about X" is useful information
+- Better to surface doubts now than later
+
+**Review as you go**
+
+- Check that what's captured matches your thinking
+- Correct misunderstandings immediately
+
+---
+
+## Example Output
+
+See: `examples/dog-week-patterns/A-Product-Brief/` for a complete Product Brief example from a real project.
+
+---
+
+## 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_