siesa-agents 2.1.90 → 2.1.91

package/siesa-agents/wds/data/agent-guides/freya/specification-quality.md

@@ -0,0 +1,262 @@
+# Freya's Specification Quality Guide
+
+**When to load:** Before creating any page spec, component definition, or scenario documentation
+
+---
+
+## Core Principle
+
+**If I can't explain it logically, it's not ready to specify.**
+
+Gaps in logic become bugs in code. Clear specifications = confident implementation.
+
+---
+
+## The Logical Explanation Test
+
+Before you write any specification, ask:
+
+**"Can I explain WHY this exists and HOW it works without hand-waving?"**
+
+- ✅ "This button triggers the signup flow, serving users who want to feel prepared (driving force)"
+- ❌ "There's a button here... because users need it?"
+
+**If you can't explain it clearly, stop and think deeper.**
+
+---
+
+## Area Label Structure & Hierarchy
+
+**Area Labels follow a consistent hierarchical pattern to identify UI locations across sketch, specification, and code.**
+
+### Structural Area Labels (Containers)
+These define the page architecture and visual grouping:
+
+- `{page-name}-page` - Top-level page wrapper
+- `{page-name}-header` - Header section container
+- `{page-name}-main` - Main content area
+- `{page-name}-form` - Form element wrapper
+- `{page-name}-{section}-section` - Section containers
+- `{page-name}-{section}-header-bar` - Section header bars
+
+**Purpose:** Organize page structure, enable Figma layer naming (via aria-label), support testing selectors (via id attribute)
+
+### Interactive Area Labels (Components)
+These identify specific interactive elements:
+
+- `{page-name}-{section}-{element}` - Standard pattern
+- `{page-name}-input-{field}` - Form inputs
+- `{page-name}-button-{action}` - Buttons
+- `{page-name}-error-{field}` - Error messages
+
+**Purpose:** Enable user interaction, form validation, accessibility, and location tracking across design and code
+
+**Note:** Area Labels become both `id` and `aria-label` attributes in HTML implementation.
+
+### Purpose-Based Naming
+
+**Name components by FUNCTION, not CONTENT**
+
+### Good (Function)
+- `hero-headline` - Describes its role on the page
+- `primary-cta` - Describes its function in the flow
+- `feature-benefit-section` - Describes what it does
+- `form-validation-error` - Describes when it appears
+
+### Bad (Content)
+- `welcome-message` - What if the message changes?
+- `blue-button` - What if we change colors?
+- `first-paragraph` - Position isn't purpose
+- `email-error-text` - Too specific, not reusable
+
+**Why this matters:**
+- Content changes, function rarely does
+- Makes specs maintainable
+- Helps developers understand intent
+- Enables component reuse
+- Supports Figma html.to.design layer naming
+
+---
+
+## Clear Component Purpose
+
+**Every component needs a clear job description:**
+
+### Template
+```markdown
+### [Component Name]
+
+**Purpose:** [What job does this do?]
+**Triggers:** [What user action/state causes this?]
+**Serves:** [Which driving force or goal?]
+**Success:** [How do we know it worked?]
+```
+
+### Example
+```markdown
+### Primary CTA Button
+
+**Purpose:** Initiate account creation flow
+**Triggers:** User clicks after reading value proposition
+**Serves:** User's desire to "feel prepared" (positive driving force)
+**Success:** User enters email and moves to step 2
+```
+
+---
+
+## Section-First Workflow
+
+**Understand the WHOLE before detailing the PARTS**
+
+### Wrong Approach (Bottom-Up)
+1. Design individual components
+2. Try to arrange them into sections
+3. Hope the page makes sense
+4. Realize it doesn't flow logically
+5. Start over
+
+### Right Approach (Top-Down)
+1. **Define structural containers** - Page, header, main, sections
+2. **Assign structural Area Labels** - `{page}-page`, `{page}-header`, etc.
+3. **Identify page sections** - What major areas exist?
+4. **Define section purposes** - Why does each section exist?
+5. **Confirm flow logic** - Does the story make sense?
+6. **Detail each section** - Now design components
+7. **Specify components** - With clear purpose and context
+8. **Assign interactive Area Labels** - `{page}-{section}-{element}`
+
+**Result:** Logical flow, no gaps, confident specifications, complete Area Label coverage
+
+### Area Label Coverage Checklist
+- [ ] Page container (`{page}-page`)
+- [ ] Header section (`{page}-header`)
+- [ ] Main content area (`{page}-main`)
+- [ ] Form container if applicable (`{page}-form`)
+- [ ] Section containers (`{page}-{section}-section`)
+- [ ] Section header bars if visible (`{page}-{section}-header-bar`)
+- [ ] All interactive elements (`{page}-{section}-{element}`)
+
+---
+
+## Multi-Language from the Start
+
+**Never design in one language only**
+
+### Grouped Translations
+```markdown
+#### Hero Headline
+
+**Content:**
+- EN: "Stop losing clients to poor proposals"
+- SE: "Sluta förlora kunder på dåliga offerter"
+- NO: "Slutt å miste kunder på dårlige tilbud"
+
+**Purpose:** Hook Problem Aware users by validating frustration
+```
+
+### Why This Matters
+- Prevents "English-first" bias
+- Reveals translation issues early
+- Shows if message works across cultures
+- Keeps translations coherent (grouped by component)
+
+---
+
+## Specification Quality Checklist
+
+Before marking a spec "complete":
+
+### Core Quality
+- [ ] **Logical Explanation** - Can I explain WHY and HOW?
+- [ ] **Purpose-Based Names** - Named by function, not content?
+- [ ] **Clear Purpose** - Every component has a job description?
+- [ ] **Section-First** - Whole page flows logically?
+- [ ] **Multi-Language** - All product languages included?
+- [ ] **No Hand-Waving** - No "probably" or "maybe" or "users will figure it out"?
+
+### Area Labels
+- [ ] **Structural Area Labels** - Page, header, main, sections all have labels?
+- [ ] **Interactive Area Labels** - All buttons, inputs, links have labels?
+- [ ] **Area Label Hierarchy** - Labels follow `{page}-{section}-{element}` pattern?
+- [ ] **Figma-Ready** - Area Labels support html.to.design layer naming?
+
+### Accessibility
+- [ ] **ARIA Labels** - All interactive elements have aria-label attributes?
+- [ ] **Alt Text** - All images have descriptive alt attributes?
+- [ ] **Form Labels** - All inputs have associated labels?
+- [ ] **Keyboard Navigation** - Tab order and focus management documented?
+- [ ] **Screen Reader Support** - Semantic HTML and ARIA attributes specified?
+- [ ] **Color Contrast** - WCAG AA compliance (4.5:1 for text)?
+- [ ] **Error Announcements** - Error messages accessible to screen readers?
+- [ ] **Heading Hierarchy** - Logical H1-H6 structure documented?
+
+### SEO (Public Pages)
+- [ ] **H1 Present** - Exactly one H1 on the page, contains primary keyword?
+- [ ] **Heading Hierarchy** - Logical H1 → H2 → H3, no skipped levels?
+- [ ] **URL Slug** - Defined, keyword-rich, matches project brief keyword map?
+- [ ] **Primary Keyword** - Identified and placed in H1, title tag, meta description?
+- [ ] **Meta Title** - ≤ 60 chars, includes primary keyword + brand?
+- [ ] **Meta Description** - 150-160 chars, includes keyword + CTA?
+- [ ] **Image Alt Text** - All images have descriptive alt text in all languages?
+- [ ] **Internal Links** - At least 2 links to other pages on the site?
+- [ ] **Structured Data** - Schema type specified per project brief plan?
+
+### Content Completeness
+- [ ] **All Text Defined** - No placeholder content?
+- [ ] **Error Messages** - All error states have messages in all languages?
+- [ ] **Success Messages** - Confirmation messages defined?
+- [ ] **Empty States** - Messages for no-data scenarios?
+- [ ] **Loading States** - Loading indicators and messages?
+- [ ] **Meta Content** - Page title and meta description for public pages?
+- [ ] **Social Sharing** - Social media title, description, and image for public pages?
+
+### Implementation Ready
+- [ ] **Developer-Ready** - Could someone build this confidently?
+- [ ] **Component References** - All design system components linked?
+- [ ] **API Endpoints** - Data requirements documented?
+- [ ] **Validation Rules** - Form validation clearly specified?
+
+---
+
+## Red Flags (Stop and Rethink)
+
+🚩 **Vague language:** "Something here to help users understand..."  
+🚩 **Content-based names:** "blue-box", "top-paragraph"  
+🚩 **Missing purpose:** "There's a button... because buttons are good?"  
+🚩 **Illogical flow:** "This section comes after that one... because?"  
+🚩 **English-only:** "We'll translate later..."  
+🚩 **Gaps in logic:** "Users will just know what to do here"  
+🚩 **Missing accessibility:** "We'll add ARIA labels during development..."  
+🚩 **No alt text:** Images without descriptive alternatives
+🚩 **Unlabeled inputs:** Form fields without associated labels
+🚩 **No SEO section:** Public page without URL slug, keywords, or meta content
+
+**When you spot these, pause and dig deeper.**
+
+---
+
+## The Developer Trust Test
+
+**Imagine handing your spec to a developer who:**
+- Has never seen your sketches
+- Doesn't know the business context
+- Speaks a different language
+- Lives in a different timezone
+
+**Could they build this confidently?**
+
+- ✅ Yes → Good spec
+- ❌ No → More work needed
+
+---
+
+## Related Resources
+
+- **File Naming:** `../../workflows/00-system/FILE-NAMING-CONVENTIONS.md`
+- **Language Config:** `../../workflows/00-system/language-configuration-guide.md`
+- **Page Spec Template:** `../../workflows/wds-4-ux-design/templates/page-specification.template.md`
+
+---
+
+*Quality specifications are the foundation of confident implementation.*
+

package/siesa-agents/wds/data/agent-guides/freya/strategic-design.md

@@ -0,0 +1,116 @@
+# Freya's Strategic Design Guide
+
+**When to load:** Before designing any page, component, or user flow
+
+---
+
+## Core Principle
+
+**Every design decision connects to strategy.** Never design in a vacuum.
+
+---
+
+## Before You Design Anything
+
+### 1. Load Strategic Context
+
+**Ask yourself:**
+- What's in the Trigger Map for this page/scenario?
+- What does the Product Brief say?
+
+**If missing:** Suggest creating one first. Design without strategy is decoration.
+
+---
+
+### 2. Connect to Business Goals
+
+**Every major design choice should answer:**
+- Which business goal does this serve?
+- How does this move the needle on our success metrics?
+
+**Example:**
+- ❌ "Let's make this button blue because it's pretty"
+- ✅ "This CTA should be prominent because it serves the 'Convert Problem Aware users' goal"
+
+---
+
+### 3. Identify User Driving Forces
+
+**From the Trigger Map, ask:**
+- What positive driving forces should we trigger? (wishes, desires, aspirations)
+- What negative driving forces should we address? (fears, frustrations, anxieties)
+
+**Example:**
+- User wants to "feel like an industry expert"
+- User fears "looking unprofessional to clients"
+- Design should make them feel capable, not overwhelmed
+
+---
+
+### 4. Customer Awareness Stage
+
+**Where are users in their journey?**
+
+1. **Unaware** - Don't know they have a problem → Educate on problem
+2. **Problem Aware** - Know the problem, not solutions → Show there are solutions
+3. **Solution Aware** - Know solutions exist → Show why yours is different
+4. **Product Aware** - Know your product → Remove friction, show proof
+5. **Most Aware** - Ready to buy/use → Make it easy, reinforce decision
+
+**Design implications:**
+- Unaware users need more context, education
+- Most Aware users need less explanation, more action
+
+---
+
+### 5. Content Hierarchy (Golden Circle)
+
+**Structure content as:** WHY → HOW → WHAT
+
+- **WHY** - Purpose, benefit, emotional hook (first)
+- **HOW** - Process, approach, differentiation (second)
+- **WHAT** - Features, specifics, details (last)
+
+**Example:**
+```
+Hero Section:
+├── Headline (WHY): "Stop losing clients to competitors with better proposals"
+├── Subhead (HOW): "Create stunning proposals in minutes with AI-powered templates"
+└── Features (WHAT): "10,000+ templates, Smart pricing, E-signatures"
+```
+
+---
+
+## Strategic Design Checklist
+
+Before finalizing any design:
+
+- [ ] **Trigger Map** - Which driving force does this serve?
+- [ ] **Business Goal** - How does this support our objectives?
+- [ ] **Customer Awareness** - Appropriate for their awareness stage?
+- [ ] **Golden Circle** - WHY before HOW before WHAT?
+- [ ] **Logical Explanation** - Can I defend this decision strategically?
+
+---
+
+## When You're Stuck
+
+**If you can't connect a design choice to strategy:**
+1. It might not be needed (remove it)
+2. You need more strategic context (ask for Trigger Map)
+3. There's a better alternative (explore options)
+
+**Never guess.** Always design with intent.
+
+---
+
+## Related Resources
+
+- **Trigger Mapping:** `../../docs/method/phase-wds-2-trigger-mapping-guide.md`
+- **Customer Awareness:** `../../docs/models/customer-awareness-cycle.md`
+- **Golden Circle:** `../../docs/models/golden-circle.md`
+
+---
+
+*Strategic design is what makes WDS different. Every pixel has a purpose.*
+

package/siesa-agents/wds/data/agent-guides/saga/content-structure-principles.md

@@ -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.*