whiteport-design-studio 0.1.0 → 0.2.0

package/src/data/agent-guides/saga/strategic-documentation.md

@@ -1,456 +1,456 @@
-# Saga's Strategic Documentation Guide
-
-**When to load:** When creating Product Brief, Project Outline, or any strategic documentation
-
----
-
-## Core Principle
-
-**Create documentation that coordinates teams and persists context.**
-
-Every project needs a North Star - clear, accessible, living documentation that guides all work.
-
----
-
-## The Project Outline
-
-**Created during Product Brief (Step 1), updated throughout project**
-
-### Purpose
-- **Single source of truth** for project status
-- **Coordination point** for all team members
-- **Context preservation** across sessions
-- **Onboarding tool** for new collaborators
-
----
-
-### What Goes In Project Outline
-
-```yaml
-project:
-  name: [Project Name]
-  type: [digital_product|landing_page|website|other]
-  status: [planning|in_progress|complete]
-
-methodology:
-  type: [wds-v6|wps2c-v4|custom]
-  instructions_file: [if custom]
-
-phases:
-  phase_1_product_brief:
-    folder: "docs/A-Product-Brief/"
-    name: "Product Exploration"
-    status: [not_started|in_progress|complete]
-    artifacts:
-      - product-brief.md
-      - pitch-deck.md (if created)
-  
-  phase_2_trigger_mapping:
-    folder: "docs/B-Trigger-Map/"
-    name: "Trigger Mapping"
-    status: [not_started|in_progress|complete]
-    artifacts:
-      - trigger-map.md
-      - trigger-map-diagram.mermaid
-  
-  # ... other phases
-
-languages:
-  specification_language: "en"
-  product_languages: ["en", "se"]
-
-design_system:
-  enabled: true
-  mode: [none|figma|component_library]
-  library: [if mode=component_library]
-```
-
----
-
-### When to Update Project Outline
-
-**Always update when:**
-- ✅ Completing a phase
-- ✅ Creating new artifacts
-- ✅ Changing project scope
-- ✅ Adding new workflows
-
-**Project outline is living documentation** - keep it current!
-
----
-
-## The Product Brief
-
-**10-step conversational workshop creates:**
-
-### 1. Vision & Problem Statement
-**What are we building and why?**
-
-- Product vision (aspirational)
-- Problem statement (what pain exists)
-- Solution approach (high-level)
-
----
-
-### 2. Positioning
-**How are we different?**
-
-- Target customer
-- Need/opportunity
-- Product category
-- Key benefits
-- Differentiation vs competition
-
-**Format:** "For [target] who [need], our [product] is [category] that [benefits]. Unlike [competition], we [differentiators]."
-
----
-
-### 3. Value Trigger Chain (VTC)
-**Strategic benchmark for early decisions**
-
-Created in Step 4 (early in the brief) to provide strategic grounding:
-- Business goal
-- Solution context
-- User
-- Driving forces (positive + negative)
-- Customer awareness progression
-
-**See:** VTC micro-guide for Freya (also relevant for Saga)
-
----
-
-### 4. Business Model
-**How do we make money?**
-
-- Revenue model (subscription, transaction, license, etc.)
-- Pricing approach
-- Unit economics
-- Key assumptions
-
----
-
-### 5. Business Customers
-**Who pays? (B2B/Enterprise)**
-
-- Decision makers
-- Budget owners
-- Procurement process
-- Deal cycle
-
-**Skip if B2C.**
-
----
-
-### 6. Target Users
-**Who actually uses it?**
-
-- User segments
-- Demographics
-- Psychographics
-- Current behavior patterns
-
-**Note:** Detailed in Trigger Map later, this is overview.
-
----
-
-### 7. Success Criteria
-**How do we measure success?**
-
-- Business metrics (revenue, users, retention)
-- User metrics (engagement, satisfaction, NPS)
-- Technical metrics (performance, uptime)
-- Timeline milestones
-
----
-
-### 8. Competitive Landscape
-**Who else solves this?**
-
-- Direct competitors
-- Indirect competitors
-- Substitutes
-- Our advantages/disadvantages
-
----
-
-### 9. Unfair Advantage
-**What do we have that others can't easily copy?**
-
-- Network effects
-- Proprietary data
-- Domain expertise
-- Strategic partnerships
-- Technology
-- Brand/reputation
-
----
-
-### 10. Constraints
-**What are our limits?**
-
-- Budget constraints
-- Timeline constraints
-- Technical constraints
-- Resource constraints
-- Regulatory constraints
-
----
-
-### 11. Tone of Voice
-**How should UI microcopy sound?**
-
-- Brand personality
-- Writing principles
-- Do's and don'ts
-- Example phrases
-
-**Used for:** Field labels, buttons, error messages, success messages
-
-**NOT for:** Strategic content (that uses Content Creation Workshop)
-
----
-
-### 12. Synthesize
-**Bring it all together**
-
-Generate complete Product Brief document using template.
-
-**See:** `../../workflows/1-project-brief/project-brief/complete/project-brief.template.md`
-
----
-
-## File Naming Conventions
-
-**CRITICAL: Never use generic names**
-
-### ❌ Wrong (Generic)
-- `README.md`
-- `guide.md`
-- `notes.md`
-- `documentation.md`
-
-**Why bad:** Ambiguous, unmaintainable, confusing
-
----
-
-### ✅ Right (Specific)
-- `product-brief.md`
-- `trigger-mapping-guide.md`
-- `platform-requirements.md`
-- `design-system-guide.md`
-
-**Why better:** Clear purpose, searchable, maintainable
-
----
-
-### Pattern: `[TOPIC]-GUIDE.md`
-
-**For methodology documentation:**
-- `phase-1-product-exploration-guide.md`
-- `value-trigger-chain-guide.md`
-- `content-creation-philosophy.md`
-
-**For deliverables:**
-- `product-brief.md`
-- `trigger-map.md`
-- `platform-prd.md`
-
-**For examples:**
-- `wds-examples-guide.md`
-- `wds-v6-conversion-guide.md`
-
----
-
-## Documentation Quality Standards
-
-### Precision
-**Articulate requirements with precision while keeping language accessible**
-
-❌ "Users probably want something to help them..."
-
-✅ "Consultants need proposal templates that reduce formatting time by 80% while maintaining professional appearance"
-
----
-
-### Evidence
-**Ground all findings in verifiable evidence**
-
-❌ "Most consultants struggle with proposals"
-
-✅ "In 15 user interviews, 12 consultants (80%) reported spending 3+ hours per proposal on formatting alone"
-
----
-
-### Accessibility
-**Technical accuracy, but readable by non-experts**
-
-❌ "Implement OAuth 2.0 authorization code flow with PKCE extension for SPA-based authentication"
-
-✅ "Use industry-standard secure login (OAuth 2.0) that protects user data even in browser-based apps"
-
----
-
-### Structure
-**Clear hierarchy, scannable, actionable**
-
-Good structure:
-```markdown
-# Main Topic
-
-## Overview
-[High-level summary]
-
-## Key Concepts
-### Concept 1
-[Explanation]
-
-### Concept 2
-[Explanation]
-
-## How to Use This
-[Actionable steps]
-
-## Related Resources
-[Links to related docs]
-```
-
----
-
-## The Bible: `project-context.md`
-
-**If this file exists, treat it as gospel.**
-
-### What It Contains
-- Project history
-- Key decisions and rationale
-- Technical constraints
-- Business constraints
-- Team context
-- Anything critical to know
-
-### How to Use It
-1. **First action:** Check if exists
-2. **If exists:** Read thoroughly before any work
-3. **If missing:** Offer to create one
-
-**Location:** Usually `docs/project-context.md` or root `project-context.md`
-
----
-
-## Absolute vs Relative Paths
-
-**WDS uses absolute paths for artifacts:**
-
-### ✅ Absolute (Explicit)
-```
-docs/A-Product-Brief/product-brief.md
-docs/B-Trigger-Map/trigger-map.md
-docs/C-Scenarios/landing-page/01-hero-section.md
-```
-
-**Why:** Clear, unambiguous, no confusion about location
-
----
-
-### ❌ Relative (Ambiguous)
-```
-../product-brief.md
-../../trigger-map.md
-```
-
-**Why bad:** Depends on current location, breaks easily
-
----
-
-## Alliterative Persona Names
-
-**Create memorable, fun persona names using alliteration**
-
-### Good Examples
-- Harriet the Hairdresser
-- Marcus Manager
-- Diana Designer
-- Samantha Salesperson
-- Tony Trainer
-- Petra Product Manager
-
-**Why:** Easier to remember, more human, makes documentation engaging
-
----
-
-### Bad Examples
-- John (generic)
-- User 1 (impersonal)
-- Target Group A (clinical)
-
-**Why bad:** Forgettable, boring, doesn't bring persona to life
-
----
-
-## Documentation Maintenance
-
-**Documents are living artifacts:**
-
-### When to Update
-- ✅ New information discovered
-- ✅ Assumptions proven wrong
-- ✅ Priorities shift
-- ✅ Scope changes
-- ✅ Phase completes
-
-### Version Control
-- Use git for all documentation
-- Commit with clear messages
-- Tag major milestones
-- Keep history
-
-### Archive, Don't Delete
-- Old versions have context value
-- Create `archive/` folder if needed
-- Document why something changed
-
----
-
-## Documentation Handoffs
-
-**When handing to development team:**
-
-### Complete Package Includes
-1. **Product Brief** - Strategic foundation
-2. **Trigger Map** - User psychology
-3. **Platform PRD** - Technical requirements
-4. **Page Specifications** - Detailed UX specs
-5. **Design System** (if created) - Component library
-6. **Design Delivery PRD** - Complete handoff package
-
-**See:** Phase 6 (Design Deliveries) for handoff process
-
----
-
-## Quality Checklist
-
-Before marking documentation "complete":
-
-- [ ] **Clear purpose** - Why does this document exist?
-- [ ] **Specific names** - No README.md or generic.md?
-- [ ] **Absolute paths** - All file references explicit?
-- [ ] **Evidence-based** - Claims backed by research/data?
-- [ ] **Accessible language** - Readable by all stakeholders?
-- [ ] **Structured well** - Scannable, logical hierarchy?
-- [ ] **Up to date** - Reflects current reality?
-- [ ] **Actionable** - Others can use this to make decisions?
-
----
-
-## Related Resources
-
-- **Product Brief Workflow:** `../../workflows/1-project-brief/project-brief/`
-- **File Naming Conventions:** `../../workflows/00-system/FILE-NAMING-CONVENTIONS.md`
-- **Project Outline Template:** Created during Phase 1 Step 1
-- **Documentation Standards:** `../../../bmm/data/documentation-standards.md`
-
----
-
-*Good documentation is the foundation of coordinated, confident execution. It's not overhead - it's leverage.*
-
-
+# Saga's Strategic Documentation Guide
+
+**When to load:** When creating Product Brief, Project Outline, or any strategic documentation
+
+---
+
+## Core Principle
+
+**Create documentation that coordinates teams and persists context.**
+
+Every project needs a North Star - clear, accessible, living documentation that guides all work.
+
+---
+
+## The Project Outline
+
+**Created during Product Brief (Step 1), updated throughout project**
+
+### Purpose
+- **Single source of truth** for project status
+- **Coordination point** for all team members
+- **Context preservation** across sessions
+- **Onboarding tool** for new collaborators
+
+---
+
+### What Goes In Project Outline
+
+```yaml
+project:
+  name: [Project Name]
+  type: [digital_product|landing_page|website|other]
+  status: [planning|in_progress|complete]
+
+methodology:
+  type: [wds-v6|wps2c-v4|custom]
+  instructions_file: [if custom]
+
+phases:
+  phase_1_product_brief:
+    folder: "docs/A-Product-Brief/"
+    name: "Product Exploration"
+    status: [not_started|in_progress|complete]
+    artifacts:
+      - product-brief.md
+      - pitch-deck.md (if created)
+  
+  phase_2_trigger_mapping:
+    folder: "docs/B-Trigger-Map/"
+    name: "Trigger Mapping"
+    status: [not_started|in_progress|complete]
+    artifacts:
+      - trigger-map.md
+      - trigger-map-diagram.mermaid
+  
+  # ... other phases
+
+languages:
+  specification_language: "en"
+  product_languages: ["en", "se"]
+
+design_system:
+  enabled: true
+  mode: [none|figma|component_library]
+  library: [if mode=component_library]
+```
+
+---
+
+### When to Update Project Outline
+
+**Always update when:**
+- ✅ Completing a phase
+- ✅ Creating new artifacts
+- ✅ Changing project scope
+- ✅ Adding new workflows
+
+**Project outline is living documentation** - keep it current!
+
+---
+
+## The Product Brief
+
+**10-step conversational workshop creates:**
+
+### 1. Vision & Problem Statement
+**What are we building and why?**
+
+- Product vision (aspirational)
+- Problem statement (what pain exists)
+- Solution approach (high-level)
+
+---
+
+### 2. Positioning
+**How are we different?**
+
+- Target customer
+- Need/opportunity
+- Product category
+- Key benefits
+- Differentiation vs competition
+
+**Format:** "For [target] who [need], our [product] is [category] that [benefits]. Unlike [competition], we [differentiators]."
+
+---
+
+### 3. Value Trigger Chain (VTC)
+**Strategic benchmark for early decisions**
+
+Created in Step 4 (early in the brief) to provide strategic grounding:
+- Business goal
+- Solution context
+- User
+- Driving forces (positive + negative)
+- Customer awareness progression
+
+**See:** VTC micro-guide for Freya (also relevant for Saga)
+
+---
+
+### 4. Business Model
+**How do we make money?**
+
+- Revenue model (subscription, transaction, license, etc.)
+- Pricing approach
+- Unit economics
+- Key assumptions
+
+---
+
+### 5. Business Customers
+**Who pays? (B2B/Enterprise)**
+
+- Decision makers
+- Budget owners
+- Procurement process
+- Deal cycle
+
+**Skip if B2C.**
+
+---
+
+### 6. Target Users
+**Who actually uses it?**
+
+- User segments
+- Demographics
+- Psychographics
+- Current behavior patterns
+
+**Note:** Detailed in Trigger Map later, this is overview.
+
+---
+
+### 7. Success Criteria
+**How do we measure success?**
+
+- Business metrics (revenue, users, retention)
+- User metrics (engagement, satisfaction, NPS)
+- Technical metrics (performance, uptime)
+- Timeline milestones
+
+---
+
+### 8. Competitive Landscape
+**Who else solves this?**
+
+- Direct competitors
+- Indirect competitors
+- Substitutes
+- Our advantages/disadvantages
+
+---
+
+### 9. Unfair Advantage
+**What do we have that others can't easily copy?**
+
+- Network effects
+- Proprietary data
+- Domain expertise
+- Strategic partnerships
+- Technology
+- Brand/reputation
+
+---
+
+### 10. Constraints
+**What are our limits?**
+
+- Budget constraints
+- Timeline constraints
+- Technical constraints
+- Resource constraints
+- Regulatory constraints
+
+---
+
+### 11. Tone of Voice
+**How should UI microcopy sound?**
+
+- Brand personality
+- Writing principles
+- Do's and don'ts
+- Example phrases
+
+**Used for:** Field labels, buttons, error messages, success messages
+
+**NOT for:** Strategic content (that uses Content Creation Workshop)
+
+---
+
+### 12. Synthesize
+**Bring it all together**
+
+Generate complete Product Brief document using template.
+
+**See:** `{project-root}/_bmad/wds/templates/1-project-brief/project-brief.template.md`
+
+---
+
+## File Naming Conventions
+
+**CRITICAL: Never use generic names**
+
+### ❌ Wrong (Generic)
+- `README.md`
+- `guide.md`
+- `notes.md`
+- `documentation.md`
+
+**Why bad:** Ambiguous, unmaintainable, confusing
+
+---
+
+### ✅ Right (Specific)
+- `product-brief.md`
+- `trigger-mapping-guide.md`
+- `platform-requirements.md`
+- `design-system-guide.md`
+
+**Why better:** Clear purpose, searchable, maintainable
+
+---
+
+### Pattern: `[TOPIC]-GUIDE.md`
+
+**For methodology documentation:**
+- `phase-1-product-exploration-guide.md`
+- `value-trigger-chain-guide.md`
+- `content-creation-philosophy.md`
+
+**For deliverables:**
+- `product-brief.md`
+- `trigger-map.md`
+- `platform-prd.md`
+
+**For examples:**
+- `wds-examples-guide.md`
+- `wds-v6-conversion-guide.md`
+
+---
+
+## Documentation Quality Standards
+
+### Precision
+**Articulate requirements with precision while keeping language accessible**
+
+❌ "Users probably want something to help them..."
+
+✅ "Consultants need proposal templates that reduce formatting time by 80% while maintaining professional appearance"
+
+---
+
+### Evidence
+**Ground all findings in verifiable evidence**
+
+❌ "Most consultants struggle with proposals"
+
+✅ "In 15 user interviews, 12 consultants (80%) reported spending 3+ hours per proposal on formatting alone"
+
+---
+
+### Accessibility
+**Technical accuracy, but readable by non-experts**
+
+❌ "Implement OAuth 2.0 authorization code flow with PKCE extension for SPA-based authentication"
+
+✅ "Use industry-standard secure login (OAuth 2.0) that protects user data even in browser-based apps"
+
+---
+
+### Structure
+**Clear hierarchy, scannable, actionable**
+
+Good structure:
+```markdown
+# Main Topic
+
+## Overview
+[High-level summary]
+
+## Key Concepts
+### Concept 1
+[Explanation]
+
+### Concept 2
+[Explanation]
+
+## How to Use This
+[Actionable steps]
+
+## Related Resources
+[Links to related docs]
+```
+
+---
+
+## The Bible: `project-context.md`
+
+**If this file exists, treat it as gospel.**
+
+### What It Contains
+- Project history
+- Key decisions and rationale
+- Technical constraints
+- Business constraints
+- Team context
+- Anything critical to know
+
+### How to Use It
+1. **First action:** Check if exists
+2. **If exists:** Read thoroughly before any work
+3. **If missing:** Offer to create one
+
+**Location:** Usually `docs/project-context.md` or root `project-context.md`
+
+---
+
+## Absolute vs Relative Paths
+
+**WDS uses absolute paths for artifacts:**
+
+### ✅ Absolute (Explicit)
+```
+docs/A-Product-Brief/product-brief.md
+docs/B-Trigger-Map/trigger-map.md
+docs/C-UX-Scenarios/landing-page/01-hero-section.md
+```
+
+**Why:** Clear, unambiguous, no confusion about location
+
+---
+
+### ❌ Relative (Ambiguous)
+```
+../product-brief.md
+../../trigger-map.md
+```
+
+**Why bad:** Depends on current location, breaks easily
+
+---
+
+## Alliterative Persona Names
+
+**Create memorable, fun persona names using alliteration**
+
+### Good Examples
+- Harriet the Hairdresser
+- Marcus Manager
+- Diana Designer
+- Samantha Salesperson
+- Tony Trainer
+- Petra Product Manager
+
+**Why:** Easier to remember, more human, makes documentation engaging
+
+---
+
+### Bad Examples
+- John (generic)
+- User 1 (impersonal)
+- Target Group A (clinical)
+
+**Why bad:** Forgettable, boring, doesn't bring persona to life
+
+---
+
+## Documentation Maintenance
+
+**Documents are living artifacts:**
+
+### When to Update
+- ✅ New information discovered
+- ✅ Assumptions proven wrong
+- ✅ Priorities shift
+- ✅ Scope changes
+- ✅ Phase completes
+
+### Version Control
+- Use git for all documentation
+- Commit with clear messages
+- Tag major milestones
+- Keep history
+
+### Archive, Don't Delete
+- Old versions have context value
+- Create `archive/` folder if needed
+- Document why something changed
+
+---
+
+## Documentation Handoffs
+
+**When handing to development team:**
+
+### Complete Package Includes
+1. **Product Brief** - Strategic foundation
+2. **Trigger Map** - User psychology
+3. **Platform PRD** - Technical requirements
+4. **Page Specifications** - Detailed UX specs
+5. **Design System** (if created) - Component library
+6. **Design Delivery PRD** - Complete handoff package
+
+**See:** Phase 6 (Design Deliveries) for handoff process
+
+---
+
+## Quality Checklist
+
+Before marking documentation "complete":
+
+- [ ] **Clear purpose** - Why does this document exist?
+- [ ] **Specific names** - No README.md or generic.md?
+- [ ] **Absolute paths** - All file references explicit?
+- [ ] **Evidence-based** - Claims backed by research/data?
+- [ ] **Accessible language** - Readable by all stakeholders?
+- [ ] **Structured well** - Scannable, logical hierarchy?
+- [ ] **Up to date** - Reflects current reality?
+- [ ] **Actionable** - Others can use this to make decisions?
+
+---
+
+## Related Resources
+
+- **Product Brief Workflow:** `../../workflows/1-project-brief/project-brief/`
+- **File Naming Conventions:** `../../workflows/00-system/FILE-NAMING-CONVENTIONS.md`
+- **Project Outline Template:** Created during Phase 1 Step 1
+- **Documentation Standards:** `../../../bmm/data/documentation-standards.md`
+
+---
+
+*Good documentation is the foundation of coordinated, confident execution. It's not overhead - it's leverage.*
+
+