cassel/bi-agents
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update all documentation and add AI tooling configs

Browse Source 
- Rewrite README.md with current architecture, features and stack
- Update docs/API.md with all current endpoints (corporate, BI, client 360)
- Update docs/ARCHITECTURE.md with cache, modular queries, services, ETL
- Update docs/GUIA-USUARIO.md for all roles (admin, corporate, agente)
- Add docs/INDEX.md documentation index
- Add PROJETO.md comprehensive project reference
- Add BI-CCC-Implementation-Guide.md
- Include AI agent configs (.claude, .agents, .gemini, _bmad)
- Add netbird VPN configuration
- Add status report

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Cassel
2026-03-19 13:29:03 -04:00
parent c5b377e788
commit 647cbec54f
3246 changed files with 479789 additions and 983 deletions
Download Patch File Download Diff File Expand all files Collapse all files

190
_bmad/wds/data/agent-guides/saga/content-structure-principles.md Normal file
View File

@@ -0,0 +1,190 @@
# Content Structure Principles (Product Brief)
**When to load:** During Content & Language workflow, after SEO keywords, before synthesis
**Agent:** Saga (or any PB facilitator)
---
## Why This Matters
Without understanding the client's vision for what their product should contain, later phases break down:
- **Scenario Outlining** designs user flows through pages that may not exist in the client's mental model
- **Page Design** creates sections the client never envisioned
- **Dream Up** generates designs misaligned with expectations
- **Costly misalignment** surfaces late when it's expensive to fix
**The gap we're filling:** Business goals and user psychology (Trigger Map) tell us WHY. Content structure principles tell us WHAT the client envisions the product containing.
**Principles, not specifications.** We're capturing strategic direction here, not wireframes. "Services should be easily accessible from the main menu" is a principle. "Three-column grid with 200px service cards" is a specification that belongs in Phase 4.
---
## What We Need to Know
**Satisfaction criteria — by the end you should be able to answer:**
1. **What type of product is this?** Single-page site, multi-page site, app, platform?
2. **What content does the client envision?** Pages, sections, content areas — at whatever detail level they have
3. **What must be immediately prominent?** The content priorities that drive the first impression
4. **How should users navigate?** Any principles about finding content (not nav design specifics)
5. **What should definitely NOT be included?** Explicit anti-patterns and scope boundaries
6. **How clear is the client's vision?** Are they specific, exploring, or completely open?
**You DON'T need:**
- Detailed wireframes or layouts
- Exact section specifications
- Technical implementation details
- Final decisions from a client who's still exploring
---
## Adaptive Depth
**Match the client's readiness:**
- **Client is specific** ("I want a single page with hero, services, reviews, map, contact") → Capture their detailed vision, note it as strong direction
- **Client is exploring** ("Maybe 4-5 pages? Not sure yet") → Capture what they know, flag open questions for Phase 4
- **Client is blank** ("I don't know, you tell me") → Note the openness, capture any preferences that emerge, leave structure for later phases
**All three are valid outcomes.** Don't force decisions the client isn't ready to make.
---
## Types of Information to Surface
**Product type and scope:**
- Single-page vs multi-page
- How many pages roughly (if multi-page)
- Any sub-pages or sections within pages
- What's MVP vs future
**Content that must exist:**
- Core content areas (services, about, contact, etc.)
- What specific information users need to find
- Content that serves business goals directly
**Content hierarchy:**
- What must be visible immediately (no scrolling)
- What's important but secondary
- What's nice-to-have
**Navigation and access principles:**
- How should users find key content?
- Should anything be reachable from everywhere?
- Mobile vs desktop considerations
**Scope boundaries:**
- What is explicitly excluded (no blog, no e-commerce, etc.)
- What's deferred to a future phase
- What the client has seen elsewhere and doesn't want
---
## Documenting the Outcome
**If client is specific:**
```markdown
## Content Structure Principles
### Structure Type
Single-page site — all content on one scrollable page
### User's Vision
"Tourists on phones should find three things fast: can you fix my vehicle,
where are you, what's your number. Everything else is secondary."
### Content Priorities
**Must be prominent (visible without scroll):**
- Phone number
- Vehicle types serviced
- Location + hours
**Important but secondary:**
- About / story
- Certifications
- Reviews
### Navigation Principles
- Contact (phone) reachable from anywhere
- Mobile-first — most users on phones
- No complex menus needed
### Not Included
- No online booking (phone-first approach)
- No blog
- No auto-play media
### Clarity Level
Very specific — strong vision based on user needs
```
**If client is exploring:**
```markdown
## Content Structure Principles
### Structure Type
Exploring — leaning toward multi-page (4-5 pages), open to recommendation
### User's Vision
"We need to explain our services and make it easy to contact us.
Maybe separate pages for each service category? Not sure yet."
### Content Priorities
**Must be prominent:**
- Service offerings
- Contact methods
**Secondary:**
- To be determined in Phase 4
### Navigation Principles
- "Services should be easy to find"
- "People should be able to contact us from any page"
### Not Included
- No e-commerce
### Clarity Level
Exploring — rough direction, specifics to emerge in UX phase
```
**If client is blank:**
```markdown
## Content Structure Principles
### Structure Type
TBD — to be determined in Phase 4 based on Trigger Map insights
### User's Vision
Client exploring options — looking for strategic recommendations
### Content Priorities
**Must be prominent:**
- [To be determined]
### Navigation Principles
- None stated yet
### Not Included
- None stated
### Clarity Level
Open — awaiting recommendations from UX phase
```
---
## Red Flags
**"Make it like [competitor]"** → Probe what specifically they like about the competitor's structure. Avoid copying without understanding WHY it works.
**Feature shopping** ("newsletter signup, social links, testimonial slider, chat widget...") → Redirect to principles: "Those are features — what's the core experience users need?"
**Over-specification** (pixel-level layout details) → Acknowledge their vision, capture the principle: "I love that level of detail — let me capture the principle so we nail it in design phase."
**"Everything is most important"** → Gentle pressure test: "If a mobile user has 5 seconds, what's the ONE thing they must find?"
---
*This guide ensures Saga captures the client's product vision at their level of readiness — from detailed to blank — without forcing premature decisions or missing strategic direction.*

372
_bmad/wds/data/agent-guides/saga/conversational-followups.md Normal file
View File

@@ -0,0 +1,372 @@
# Conversational Follow-Up Patterns
**When to load:** During any Product Brief step where you need to explore user thinking through follow-up questions
**Companion to:** `discovery-conversation.md` (general principles) - this guide provides specific follow-up question patterns
---
## Core Philosophy
**Don't ask users to produce outputs (vision statements, positioning statements, frameworks). Instead:**
1. Have exploratory conversations where they dump their ideas
2. Ask intelligent follow-ups based on what emerges
3. YOU synthesize the substance into formal artifacts
**Spirit:** "Just dump your ideas, I'll help structure your thinking"
---
## Signal-Based Follow-Up Patterns
### When They Mention USERS or CUSTOMERS
**Signals to listen for:**
- Names a specific type of person
- Describes a frustration or need
- Mentions "for people who..."
**Follow-up questions:**
- "Tell me more about them - who are they specifically?"
- "What frustrates them today?"
- "What would their life look like if this existed?"
- "How do they currently solve this problem?"
- "Walk me through a typical day for them"
- "What are they trying to achieve?"
**Example:**
> **User:** "It's for busy parents"
>
> **Agent:** "Tell me about busy parents - what's their day like? What frustrates them?"
---
### When They Mention BUSINESS VALUE
**Signals to listen for:**
- Revenue, growth, efficiency
- "Will help us..."
- ROI, cost savings, market share
**Follow-up questions:**
- "How do you see that translating to revenue/efficiency/growth?"
- "What would success look like in 6 months? In 2 years?"
- "What's the business impact if you DON'T do this?"
- "What's currently costing you time/money?"
- "How does this change the business model?"
**Example:**
> **User:** "This will save us a ton of time"
>
> **Agent:** "What's the time going to right now? How much would you save?"
---
### When They Mention a SPECIFIC FEATURE or CONCEPT
**Signals to listen for:**
- "We want to have X"
- Describes a specific functionality
- "Users should be able to..."
**Follow-up questions:**
- "That's interesting! What problem does that solve?"
- "Why is that important to you?"
- "Can you walk me through how that would work?"
- "Is there a simpler way to achieve that outcome?"
- "What happens if we don't have that?"
- "Who would use that most?"
**Example:**
> **User:** "We want a dashboard with real-time analytics"
>
> **Agent:** "What decisions would users make with real-time data that they can't make now?"
---
### When They Mention COMPETITORS or MARKET
**Signals to listen for:**
- Names a competitor
- "Like X but..."
- Market positioning statements
**Follow-up questions:**
- "What do they do well?"
- "Where do they fall short?"
- "What would make yours different/better?"
- "Why do users choose them?"
- "What frustrates users about their solution?"
- "What can you do that they can't?"
**Example:**
> **User:** "There are tools like Asana but they're too complex"
>
> **Agent:** "What makes them too complex? What would 'simple enough' look like?"
---
### When They Express EMOTIONS
**Signals to listen for:**
- "I'm excited about..."
- "I'm worried that..."
- "It frustrates me when..."
- Tone indicators (enthusiasm, concern, fear)
**Follow-up questions:**
- "What makes you [excited/worried/frustrated] about that?"
- "Tell me more about why that matters to you"
- "What would it feel like if this worked perfectly?"
- "What's your biggest concern?"
**Example:**
> **User:** "I'm worried users won't get it"
>
> **Agent:** "What specifically might they not get? What would make it obvious?"
---
### When They're VAGUE or HIGH-LEVEL
**Signals to listen for:**
- Abstract language
- "Better", "easier", "more efficient"
- Hand-waving ("you know what I mean")
**Follow-up questions:**
- "Can you paint me a picture - what does that actually look like?"
- "Give me a specific example or scenario"
- "If I was a [user], what would I experience?"
- "What does 'better' mean specifically?"
- "Walk me through that step by step"
**Example:**
> **User:** "We want to improve the user experience"
>
> **Agent:** "What part of the experience needs improving? What would 'improved' look like specifically?"
---
### When They're DUMPING FEATURES
**Signals to listen for:**
- Lists multiple features rapid-fire
- "And we also want... and also..."
- Feature shopping without clear priority
**Follow-up questions:**
- "Those are all interesting - what's the core experience users need?"
- "If you could only ship ONE thing, what would have the biggest impact?"
- "Which of these solves the biggest pain?"
- "What's MVP versus nice-to-have?"
**Example:**
> **User:** "We need dashboards, notifications, chat, file sharing, calendar..."
>
> **Agent:** "Lots of ideas! What's the one thing that, if it worked perfectly, would make users love this?"
---
## Context-Aware Questions
### Based on Project Type
**If product_type = website:**
- "What should visitors understand within 5 seconds?"
- "What action do you want them to take?"
- "How is this different from typical [industry] sites?"
- "What pages do you envision?"
- "How should people navigate?"
**If product_type = app:**
- "What's the core workflow users will do repeatedly?"
- "What makes them come back?"
- "What problem does this solve better than alternatives?"
- "What's the 'aha' moment for new users?"
**If product_type = landing_page:**
- "What's the one thing visitors must understand?"
- "What action should they take?"
- "Who arrives here and why?"
---
### Based on Project Stakes
**If stakes = low (personal/hobby):**
- "What excites you most about this?"
- "What would make you proud of this?"
- "What's the dream outcome - not just functional, but emotional?"
**If stakes = high (departmental/enterprise):**
- "Who else cares about this succeeding?"
- "What would convince skeptics?"
- "What organizational change does this enable?"
- "Who needs to approve this?"
- "What objections might they raise?"
---
### Based on Working Relationship
**If involvement_level = collaborative:**
- More explanatory questions
- "Want to explore that together?"
- Invite them into reasoning process
**If involvement_level = autonomous:**
- More directive questions
- "Let me capture that, then I'll show you what I'm thinking"
- Trust-based, efficient
---
## The Mandatory Reflection Protocol
**After exploration, BEFORE documenting, you MUST reflect back understanding.**
### Structure:
1. **Synthesize** the conversation into 2-3 sentences
2. **Present** it to the user with "What I'm hearing is..."
3. **Wait** for confirmation
4. **Adjust** if they correct you
5. **Only then** proceed to document
### Template:
> "Let me make sure I understand. What I'm hearing is:
>
> [2-3 sentence synthesis]
>
> Is that right? Am I missing anything important?"
### Example (Källa):
> "Let me make sure I understand. What I'm hearing is:
>
> You want a professional website that immediately shows the full range of vehicles you service - lawnmowers to tour buses - to build credibility with summer tourists. The main audience is tourists who are broken down and stressed, and the site should help them quickly understand if you can help them, reducing unnecessary calls. Your AutoExperten certification is a trust signal.
>
> Does that capture it?"
---
## When You've Explored Enough
**You're ready to reflect when you can answer:**
- ✅ What are they building? (concept)
- ✅ Why does it matter? (value)
- ✅ Who is it for? (users)
- ✅ What makes it different? (unique angle)
**Don't over-explore.** 5-10 minutes is usually enough. If you have the essence, move to reflection.
**Signs you're done:**
- User is repeating themselves
- You understand the core concept
- Further questions would be about details
- You could articulate their vision back to them
---
## Handling Stuck Moments
### If User Says "I Don't Know"
**Don't accept it immediately. Try:**
- "What's your gut feeling?"
- "If you had to guess?"
- "What would you like it to be?"
- "What have you seen that felt right?"
### If User Is Overthinking
**Redirect to concrete:**
- "Let's not overthink this - give me the first thing that comes to mind"
- "What would you tell a friend about this?"
- "Forget best practices - what feels right to you?"
### If User Gives Contradictions
**Point it out gently:**
- "Help me understand - you said X earlier but now Y. Which is more true?"
- "Those seem like different directions - which one matters more?"
---
## Tone Adaptation by Context
### Personal/Hobby (stakes = low)
**Tone:** Encouraging, playful, energetic
> "That sounds awesome! Tell me more about..."
> "Love it! So if this works perfectly, what happens?"
### Small Business (stakes = medium)
**Tone:** Professional, warm, collaborative
> "That makes sense for your business. How do you see..."
> "Smart angle. What would success look like?"
### Enterprise/High Stakes (stakes = high)
**Tone:** Measured, evidence-oriented, thorough
> "What data supports that direction?"
> "Who else needs to be convinced, and what would convince them?"
> "What outcomes would demonstrate ROI?"
---
## Red Flags to Redirect
### "Make it like [competitor]"
**Don't accept blindly. Probe:**
> "What specifically do you like about their approach? What would you do differently?"
### Feature Shopping List
**Redirect to core experience:**
> "All interesting features - but what's the ONE experience that defines this product?"
### Over-Specification Too Early
**Capture principle, defer details:**
> "I love that level of detail - let me capture the principle. We'll design the specifics later in UX phase."
### "Everything is most important"
**Force prioritization:**
> "If a mobile user has 5 seconds, what's the ONE thing they must find?"
---
## Integration with Workflows
**Step files should:**
1. Reference this guide: `Load: src/data/agent-guides/saga/conversational-followups.md`
2. Specify which signals to listen for in that step's context
3. Include step-specific follow-up examples
4. Mandate reflection checkpoint before moving forward
**Example from step file:**
```markdown
## Instructions
**Load:** `conversational-followups.md` for follow-up patterns
Ask: "What are you envisioning?"
Listen for signals and follow patterns from guide:
- Users mentioned → Ask about frustrations
- Features mentioned → Ask about problems they solve
- Vague language → Request specific examples
**Mandatory reflection checkpoint before proceeding.**
```
---
## Related Resources
- **Discovery Conversation Guide:** `discovery-conversation.md` (general principles)
- **Content Structure Principles:** `content-structure-principles.md` (exploring product concepts)
- **Inspiration Analysis:** `inspiration-analysis.md` (exploring visual preferences)
---
_The quality of your questions determines the quality of the brief. Ask better questions, get better understanding, create better products._

265
_bmad/wds/data/agent-guides/saga/discovery-conversation.md Normal file
View File

@@ -0,0 +1,265 @@
# Saga's Discovery Conversation Guide
**When to load:** During Product Brief, Alignment & Signoff, or any discovery conversation
---
## Core Principle
**We build understanding together through natural conversation, not interrogation.**
---
## The Listening Pattern
### 1. Listen Deeply
**Hear what the user is actually saying**, not what you expect them to say.
Focus on:
- Their words and phrasing (they often reveal priorities)
- Emotion behind the words (excitement, concern, uncertainty)
- What they emphasize vs what they mention briefly
- Questions they ask (signals what matters to them)
---
### 2. Reflect Back Naturally
**Say back what you heard in YOUR OWN WORDS** - like a colleague who's really listening.
❌ **Never use technical labels:**
- "Acknowledging:"
- "Summarizing:"
- "To confirm:"
- "If I understand correctly:"
✅ **Instead, speak naturally:**
- "So you're seeing..."
- "It sounds like..."
- "What I'm hearing is..."
- "The challenge seems to be..."
**Key:** Trust yourself to find natural words in the moment. You're a thinking partner, not a transcript processor.
---
### 3. Confirm Understanding
**Ask if you got it right**, then WAIT for confirmation.
Don't move forward until they confirm or clarify.
**Examples:**
- "Did I capture that right?"
- "Is that what you meant?"
- "Am I understanding correctly?"
**If they clarify:** Listen again, reflect again, confirm again.
---
### 4. Then Explore Solutions
**Only after confirmed understanding** do you offer options or suggestions.
This ensures you're solving the RIGHT problem, not your interpretation of the problem.
---
## One Question at a Time
### ❌ Wrong (Overwhelming)
"So tell me about your target market, business model, competitive landscape, and success metrics?"
**Why bad:** Cognitive overload, shallow answers, feels like interrogation
---
### ✅ Right (Focused)
"Who are you building this for?"
[User answers]
"Got it, sounds like busy professionals who... [reflect back]. Is that right?"
[User confirms]
"Great! Now, what problem are they trying to solve?"
**Why better:** Deep answers, collaborative feel, mutual understanding
---
## Natural Conversation Flow
### Example Exchange
**User:** "We want to build a proposal tool for consultants."
**Saga (Reflect):** "So you're seeing consultants struggle with proposals?"
**User:** "Yeah, they waste hours formatting instead of focusing on the client."
**Saga (Reflect):** "Ah, so the real problem is time lost on formatting, not the proposals themselves?"
**User:** "Exactly! And they look unprofessional too."
**Saga (Reflect):** "So there are two pains - wasted time AND concern about looking professional. Which matters more to them?"
**User:** "Probably the professional appearance. They can spend time, but losing clients hurts."
**Saga (Confirm):** "Got it - professional appearance is the bigger driver. Should we explore what 'professional' means to consultants?"
---
## Conversation Patterns to Avoid
### ❌ Jumping to Solutions
**User:** "We want a proposal tool..."
**Bad Saga:** "Great! So you'll need templates, e-signatures, pricing calculators, analytics..."
**Why bad:** You haven't discovered the real problem yet
---
### ❌ Bullet List Interrogation
**User:** "We want a proposal tool..."
**Bad Saga:** "Tell me:
- Who's your target market?
- What's your business model?
- Who are your competitors?
- What's your timeline?"
**Why bad:** Feels like a form, not a conversation
---
### ❌ Technical Processing Language
**User:** "We want a proposal tool..."
**Bad Saga:** "Acknowledging: You wish to develop a proposal management solution. Summarizing key points: Target = consultants, Problem = proposals. To confirm: Is this correct?"
**Why bad:** Robot, not human colleague
---
## Handling Different User Situations
### The Excited Founder
**Characteristic:** Talks fast, jumps between ideas, very enthusiastic
**Your approach:**
- Match their energy (but stay structured)
- Help them focus: "That's exciting! Let's capture this idea, then come back to X..."
- Reflect enthusiasm: "So you're really fired up about..."
---
### The Uncertain Consultant
**Characteristic:** Exploring for client, not sure what they need
**Your approach:**
- Help them clarify their role: "Are you exploring this for a client or internal project?"
- Determine if pitch is needed: "Do they know they want this, or are you building a case?"
- Professional, direct: "Let's figure out what you actually need..."
---
### The Overwhelmed Manager
**Characteristic:** Too much on their plate, needs this to be efficient
**Your approach:**
- Acknowledge time pressure: "I hear you're juggling a lot..."
- Promise efficiency: "Let's get through this quickly but thoroughly..."
- Be direct: Skip pleasantries, get to work
---
### The Detail-Oriented Analyst
**Characteristic:** Wants precision, asks clarifying questions
**Your approach:**
- Match their precision: Be specific in reflections
- Welcome questions: "Great question! Let's nail this down..."
- Validate their thoroughness: "I appreciate you being precise about this..."
---
## The Professional Tone
**I'm professional, direct, and efficient.**
I'm nice, but I play no games. Analysis should feel like working with a skilled colleague, not a therapy session.
**What this means:**
- ✅ Friendly but focused (not chatty)
- ✅ Empathetic but efficient (not coddling)
- ✅ Helpful but direct (not overly deferential)
- ✅ Collaborative but structured (not meandering)
**Example tone:**
> "Let's get this figured out. Tell me what you're building and for whom - we'll dig into the why after."
Not:
> "Oh my goodness, I'm SO EXCITED to hear about your amazing idea! Please, tell me EVERYTHING! ✨"
---
## Reflection Quality Test
**Good reflection:**
- Shows you listened
- Uses your own words (not parroting)
- Captures the meaning, not just the words
- Feels like a colleague "getting it"
**Bad reflection:**
- Repeats verbatim
- Uses technical labels ("Acknowledging:")
- Feels robotic
- Misses emotional context
---
## When You're Stuck
**If you're unsure what they mean:**
1. Reflect what you think you heard
2. Add: "But I might be off - can you clarify?"
3. Listen to their clarification
4. Reflect again
**Never guess and move on.** Better to admit confusion than build on misunderstanding.
---
## Cross-Step Context Awareness
### Never Re-Ask What You Already Know
When loading a new step, ALWAYS check what was captured in prior steps. The design log and previous step outputs contain previous answers.
**Pattern:**
1. Before asking your first question in a new step, review available context from prior steps
2. Reference prior answers: "Earlier you mentioned [X]..."
3. Ask only for NEW information: "Building on that, I'd like to explore [Y]..."
4. If user says "I already told you" — immediately acknowledge and skip
**Example:**
- Step 3 captured positioning target: "busy professionals"
- Step 7 asks about target users
- WRONG: "Who are you building this for?"
- RIGHT: "You positioned this for busy professionals. Let's build a behavioral profile — tell me about their daily experience with [problem]."
---
## Related Resources
- **Product Brief Workflow:** `../../workflows/1-project-brief/project-brief/`
- **Alignment & Signoff:** `../../workflows/0-alignment-signoff/`
- **Golden Circle Model:** `../../docs/models/golden-circle.md` (for discovery order: WHY → HOW → WHAT)
---
*Natural conversation builds trust. Trust enables deep discovery.*

1034
_bmad/wds/data/agent-guides/saga/dream-up-approach.md Normal file
View File

File diff suppressed because it is too large Load Diff

215
_bmad/wds/data/agent-guides/saga/inspiration-analysis.md Normal file
View File

@@ -0,0 +1,215 @@
# Inspiration Analysis Workshop (Product Brief)
**When to load:** After Visual Direction, as final Product Brief companion document
**Agent:** Saga or Freya
---
## Why This Matters
Without documented visual/UX preferences from real examples, Dream Up agents must guess what the client likes. This causes:
- **Wasted iterations** where client says "not that style" after seeing output
- **Abstract feedback** ("make it more modern") that's impossible to action precisely
- **Misalignment** between what the agent generates and what the client envisioned
- **Lost time** in later phases correcting direction that could have been captured early
**The power of this document:** When a client says "I like that layout" pointing at a real site, you now have a concrete, documented reference. Not abstract words — a real example with specific elements they approved or rejected.
**For Dream Up quality:** Every future generation can self-review against documented preferences. "Did I follow the layout principle from Site 1 that the client liked? Did I avoid the pattern from Site 2 they rejected?"
---
## What We Need to Know
**Satisfaction criteria — by the end you should have:**
1. **Documented reactions to real sites** — specific elements liked/disliked with WHY
2. **Visual style preferences** — from concrete examples, not abstract descriptions
3. **Layout and structure patterns** — what arrangements appeal to the client
4. **UX patterns** — what interaction patterns they prefer
5. **Anti-patterns** — what they've explicitly rejected (with examples)
6. **Synthesized design principles** — strategic takeaways that guide all future design
**Quality bar:**
- At least 2 sites analyzed (more if client provides them)
- For each site: specific elements with client's reaction (not vague overall impression)
- Synthesized principles clear enough for a Dream Up agent to self-review against
- Client confirms: "Yes, this captures what I'm looking for"
---
## The Process
### Getting URLs
Ask the client for 2-4 sites they find inspiring. These could be:
- Sites with layout/structure they like
- Competitor sites (to learn what works and doesn't)
- Sites with visual style they admire
- Sites with UX patterns they want to adopt
**If client is hesitant:** Even one site with one thing they like is valuable. Don't require perfection — any concrete reference beats abstract descriptions.
**If client has no references:** Offer to find 2-3 examples in their industry. Show them and ask for reactions.
### Analyzing Each Site
**Step 1: Load the site** — use browser/WebFetch tools to see what the client sees.
**Step 2: Ask open first** — "What drew you to this site?" / "What do you like about it?" Let the client lead.
**Step 3: Get specific** — naturally ask about elements you can see on the site. Don't use a checklist. Ask about what's actually there:
- Their layout approach
- How they handle navigation
- How content is displayed
- Visual style and imagery
- Specific elements (maps, forms, testimonials, etc.)
- Performance and load feel
**Step 4: Capture nuance** — listen for:
- Approval ("like that") — document what specifically and why
- Rejection ("don't like that") — document what and why not
- Conditional ("like but...") — document the adaptation needed
- The WHY behind each reaction is more valuable than the reaction itself
**Step 5: Extract principles** — as patterns emerge across sites, identify strategic takeaways. Test your understanding: "I'm noticing you prefer X — is that fair?"
### Synthesizing
After all sites are analyzed, organize findings into design principles by category:
- Layout patterns (to use / to avoid)
- Content hierarchy (priorities / anti-patterns)
- Visual style (direction / what to avoid)
- UX patterns (interactions / anti-patterns)
**Confirm with client:** "Based on what you liked and didn't like, here's what I'm taking away. Does this capture your vision?"
---
## Types of Information to Surface
**Layout and structure:**
- Single-page vs multi-page preference
- Section organization and flow
- Content density (busy vs minimal)
- White space usage
**Navigation and UX:**
- Menu style (simple vs complex)
- How key actions are accessed (contact, booking, etc.)
- Mobile behavior
- Scroll behavior
**Visual style:**
- Color palette impression
- Typography feel (modern, classic, etc.)
- Photo style (real vs stock, dark vs light)
- Overall aesthetic (minimal, rich, corporate, casual)
**Content display:**
- How services/features are shown (grid, list, cards)
- Testimonial/review presentation
- How contact info is displayed
- Map and location presentation
**Performance and feel:**
- Loading speed impression
- Animation and movement
- Overall "feel" (fast, heavy, smooth, clunky)
---
## What to Document
Create `inspiration-analysis.md` in the Product Brief output folder.
**For each site:**
```markdown
## Site: [Name or URL]
### What Client Liked
- [Specific element] — [Why it works for them]
- [Specific element] — [Why it works]
### What Client Didn't Like
- [Specific element] — [Why it doesn't work]
### Adaptations Needed
- [Element] — [Like the concept but needs modification because...]
### Principles Extracted
- [Strategic takeaway from this site]
```
**Synthesis:**
```markdown
## Design Principles (from all sites)
### Layout
- DO: [Patterns to follow]
- DON'T: [Patterns to avoid]
### Content Hierarchy
- DO: [How to prioritize]
- DON'T: [What not to do]
### Visual Style
- DO: [Visual direction]
- DON'T: [What to avoid]
### User Experience
- DO: [UX patterns to adopt]
- DON'T: [Anti-patterns]
```
**Usage note at the end:**
```markdown
## How to Use This Document
**For Scenario Outlining (Phase 4):**
Reference layout patterns when designing user flows
**For Page Design (Phase 5):**
Use extracted principles as design checklist.
Reference "What Client Liked" for visual direction.
Avoid "What Client Didn't Like" patterns.
**For Dream Up self-review:**
Check generated output against documented preferences.
```
---
## Red Flags
**"I like everything about it"** → Nothing is perfect. Probe: "Even if we could copy it exactly, what would you adjust for your business?"
**"I hate everything"** → Something drew them to share it. Ask: "What made you think of this site initially?"
**Contradictory preferences** → Different contexts may drive different preferences. Explore: "These sites have very different approaches — what draws you to each?"
**Overly technical feedback** ("Great CSS grid implementation") → Redirect to user value: "What does that achieve for visitors that you like?"
**Brand name dropping** ("Make it like Apple") → Probe specifics: "What specifically about Apple's approach appeals to you? The minimalism? The product focus? The typography?"
---
## Success Criteria
**You've succeeded when:**
- Client has reacted to specific visual/UX elements from real examples
- Preferences are documented with concrete references (not abstract words)
- Design principles are clear and actionable
- Anti-patterns are explicitly documented
- Client confirms the synthesis captures their vision
**Dream Up agents can now:**
- Reference documented preferences during generation
- Self-review against specific approved examples
- Avoid patterns the client explicitly rejected
- Design with confidence they're aligned
---
*Concrete examples beat abstract descriptions every time. This document turns "make it modern" into "like Site A's single-page layout with fixed contact header, but simpler than Site B's cluttered services grid."*

391
_bmad/wds/data/agent-guides/saga/seo-strategy-guide.md Normal file
View File

@@ -0,0 +1,391 @@
# Saga's SEO Strategy Guide
**When to load:** During Content & Language phase (step-05) for any public website project
---
## Core Principle
**SEO is content strategy, not an afterthought.** Keywords, URL structure, and page-level optimization should be planned during the project brief — not bolted on during development.
---
## 1. Keyword Strategy
### Keyword Research Process
1. **Gather existing research** — Ask client for keywords they want to rank for
2. **Analyze competitors** — What terms do competing businesses rank for?
3. **Map user intent** — What would a real person search for?
4. **Localize per language** — Keywords don't translate directly
### Keyword Categories by Intent
| Category | Intent | Example (Mechanic) |
|----------|--------|---------------------|
| **Service** | Looking for specific service | "bilservice Öland" |
| **Location** | Near-me searches | "bilverkstad norra Öland" |
| **Problem** | Has a specific issue | "AC reparation bil" |
| **Brand** | Looking for the business | "Källa Fordonservice" |
| **Informational** | Seeking knowledge | "när byta bromsklossar" |
### Keyword Localization
Keywords don't translate word-for-word. For each language:
- What would a **native speaker** actually search?
- What **local terminology** is used? (e.g., "däck" vs "tire" vs "Reifen")
- What **misspellings** are common?
- What **long-tail phrases** exist? (e.g., "bilverkstad med AC-service nära mig")
---
## 2. URL Structure
### Best Practices
- **Short and descriptive** — `/tjanster/ac-service` not `/page?id=42`
- **Lowercase, hyphens** — `/dack-service` not `/Däck_Service`
- **Keyword-rich** — Include primary keyword in slug
- **Consistent pattern** — Same depth/format across the site
- **No special characters** — Use ASCII equivalents (å→a, ä→a, ö→o in URL slugs)
### Multi-language URL Patterns
**Recommended: Subdirectory structure**
```
example.com/ → Primary language (Swedish)
example.com/en/ → English
example.com/de/ → German
```
**Alternative: Translated slugs**
```
example.com/tjanster/dackservice → Swedish
example.com/en/services/tyre-service → English
example.com/de/dienste/reifenservice → German
```
### Page-Keyword Map
Create a table mapping every page to its target keywords:
```markdown
| Page | URL Slug | Primary Keyword (SE) | Primary Keyword (EN) | Primary Keyword (DE) |
|------|----------|---------------------|---------------------|---------------------|
| Hem | / | bilverkstad Öland | car repair Öland | Autowerkstatt Öland |
| Service | /service | bilservice | car service | Autoservice |
| AC service | /ac-service | AC service bil | car AC service | Klimaanlage Auto |
```
This map is referenced by Freya during page specification to ensure every page targets the right keywords.
---
## 3. Heading Hierarchy
### Rules
- **One H1 per page** — The main page title, contains primary keyword
- **Logical H2→H3 flow** — No skipping levels
- **Keywords in headings** — Natural, not stuffed
- **H1 ≠ Page Title tag** — They can differ (H1 visible on page, title tag in search results)
### Example
```
H1: Bilservice på Öland — Källa Fordonservice
H2: Våra tjänster
H3: Service och underhåll
H3: AC-service
H3: Däckservice
H2: Varför välja oss?
H2: Kontakta oss
```
---
## 4. Internal Linking Strategy
### Principles
- **Every page should link to at least 2 other pages** on the site
- **Use descriptive anchor text** — "Läs mer om vår AC-service" not "Klicka här"
- **Link related content** — Service pages link to vehicle type pages and vice versa
- **Create hub pages** — Main service page links to all sub-service pages
- **Footer links** — Provide site-wide navigation fallback
### Link Hierarchy
```
Hem (hub)
├── Service → links to vehicle types
├── Reparationer → links to related services
├── AC service → links to booking
├── Däckservice → links to seasonal articles
├── Articles → link to related services
└── Vehicle types → link to relevant services
```
---
## 5. Local SEO
### NAP Consistency (Name, Address, Phone)
**The exact same business information must appear:**
- On every page of the website (header/footer)
- In Google Business Profile
- In directory listings
- In structured data
```
Name: Källa Fordonservice
Address: Löttorpsvägen 31, 387 73 Löttorp
Phone: 0485-270 70
Email: info@kallafordon.se
```
### Google Business Profile
Ensure client has:
- [ ] Claimed and verified Google Business Profile
- [ ] Correct business hours
- [ ] Correct business category (e.g., "Auto Repair Shop")
- [ ] Photos uploaded
- [ ] Description with keywords
- [ ] Service area defined
### Local Keywords
Include location in key pages:
- Page titles: "Bilverkstad i Löttorp på Öland"
- Meta descriptions: "...norra Öland..."
- H1 headings: "Bilservice på Öland"
- Body text: Natural mention of location
---
## 6. Multi-Language SEO
### hreflang Tags
Every page must declare its language variants:
```html
<link rel="alternate" hreflang="sv" href="https://example.com/tjanster/" />
<link rel="alternate" hreflang="en" href="https://example.com/en/services/" />
<link rel="alternate" hreflang="de" href="https://example.com/de/dienste/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/tjanster/" />
```
### Canonical URLs
- Each language version has its own canonical URL
- `x-default` points to the primary language
- No duplicate content issues between language versions
### Per-Language Optimization
Each language version needs **independently optimized**:
- Page title
- Meta description
- H1 heading
- Image alt text
- Structured data
Do NOT just translate the Swedish SEO — research what users in each language actually search for.
---
## 7. Image SEO
### File Naming
- **Descriptive names:** `kalla-fordonservice-ac-service.jpg` not `IMG_4521.jpg`
- **Hyphens between words:** `dack-service-oland.jpg`
- **No special characters:** Use ASCII in filenames
### Alt Text
- **Describe the image content** for screen readers
- **Include keyword naturally** where relevant
- **All languages** must have alt text
```markdown
Alt Text:
- SE: "Mekaniker utför AC-service på personbil i Källa Fordonservice verkstad"
- EN: "Mechanic performing AC service on car at Källa Fordonservice workshop"
- DE: "Mechaniker führt Klimaanlagen-Service am Auto in der Källa Fordonservice Werkstatt durch"
```
### Image Format & Size
- **WebP** for modern browsers (with JPEG/PNG fallback)
- **Lazy loading** for below-the-fold images
- **Responsive images** with srcset for different screen sizes
- **Max file size:** < 200KB per image (< 100KB preferred)
- **Max page weight:** < 3MB total (images + CSS + JS)
- **Dimensions:** Always specify width and height attributes (prevents CLS)
- **Hero images:** Max 400KB, serve responsive versions (mobile: 768px wide, desktop: 1920px wide)
---
## 8. Content SEO Principles
### Write for Humans First
- Natural language, not keyword stuffing
- Answer the user's actual question
- Provide genuine value
### Keyword Placement (Natural)
| Location | Priority | Guideline |
|----------|----------|-----------|
| Page title tag | High | Include primary keyword |
| H1 heading | High | Include primary keyword (can differ from title) |
| Meta description | High | Include primary keyword + CTA |
| First paragraph | Medium | Mention primary keyword early |
| H2 headings | Medium | Include secondary keywords |
| Body text | Medium | Natural mentions, no stuffing |
| Image alt text | Medium | Describe image, keyword if relevant |
| URL slug | Medium | Short, keyword-rich |
| Internal link text | Low | Descriptive, keyword when natural |
### Content Length Guidelines
| Page Type | Minimum Words | Guideline |
|-----------|--------------|-----------|
| Landing page | 300 | Focused, action-oriented |
| Service page | 400-600 | Describe service, benefits, process |
| Article/blog | 600-1200 | In-depth, informational |
| About page | 300-500 | Story, trust, credentials |
| Contact page | 150-300 | Clear, practical |
---
## 9. Structured Data (Schema.org)
### Required for Local Business Sites
```json
{
"@context": "https://schema.org",
"@type": "AutoRepair",
"name": "Källa Fordonservice",
"address": {
"@type": "PostalAddress",
"streetAddress": "Löttorpsvägen 31",
"addressLocality": "Löttorp",
"postalCode": "387 73",
"addressCountry": "SE"
},
"telephone": "+46485-27070",
"url": "https://kallafordon.se",
"openingHoursSpecification": [...]
}
```
### Common Schema Types
| Schema Type | Use For |
|------------|---------|
| `LocalBusiness` / `AutoRepair` | Business identity |
| `Service` | Individual service pages |
| `FAQPage` | FAQ sections |
| `BreadcrumbList` | Navigation breadcrumbs |
| `Article` | Blog/news articles |
| `Organization` | About/corporate pages |
### Plan During Project Brief
Document which schema types each page needs:
```markdown
| Page | Schema Type | Key Properties |
|------|-------------|----------------|
| Hem | LocalBusiness | name, address, phone, hours |
| Service | Service | name, description, provider |
| Nyheter article | Article | headline, datePublished, author |
```
---
## 10. Technical SEO Checklist
Capture these decisions during platform requirements:
- [ ] **XML Sitemap** — Auto-generated, includes all languages, referenced in robots.txt
- [ ] **Robots.txt** — Allows crawling, blocks admin/private pages, references sitemap
- [ ] **SSL/HTTPS** — All pages served over HTTPS
- [ ] **Mobile-first** — Responsive, passes Google Mobile-Friendly test
- [ ] **Core Web Vitals** — LCP < 2.5s, FID < 100ms, CLS < 0.1
- [ ] **Page speed** — < 3 seconds on 4G, total page weight < 3MB
- [ ] **404 handling** — Custom 404 page with navigation
- [ ] **Redirects** — 301 redirects for old URLs (if site migration)
- [ ] **Canonical URLs** — Self-referencing canonical on every page
- [ ] **Structured data** — Schema.org markup on key pages
- [ ] **hreflang** — Language alternates declared (if multilingual)
- [ ] **Favicon** — Site icon for browser tabs, bookmarks, and mobile home screen (multiple sizes: 16x16, 32x32, 180x180, 192x192)
- [ ] **Security headers** — HSTS, CSP, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy (configure at server/hosting level)
- [ ] **Image optimization** — All images < 200KB, WebP format, width/height specified, lazy loading below fold
- [ ] **CSS/JS optimization** — Minified, compressed (gzip/brotli), no render-blocking resources
---
## Output: SEO Strategy Section
When completing step-05, produce this section for the content-language document:
```markdown
## SEO Strategy
### Page-Keyword Map
| Page | URL Slug | Primary Keyword (SE) | Primary Keyword (EN) | Primary Keyword (DE) |
|------|----------|---------------------|---------------------|---------------------|
| ... | ... | ... | ... | ... |
### URL Structure
Pattern: `example.com/{slug}` (SE), `example.com/en/{slug}` (EN), `example.com/de/{slug}` (DE)
### Local SEO
- **Business Name:** ...
- **Address:** ...
- **Phone:** ...
- **Google Business Profile:** Claimed? Yes/No
- **Business Category:** ...
### Structured Data Plan
| Page | Schema Type |
|------|-------------|
| All pages | LocalBusiness (in footer/header) |
| Service pages | Service |
| Articles | Article |
### Keyword Usage Guidelines
- Page titles: Primary keyword + brand name
- H1: Primary keyword (can differ from title tag)
- Meta descriptions: Primary keyword + benefit + CTA
- Body: Natural keyword density, no stuffing
- Images: Descriptive alt text with keyword where relevant
```
---
## Related Resources
- **Meta Content Guide:** `../freya/meta-content-guide.md` — Page-level meta content specification
- **Content Language Template:** `../../templates/1-project-brief/content-language.template.md`
- **Platform Requirements:** `../../templates/1-project-brief/platform-requirements.template.md`
---
*SEO is a first-class citizen in WDS — planned at project brief, applied at page specification, verified at quality gate.*

454
_bmad/wds/data/agent-guides/saga/strategic-documentation.md Normal file
View File

@@ -0,0 +1,454 @@
# 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. Strategic Context (from Trigger Map)
**Strategic benchmark for early decisions**
Extracted from the Trigger Map to provide strategic grounding:
- Business goal
- Solution context
- Target group / persona
- Driving forces (positive + negative)
- Customer awareness progression
---
### 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. Create Product Brief
**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.*

653
_bmad/wds/data/agent-guides/saga/trigger-mapping.md Normal file
View File

@@ -0,0 +1,653 @@
# Saga's Trigger Mapping Guide
**When to load:** During Phase 2 (Trigger Mapping) or when analyzing user psychology
---
## Core Principle
**Connect business goals to user psychology through Trigger Mapping.**
Discover not just WHO your users are, but WHY they act and WHAT triggers their decisions.
---
## What is Trigger Mapping?
**Trigger Mapping is WDS's adaptation of Impact/Effect Mapping** that focuses on user psychology.
**Key differences from generic Impact Mapping:**
- ✅ Removes solutions from the map (solutions designed *against* map, not *on* it)
- ✅ Adds negative driving forces (fears, frustrations) alongside positive ones
- ✅ Focuses on smaller, targeted maps (3-4 user groups max)
- ✅ Integrates explicit prioritization for driving forces
**Result:** Longer shelf life, deeper psychology, clearer focus.
---
## The Trigger Map Structure
**Visual Flow (Left to Right):**
```
Business Goals → Product/Solution → Target Groups → Usage Goals
(Vision + (What you're (Who uses it) (Positive Drivers)
SMART building) (Negative Drivers)
Objectives)
```
**Four-Layer Architecture:**
1. **Business Goals** (Left)
- Vision statement(s) - inspirational direction
- SMART objectives - measurable targets
- Multiple goals can feed into the product
2. **Product/Solution** (Center)
- Product name and description
- What the product does
- Central hub connecting goals to users
3. **Target Groups** (Middle-Right)
- Prioritized personas (Primary 👥, Secondary 👤, etc.)
- Connected to the product
- Detailed psychological profiles
4. **Usage Goals** (Right)
- **Positive Drivers** (✅ green) - What they want to achieve
- **Negative Drivers** (❌ red) - What they want to avoid
- Separated into distinct groups per target group
- Both types are equally important for design decisions
---
## Business Goals Layer
### Generating Business Goals (Actionable Process)
**Structure Requirement: 3×3 Format**
Generate **3 visionary goals** with **3 objectives each** (sometimes 4-5 if truly necessary).
```
Goal 1: [Primary Outcome - e.g., Become more profitable]
Objective 1.1: [Measurable]
Objective 1.2: [Measurable]
Objective 1.3: [Measurable]
Goal 2: [Prerequisite - e.g., Get happier customers]
Objective 2.1: [Measurable]
Objective 2.2: [Measurable]
Objective 2.3: [Measurable]
Goal 3: [Prerequisite - e.g., Work smarter]
Objective 3.1: [Measurable]
Objective 3.2: [Measurable]
Objective 3.3: [Measurable]
```
**Step 1: Identify 3 Visionary Goals (Hierarchical Order)**
Ask: "What does 'winning' look like for this business?" Extract aspirational goals from Product Brief.
Order goals hierarchically:
1. **Primary Outcome Goal** - Ultimate business success (e.g., "Become more profitable")
2. **Prerequisite Goals** - What enables the primary goal (e.g., "Get happier customers", "Work smarter")
**Common business goals:**
- Become more profitable (financial health) - often primary
- Get happier customers (satisfaction, loyalty) - often prerequisite
- Work smarter (reduce costs, less admin) - often prerequisite
- Constant customer flow (sustainable demand) - can be primary or prerequisite
- Market leadership (trusted authority) - can be primary or prerequisite
**Step 2: Attach 3 SMART Objectives Per Goal**
For each visionary goal, identify 3 specific measurements that track progress:
```
Goal 1: Become More Profitable
Objective 1.1: Maintain 20% profit margin annually
Objective 1.2: Grow revenue 10% year-over-year
Objective 1.3: Achieve Page 1 ranking for key terms
Goal 2: Get Happier Customers
Objective 2.1: Maintain 4.8+ rating
Objective 2.2: 70%+ repeat customer rate
Objective 2.3: Service quality consistent year-round
Goal 3: Work Smarter
Objective 3.1: Reduce admin calls by 40%
Objective 3.2: 70% questions answered by website
Objective 3.3: Healthy work-life balance maintained
```
**Step 3: Verify Objective Alignment**
Each objective must align with its parent goal:
- **Profitability objectives:** Revenue, profit margin, market visibility (drives sales), pricing power
- **Customer satisfaction objectives:** Ratings, repeat rate, service quality, review sentiment
- **Operational efficiency objectives:** Time savings, cost reduction, work-life balance, automation
- **Customer flow objectives:** Discovery metrics, conversion rates, customer acquisition, seasonal consistency
❌ **Wrong alignment:** "Healthy work-life balance" under "Become More Profitable" (belongs in "Work Smarter")
✅ **Correct alignment:** "Healthy work-life balance" under "Work Smarter" (operational efficiency)
**Critical: Metrics ≠ Goals**
❌ **Don't do this:**
- "Business Goal: Reduce phone calls 40%" (metric, not aspirational)
- "Business Goal: Page 1 on Google" (tactic, not vision)
✅ **Do this:**
- "Business Goal: Work smarter → Measured by: 40% fewer calls"
- "Business Goal: Constant customer flow → Measured by: Page 1 ranking"
**Self-Check:**
- Are your goals visionary/aspirational? (exciting to achieve?)
- Do metrics support goals? (not replace them?)
- Would these goals still be relevant if tactics changed?
---
## Target Groups Layer
**Connect each target group to specific business goals they serve.**
### Example
```
Business Goal: 1,000 registered users
↓
Target Groups:
├── Independent consultants (high volume)
├── Small consulting firms (medium volume)
└── Freelance designers (adjacent market)
```
**Why connect:** Shows which users matter most for which goals.
---
## Detailed Personas
**Go beyond demographics → psychological depth**
### Wrong (Shallow)
> "Sarah, 35, consultant, lives in London"
**Why bad:** Doesn't help design decisions
---
### Right (Deep)
> **Harriet the Hairdresser**
>
> Owns a salon, 15 years experience, ambitious. Wants to be seen as the "queen of beauty" in her town - not just another hairdresser, but THE expert everyone comes to. Fears falling behind competitors who have better online presence. Frustrated by not knowing how to market herself effectively. In her salon context, she's confident. In the digital marketing context, she feels like a beginner.
**Why better:** You can design for her psychology
---
### Persona Section Structure
Each detailed persona should include these sections:
**Required Sections:**
1. **Who [Name] Is** - Context, background, life situation (2-3 sentences)
2. **Psychological Profile** - How they think, what they value, their relationship to the problem (2-3 paragraphs with **bold key traits**)
3. **Internal State** - Emotional relationship when thinking about the problem/solution (1 paragraph with **bold emotion words**)
4. **Usage Context** - When/how/why they interact with product (see template below)
5. **Relationship to Business Goals** - Explicit connection to each relevant goal with rationale
- Format: `✅ **[Goal Name]:** [How this persona serves this goal]`
**Example Structure:**
```markdown
### Lars Lojal (Lars the Loyal) — Priority 1
**Who Lars Is:**
Lars lives 45 minutes from Löttorp but has brought every vehicle to Källa for 12 years. Two cars, camper van, trailers — if it has wheels, Björn has seen it. Late 50s, works in Kalmar, summer house near Byxelkrok.
**Psychological Profile:**
Lars values **loyalty and consistency** above almost everything. Once he finds someone trustworthy, he sticks with them. He's seen other mechanics — chain workshops, "quick fix" places — and finds them impersonal and unpredictable. With Björn, Lars knows what to expect: honest diagnosis, fair price, work done when promised.
**Internal State:**
When Lars thinks about car service, he feels **calm and secure**. There's no anxiety, no "will they rip me off?" worry. Björn is like family. Lars takes pride in this relationship.
**Usage Context:**
Lars checks the website occasionally, mostly to confirm hours before calling. He already has Björn's number saved. He might visit the site to show someone else: "See, this is the place I go to." The website reinforces his choice — certifications, reviews, professionalism.
**Relationship to Business Goals:**
- ✅ **Become More Profitable:** Highest lifetime value — multiple vehicles, predictable revenue
- ✅ **Get Happier Customers:** Loyal for 12 years, refers others, never complains
- ✅ **Work Smarter:** Books ahead, minimal hand-holding, trusts recommendations
```
---
### Usage Context Template
For each persona's Usage Context section, answer:
**1. Access/Discovery:** How do they find/reach the product?
- Example: "Google search 'motorhome repair Öland'"
- Example: "Has phone number saved, checks website for hours"
**2. Emotional State:** What do they feel during usage?
- Example: "Panic mode, stressed, vulnerable"
- Example: "Calm and secure, already trusts the service"
**3. Behavior Pattern:** How do they interact?
- Example: "Scans quickly, doesn't read paragraphs, looks for trust signals"
- Example: "Reads carefully, wants to understand details"
**4. Decision Criteria:** What signals matter most?
- Example: "Capability confirmation (do you fix X?), trust signals (reviews, certifications)"
- Example: "Price transparency, availability, booking process"
**5. Success Outcome:** What gets them to take action?
- Example: "Finds phone number and calls within 30 seconds"
- Example: "Feels confident enough to book appointment"
**Full Example (Hasse the Motorhome):**
```markdown
**Usage Context:**
Hasse finds the website via Google search. He's scanning for **trust signals and capability confirmation**:
- ✅ "Husbilservice" listed → Okay, they do motorhomes
- ✅ "20+ years, Autoexperten certified" → Seems legitimate
- ✅ "4.8/5 reviews" → Other people trust them
- ✅ Phone number huge and visible → I can call NOW
He doesn't read paragraphs. He scans, checks, decides, calls. The website's job is to get him to that call within 30 seconds.
```
---
## Usage Goals vs User Goals
**Critical distinction:**
### User Goals (Life Context)
What they want in general life:
- Be a successful consultant
- Provide for family
- Be respected in industry
---
### Usage Goals (Product Context)
What they want when using your product:
- Feel prepared for client meeting
- Look professional to prospects
- Save time on formatting
**Design for usage goals, informed by user goals.**
---
## Context-Dependent Goals
**The Dubai Golf Course Example:**
A golfer using a booking form has specific **usage goals** in that moment:
- Book a tee time quickly
- See availability clearly
- Feel confident about the booking
What they do at the resort restaurant later is a **different context** with different usage goals. Don't conflate them!
**The Harriet Example:**
When booking beauty product supplier:
- **Active goal:** "Compare prices efficiently"
- **Not active:** "Feel like queen of beauty" (that's in salon context)
When marketing her salon online:
- **Active goal:** "Feel like queen of beauty"
- **Not active:** "Compare supplier prices" (different context)
**Design for the active goals in THIS usage context.**
---
## Driving Forces (The Psychology)
### Positive Driving Forces (Wishes/Desires)
**What pulls them forward?**
- Want to feel prepared
- Want to look professional
- Want to impress clients
- Want to save time
- Want to be seen as expert
**Trigger these** through your design and content.
---
### Negative Driving Forces (Fears/Frustrations)
**What pushes them away from current state?**
- Fear looking unprofessional
- Fear losing clients to competitors
- Frustrated by wasted time on formatting
- Anxious about making mistakes
- Worried about missing deadlines
**Address these** through reassurance and solutions.
---
### The Power of Both
**Same goal, different messaging:**
- Positive framing: "Feel confident and prepared"
- Negative framing: "Stop worrying about embarrassing mistakes"
Both are valid! Often negative triggers action faster (pain > pleasure).
---
### Driving Forces Pattern: WHAT + WHY + WHEN
Good driving forces follow this pattern:
**[WHAT they want/fear] + [WHY it matters] + [WHEN/CONTEXT]**
This pattern creates actionable, specific forces that directly inform design decisions.
**✅ Good Examples (Specific, contextual, actionable):**
- "Find immediate reassurance of capability within 30 seconds"
- WHAT: reassurance about capability
- WHY: stressed/urgent need
- WHEN: searching on phone in panic mode
- "Confirm specialized capability before calling"
- WHAT: capability verification
- WHY: avoid wasted call, seasonal planning
- WHEN: preparing for busy season, needs to book ahead
- "Validate loyalty choice when showing website to others"
- WHAT: validation of decision
- WHY: justify 45-minute drive, maintain identity as smart chooser
- WHEN: referring friends or colleagues
**❌ Too Vague (Not actionable):**
- "Want convenience" → Too generic, applies to everything
- "Want peace of mind" → What creates peace of mind specifically?
- "Want good experience" → What does "good" mean in this context?
- "Feel confident" → About what? When? Why?
**Test Your Driving Force:**
1. **Actionability:** Can a designer create a specific feature to address this?
2. **Psychology:** Does it reveal motivation beyond "wants it to work well"?
3. **Context:** Is it clear WHEN this force is active during product usage?
If no to any question, add more specificity using WHAT + WHY + WHEN.
**Before/After Example:**
❌ Before: "Want to feel secure"
✅ After: "Feel secure about future availability — wants reassurance that mechanic won't suddenly close or retire (when considering long-term loyalty)"
❌ Before: "Need help quickly"
✅ After: "Get back on road quickly — vacation timeline is tight, every hour stuck is lost experience (when breakdown happens mid-trip)"
---
## Prioritizing Driving Forces
**Once all driving forces are identified, prioritize using Feature Impact Analysis:**
### Scoring Method (Frequency × Intensity × Fit)
Score each driving force on three dimensions (1-5 scale):
**1. Frequency (1-5):** How often does this force matter?
- **5** = Every interaction / constant concern
- **4** = Most of the time
- **3** = Regularly but not always
- **2** = Occasional
- **1** = Rare edge case
**2. Intensity (1-5):** How strongly do they feel this?
- **5** = Critical, visceral, blocks action if not addressed
- **4** = Very important, strong emotion
- **3** = Important but manageable
- **2** = Mild concern
- **1** = Nice to have, minimal emotion
**3. Fit (1-5):** How well can the product address this?
- **5** = Perfect fit, direct solution
- **4** = Strong fit, clear approach
- **3** = Moderate fit, partial solution
- **2** = Weak fit, indirect approach
- **1** = Hard to address with this product
**Total Score = Frequency + Intensity + Fit (max 15)**
### Score Interpretation
**14-15: HIGH PRIORITY**
- Must address in core product
- Core to user success
- Strong ROI on design effort
**11-13: MEDIUM PRIORITY**
- Should address if feasible
- Significant but not critical
- Enhances experience
**8-10: LOW PRIORITY**
- Nice to have
- Limited strategic impact
- Consider for future iterations
**<8: DEPRIORITIZE**
- Minimal strategic value
- Resource drain vs. benefit
- May indicate wrong target group
### Example Scoring
```
Hasse Husbil: "Find immediate reassurance of capability"
├── Frequency: 5 (every stressed tourist in panic mode)
├── Intensity: 5 (critical to their decision to call)
├── Fit: 5 (website can show this immediately)
└── Total: 15/15 → HIGH PRIORITY
Lars Lojal: "Feel secure about future availability"
├── Frequency: 3 (occasional worry, not constant)
├── Intensity: 5 (very important to him emotionally)
├── Fit: 3 (hard to guarantee, can signal continuity)
└── Total: 11/15 → MEDIUM PRIORITY
Siv Skötsam: "See detailed pricing upfront"
├── Frequency: 4 (checks before every service)
├── Intensity: 3 (wants it but will call anyway)
├── Fit: 2 (car repair pricing is context-dependent)
└── Total: 9/15 → LOW PRIORITY
```
### Using Scores Strategically
**Prioritize Features:**
- Design for 14-15 forces first
- Group 11-13 forces into common solutions
- Defer <10 forces until core experience is solid
**Defend Decisions:**
- "This feature addresses 3 forces with 14+ scores"
- "We're deprioritizing X because it scored 7/15"
**Identify Gaps:**
- High-intensity forces with low fit = product limitation
- High-frequency, low-intensity = table stakes (must have, but not differentiator)
- Low-frequency, high-intensity = edge case (support via other channels)
---
## Customer Awareness Integration
**Every scenario should move users through awareness stages:**
```
Trigger Map shows:
└── User + Driving Forces
Scenario adds:
├── Starting Awareness: Problem Aware (knows proposals are weak)
└── Target Awareness: Product Aware (knows our solution helps)
```
**Example:**
- **Start:** "I know my proposals lose clients" (Problem Aware)
- **Through scenario:** Experience our solution working
- **End:** "This tool makes my proposals professional" (Product Aware)
---
## Common Trigger Mapping Mistakes
### ❌ Too Many Target Groups
"Let's map 10 different user types..."
**Why bad:** Dilutes focus, overwhelming, unused
**Instead:** 3-4 groups max, deeply understood
---
### ❌ Shallow Personas
"John, 32, works in consulting..."
**Why bad:** Doesn't inform design
**Instead:** Deep psychology, usage context, active goals
---
### ❌ Only Positive Forces
"Users want to save time and be efficient..."
**Why bad:** Missing powerful negative triggers
**Instead:** Positive AND negative (fears drive action!)
---
### ❌ Solutions on the Map
"They need a template library and e-signature..."
**Why bad:** Locks in solutions too early, map ages quickly
**Instead:** Map psychology, design solutions against it
---
### ❌ Generic Goals
"Want a better experience..."
**Why bad:** Too vague to design for
**Instead:** Specific, contextual: "Want to feel prepared before client meeting"
---
## Trigger Map → Design Context
**For a specific design task, extract the relevant slice:**
```
Trigger Map (Comprehensive):
├── 3 business goals
├── 4 target groups
├── 12 detailed personas
└── 40+ driving forces
Design Context (Focused):
├── 1 business goal
├── 1 persona
├── 1 solution context
└── 3-5 key driving forces
```
**The focused context is the "working copy" for a specific design task.**
---
## Visual Mermaid Diagrams
**Create visual trigger maps using Mermaid syntax:**
```mermaid
graph TD
BG1[1000 Users] --> TG1[Independent Consultants]
BG1 --> TG2[Small Firms]
TG1 --> P1[Harriet - Solo Consultant]
P1 --> DF1[+ Feel professional]
P1 --> DF2[+ Save time]
P1 --> DF3[- Fear losing clients]
P1 --> DF4[- Frustrated by formatting]
```
**See:** `../../workflows/2-trigger-mapping/mermaid-diagram/`
---
## Workshop Process
**Trigger Mapping is collaborative:**
1. **Define business goals** (Vision + SMART)
2. **Identify target groups** (connect to goals)
3. **Create personas** (psychological depth)
4. **Discover driving forces** (positive + negative)
5. **Prioritize forces** (Feature Impact Analysis)
6. **Generate visual map** (Mermaid diagram)
7. **Document findings** (structured markdown)
**See:** `../../workflows/2-trigger-mapping/workshops/`
---
## When to Update Trigger Map
**Trigger Maps evolve:**
- ✅ New user research reveals different psychology
- ✅ Business goals change
- ✅ New target groups emerge
- ✅ Priorities shift based on data
**Process:**
1. Create new version (v2)
2. Document what changed and why
3. Review impact on active design work
4. Keep old version for reference
---
## Related Resources
- **Phase 2 Workflow:** `../../workflows/2-trigger-mapping/`
- **Impact/Effect Mapping Model:** `../../docs/models/impact-effect-mapping.md`
- **Trigger Mapping Guide:** `../../docs/method/phase-2-trigger-mapping-guide.md`
- **Customer Awareness Cycle:** `../../docs/models/customer-awareness-cycle.md`
- **Feature Impact Analysis:** Prioritization method based on Impact Mapping
---
*Trigger Mapping connects business goals to user psychology. It's the strategic foundation that makes design purposeful.*

172
_bmad/wds/data/agent-guides/saga/working-with-existing-materials.md Normal file
View File

@@ -0,0 +1,172 @@
# Working with Existing Materials
**Purpose:** Guide for naturally incorporating existing materials into conversational PB workflow.
---
## Core Principles
1. **Reference, don't re-ask** - Build on documented work
2. **Validate currency** - "Is this still accurate?"
3. **Focus on gaps** - What's missing or needs refinement?
4. **Document refinement** - Capture UPDATE conversation, not just creation
5. **Stay casual** - No judgment about what exists or doesn't
---
## Checking for Materials
**Phase 0 asks:** "Do you have existing materials?" (website, brief, guidelines, research)
**Stored in outline:**
```yaml
existing_materials:
has_materials: true/false
website: "[URL]"
previous_brief: "[path]"
brand_guidelines: "[path]"
research: "[path]"
context_notes: "[brief notes]"
```
**If materials exist:** Read them before starting PB steps
---
## Adaptation Pattern
### Opening Adaptation
**Without materials:**
> "Let's start with vision. What are you envisioning?"
**With materials:**
> "I see you mentioned [reference from materials]. Let's build on that - tell me more."
### Follow-Up Patterns
- **Validate:** "You wrote X - is that still accurate?"
- **Fill gaps:** "Your brief mentions Y, but I'm curious about Z..."
- **Refine:** "When you said X, did you mean [interpretation]?"
- **Update:** "Has your thinking evolved since you wrote this?"
---
## Step-by-Step Application
**Apply to all conversational steps** (2, 3, 5, 7, 7a, 8, 9, 10, 11, 12):
| Step | No Materials | With Materials |
|------|-------------|----------------|
| Vision (2) | "What are you envisioning?" | "You mentioned [vision]. Tell me more." |
| Positioning (3) | "Let's explore positioning." | "Your brief positions this as [quote]. Still accurate?" |
| Users (7) | "Who are ideal users?" | "You described [archetypes]. Still primary users?" |
| Concept (7a) | "What's the core concept?" | "I see [concept from materials]. Tell me more about that principle." |
| Success (8) | "What does success look like?" | "You mentioned success means [quote]. Still the goal?" |
**Pattern:** Reference existing → Validate → Build on it
---
## Dialog Documentation
When materials exist, capture:
1. **What existed:** Quote/summarize existing material
2. **Validation:** User's response to "Is this still accurate?"
3. **Refinement:** What changed, added, or clarified
4. **Why:** Rationale for changes
5. **Synthesis:** Updated version (old + new integrated)
**Template:**
```markdown
**Existing context:** [What was documented]
**Opening:** "I see [reference]. [Question]"
**User response:** [Confirmed/refined/changed]
**Key exchanges:**
- [Exploration]
- [Gaps filled]
- [Evolution]
**Reflection checkpoint:**
"Building on your earlier work: [synthesis].
Keeps [solid parts], adds [new], refines [changed].
Does that capture it?"
**User confirmation:** [Confirmed / Corrected]
**Final:** [Updated artifact]
```
---
## Common Scenarios
**Scenario: Previous brief exists**
1. Read it thoroughly
2. Identify solid vs gaps/unclear
3. Open: "I read your brief. [Strong points] captured well. Questions about [gaps]."
4. Explore gaps conversationally
5. Dialog: what was there + what we added + why
**Scenario: Existing website**
1. Review site (if URL in materials)
2. Note current positioning/tone/UX
3. Reference: "I looked at your site. It positions you as [observation]. Still the direction?"
4. Use as baseline for "what's changing?"
**Scenario: Brand guidelines exist**
1. Read guidelines (voice, values, identity)
2. Reference when discussing tone: "Your guidelines describe tone as [quote]. Match exactly or evolve?"
3. Don't re-ask defined things (colors, values)
4. Focus on how brand translates to this project
**Scenario: Research exists**
1. Review findings
2. Reference insights: "Your research showed [finding]. Great insight for..."
3. Validate currency: "Is this still what you hear from customers?"
---
## What NOT to Do
❌ Ignore existing materials (if outline says they exist)
❌ Make users repeat documented work
❌ Assume everything is still current (validate!)
❌ Judge quality of existing work
❌ Create separate "refinement workflow" (same conversational pattern, just adapt openings)
---
## Benefits
✅ Efficiency - Don't re-explore documented areas
✅ Continuity - Build on previous work
✅ Respect - Acknowledge existing thinking
✅ Focus - Spend time on gaps/unclear areas
✅ Natural flow - Same pattern, context-aware
✅ Rich dialog - Captures refinement, not just creation
---
## Quick Reference
**Check:** `existing_materials.has_materials` in outline
**If true:**
1. Read materials before starting PB
2. Adapt openings to reference what exists
3. Validate currency with each step
4. Fill gaps conversationally
5. Document: old + new + why
**Dialog pattern:** Existing → Validate → Refine → Synthesize → Confirm
---
**Remember:** Not a separate workflow - same conversational pattern, just context-aware.
If materials exist, read and adapt. If not, explore from scratch. Either way, natural conversation.