siesa-agents 2.1.89 → 2.1.91

package/siesa-agents/wds/data/agent-guides/freya/agentic-development.md

@@ -0,0 +1,223 @@
+# Freya's Agentic Development Guide
+
+**When to load:** When implementing features, building prototypes, or fixing bugs through structured development
+
+> **Note:** Agent dialogs have been replaced by the Design Log system. Use `_progress/00-design-log.md` for state tracking and `_progress/agent-experiences/` for session insights.
+
+---
+
+## Core Principle
+
+**Agentic Development builds incrementally with full traceability via the design log.**
+
+The design log bridges the gap between specifications and working code. Each step is self-contained, allowing fresh context while maintaining continuity.
+
+---
+
+## What is Agentic Development?
+
+Agentic Development is a **workflow approach** that produces various outputs:
+
+| Output Type | Description | When to Use |
+|-------------|-------------|-------------|
+| **Interactive Prototypes** | HTML prototypes that let users FEEL the design | Validating UX before production |
+| **Prototype Implementation** | Building features from specifications | Feature development |
+| **Bug Fixes** | Structured debugging and fixing | Issue resolution |
+| **Design Exploration** | Exploring visual/UX directions | Creative iteration |
+
+**Key Insight:** By structuring work with a design log and experience records, we create:
+- **Isolation** — Each step can run in a fresh context
+- **Traceability** — Clear record of what was planned and executed
+- **Replayability** — Instructions can be rerun if needed
+- **Handoff** — Different agents or humans can continue the work
+
+---
+
+## Agent Startup Protocol
+
+**When awakened, always check the design log:**
+
+```
+1. Read: {output_folder}/_progress/00-design-log.md
+2. Check Current and Backlog sections for:
+   - Items in progress
+   - Items ready to start
+3. Present current state to user
+```
+
+This ensures no captured work is forgotten.
+
+---
+
+## The Bridge Role
+
+The design log bridges **specifications** and **development**:
+
+```
+┌─────────────────────┐         ┌─────────────────────┐         ┌─────────────────────┐
+│   SPECIFICATION     │         │   DESIGN LOG        │         │   DEVELOPMENT       │
+│                     │         │                     │         │                     │
+│ • What to build     │────────▶│ • What's in scope   │────────▶│ • How to build      │
+│ • Object IDs        │         │ • Current/Backlog   │         │ • Code files        │
+│ • Requirements      │         │ • Traceability      │         │ • Components        │
+│ • Translations      │         │ • Progress tracking │         │ • Tests             │
+└─────────────────────┘         └─────────────────────┘         └─────────────────────┘
+     Single Source                   Navigation                    Implementation
+      of Truth                         Layer
+```
+
+**The specification is the single source of truth.** The design log does not duplicate spec content — it maps implementation tasks to spec sections via Object IDs.
+
+---
+
+## Progress Folder Structure
+
+```
+{output_folder}/_progress/
+├── 00-design-log.md                               ← Main state tracking
+└── agent-experiences/
+    ├── {DATE}-{agent}-{feature-name}.md            ← Session insights
+    └── ...
+```
+
+---
+
+## Feedback Protocol
+
+During implementation, classify and handle feedback naturally:
+
+| Type | What It Is | When to Address |
+|------|------------|-----------------|
+| **Bug/Issue** | Something broken or not working as expected | Now — iterate until fixed |
+| **Quick Adjustment** | Small tweak to current work | Now — implement immediately |
+| **Addition** | New requirement that fits current scope | Later step — add to plan |
+| **Change Request** | Outside current dialog scope | Future session — document in Change Requests |
+
+**Response Pattern:**
+1. **Classify** — Note what kind of feedback this is
+2. **Timing** — State when it should be addressed
+3. **Confirm** — For additions and change requests, confirm before proceeding
+4. **Execute** — Implement or document as appropriate
+
+---
+
+## Inline Testing
+
+**The agent tests its own work before presenting it to the user.**
+
+During agentic development, use Puppeteer to verify measurable criteria after each implementation step. This ensures the user only evaluates qualitative aspects (feel, clarity, hierarchy) rather than checking things the agent can measure.
+
+**Key rules:**
+
+1. **Verify before presenting** — After implementing a section, open the page with Puppeteer and check all measurable criteria
+2. **Narrate findings** — Use ✓/✗ marks with actual vs expected values
+3. **Fix before showing** — Never present with known measurable failures
+4. **Capture baselines** — Before modifying existing features, document current state with Puppeteer
+5. **Split test plans** — Story files divide criteria into agent-verifiable and user-evaluable
+
+**Responsibility split:**
+- **Agent handles:** Text content, colors, dimensions, touch targets, error states, visibility, state transitions
+- **Human handles:** Flow feel, visual hierarchy, user understanding, overall consistency
+
+**Full methodology:** `workflows/wds-4-ux-design/agentic-development/guides/INLINE-TESTING-GUIDE.md`
+
+---
+
+## Interactive Prototypes (Output Type)
+
+Interactive Prototypes are **one output** of Agentic Development.
+
+### Why HTML Prototypes?
+
+**Static Specs Can't Show:**
+- How it FEELS to interact
+- Where users get confused
+- What's missing in the flow
+- If the pacing feels right
+
+**HTML Prototypes Reveal:**
+- Interaction feels natural or awkward
+- Information appears when needed
+- Flow has logical gaps
+- Users understand next steps
+
+### Fidelity Levels
+
+| Level | Focus | Use When |
+|-------|-------|----------|
+| **Wireframe** | Information architecture | Testing flow logic only |
+| **Interactive** | User experience | Validating UX (standard) |
+| **Design System** | Component-based | Phase 5 enabled |
+
+### Prototype vs Production
+
+**Prototypes ARE:**
+- Thinking tools
+- Communication tools
+- Validation tools
+- Specification supplements
+
+**Prototypes are NOT:**
+- Production code
+- Pixel-perfect mockups
+- Final design
+
+---
+
+## Prototype Implementation (Output Type)
+
+Building features from specifications through structured dialog steps.
+
+### Step File Structure
+
+Each step links to specifications (doesn't duplicate):
+
+```markdown
+## Object ID Implementation Map
+
+| Object ID | Spec Section | Lines |
+|-----------|--------------|-------|
+| `booking-detail-header` | Drawer Header | L149-L158 |
+| `booking-detail-close` | Close Button | L159-L168 |
+```
+
+### Implementation Checklist Pattern
+
+For each Object ID:
+1. **Read** — Load the spec section
+2. **Implement** — Build to match spec
+3. **Verify (Puppeteer)** — Open in browser, check measurable criteria with ✓/✗ narration
+4. **Fix** — Resolve any mismatches before presenting to user
+
+---
+
+## Best Practices
+
+### Single Source of Truth
+- **Never duplicate spec content** — Link to spec sections with line numbers
+- **Object IDs are the contract** — Every implementation maps to an Object ID
+- **Spec changes update the spec** — Not the dialog or step files
+
+### Design Log
+- **Be thorough in Setup Context** — Assume zero prior knowledge
+- **Include file paths** — Always use absolute or project-relative paths
+- **Track progress** — Update the design log after each step
+
+### Execution
+- **Read spec first** — Before implementing any Object ID
+- **Fresh context is fine** — Steps are designed to work in isolation
+- **Update as you go** — Don't wait to update progress
+- **Capture discoveries** — Note spec changes or issues found
+
+---
+
+## Related Resources
+
+- **Design Log:** `{output_folder}/_progress/00-design-log.md`
+- **Agent Experiences:** `{output_folder}/_progress/agent-experiences/`
+- **Phase 4 UX Design:** `workflows/wds-4-ux-design/workflow.md`
+- **Inline Testing Guide:** `workflows/wds-5-agentic-development/guides/INLINE-TESTING-GUIDE.md`
+
+---
+
+*Build incrementally. Document thoroughly. Let users FEEL the design before committing to production.*

package/siesa-agents/wds/data/agent-guides/freya/content-creation.md

@@ -0,0 +1,270 @@
+# Freya's Content Creation Guide
+
+**When to load:** Before creating strategic content (headlines, features, text sections)
+
+---
+
+## Core Principle
+
+**Content is strategic, not decorative.** Every word should trigger user psychology and serve business goals.
+
+---
+
+## Content Creation Workshop
+
+**Use the Content Creation Workshop for:**
+- ✅ Headlines and subheadlines
+- ✅ Hero sections and value propositions
+- ✅ Feature descriptions and benefits
+- ✅ Call-to-action messaging
+- ✅ Page sections (entire blocks)
+
+**NOT for:**
+- ❌ Field labels ("Email", "Password")
+- ❌ Button text ("Submit", "Cancel")
+- ❌ Error messages ("Invalid email format")
+- ❌ UI microcopy (that's Tone of Voice territory)
+
+---
+
+## When to Suggest the Workshop
+
+### Signs User Needs It
+- Creating content without strategic context
+- Asking "What should this headline say?"
+- Struggling with messaging
+- Content feels generic or weak
+- Multiple content pieces to create
+
+### How to Suggest (Natural, Not Pushy)
+> "This headline is important - it hooks Problem Aware users. Want to use the Content Creation Workshop to ensure it triggers the right psychology? Takes 10-15 minutes but makes content way more effective."
+
+**Let them decide.** Some users prefer quick mode, others want depth.
+
+---
+
+## Quick Mode vs Workshop Mode
+
+### Quick Mode
+**When:**
+- Simple, straightforward content
+- User is experienced with WDS
+- Context is crystal clear
+- Time is tight
+
+**Process:**
+1. Load Trigger Map for context
+2. Consider Customer Awareness
+3. Apply Golden Circle (WHY → HOW → WHAT)
+4. Generate options
+5. Explain rationale
+
+---
+
+### Workshop Mode
+**When:**
+- Critical content (hero, main CTA)
+- User wants strategic depth
+- Multiple frameworks apply
+- Content is complex
+
+**Process:**
+Load: `skill:wds-6-asset-generation`
+
+**6-Step Framework:**
+1. Define purpose & success criteria
+2. Load Trigger Map context
+3. Apply Customer Awareness strategy
+4. Filter with Action Mapping
+5. Frame with Badass Users
+6. Structure with Golden Circle
+7. Generate content
+
+---
+
+## The 6-Model Framework
+
+### 1. Content Purpose
+**"What job does this content do?"**
+
+- Convince Problem Aware users that speed matters
+- Reassure anxious users about security
+- Trigger desire to feel professional
+
+**Must be specific and measurable.**
+
+---
+
+### 2. Trigger Map
+**Strategic foundation**
+
+- Business Goal: What are we trying to achieve?
+- User: Who are we serving?
+- Driving Forces: What motivates them? (positive + negative)
+- Solution: What triggers these forces?
+
+**Informs** which psychology to trigger.
+
+---
+
+### 3. Customer Awareness Cycle
+**Content strategy - language & focus**
+
+Where user is → Where we want them:
+
+- **Unaware → Problem Aware:** Educate on problem
+- **Problem → Solution Aware:** Show solutions exist
+- **Solution → Product Aware:** Differentiate your solution
+- **Product → Most Aware:** Remove friction, show proof
+- **Most Aware:** Maintain, deepen relationship
+
+**Determines** what language they can understand.
+
+---
+
+### 4. Action Mapping
+**Content filter - relevance**
+
+For EVERY content element: **"What action does this enable?"**
+
+- ❌ "Nice to know" → Remove it
+- ✅ "Need to do" → Keep and strengthen
+
+**Strips** fluff, focuses on user actions.
+
+---
+
+### 5. Kathy Sierra Badass Users
+**Content tone & frame**
+
+Frame content around user becoming capable:
+
+- Show transformation (current → badass state)
+- Reduce cognitive load
+- Create "aha moments"
+- Make them feel smart, not overwhelmed
+
+**Makes** users feel empowered, not intimidated.
+
+---
+
+### 6. Golden Circle
+**Structural order**
+
+Always structure: **WHY → HOW → WHAT**
+
+```
+Headline (WHY): Stop losing clients to slow proposals
+Subhead (HOW): AI-powered templates deliver in minutes
+Features (WHAT): 10K templates, smart pricing, e-signatures
+```
+
+**Gives** content persuasive flow.
+
+---
+
+## How the Models Work Together
+
+**Think of them as lenses, not sequential steps:**
+
+1. **Trigger Map** = Which driving force to trigger?
+2. **Customer Awareness** = What language can they understand?
+3. **Golden Circle** = In what order should I present?
+4. **Action Mapping** = Is this enabling action?
+5. **Badass Users** = Does this make them feel capable?
+6. **Content Purpose** = Does it achieve its job?
+
+**AI synthesizes all six** to produce optimal content.
+
+---
+
+## Content Purpose Examples
+
+### Good (Specific & Measurable)
+- "Convince Problem Aware users that proposal speed matters more than perfection"
+- "Reassure Product Aware users about data security concerns"
+- "Trigger Solution Aware users' desire to feel like industry experts"
+
+### Bad (Vague)
+- "Make users want the product"
+- "Explain features"
+- "Sound professional"
+
+**Test:** Can someone else determine if the content succeeded?
+
+---
+
+## Model Priority Matrix
+
+**Different content types prioritize different models:**
+
+### Landing Page Hero
+- Customer Awareness: ⭐⭐⭐
+- Golden Circle: ⭐⭐⭐
+- Badass Users: ⭐⭐
+- Action Mapping: ⭐
+- Trigger Map: Always loaded
+- Content Purpose: Always defined
+
+### Feature Description
+- Action Mapping: ⭐⭐⭐
+- Badass Users: ⭐⭐⭐
+- Customer Awareness: ⭐⭐
+- Golden Circle: ⭐
+- Trigger Map: Always loaded
+- Content Purpose: Always defined
+
+### Error Messages
+**Don't use workshop** - Use Tone of Voice instead
+
+---
+
+## Tone of Voice vs Strategic Content
+
+### Tone of Voice (Product-Wide)
+- Field labels: "Email address"
+- Button text: "Get started"
+- Error messages: "Please enter a valid email"
+- Success messages: "Profile updated!"
+
+**Defined once** in Product Brief, applied everywhere.
+
+---
+
+### Strategic Content (Context-Specific)
+- Headlines: "Stop losing clients to slow proposals"
+- Value propositions: "AI-powered templates that close deals faster"
+- Feature benefits: "Create stunning proposals in minutes, not hours"
+
+**Created with workshop**, varies by context.
+
+---
+
+## Quick Reference
+
+**Before creating any strategic content:**
+
+1. **Define purpose** - What job does this do?
+2. **Load Trigger Map** - Which driving forces?
+3. **Check awareness** - Where are users?
+4. **Apply Golden Circle** - WHY → HOW → WHAT
+5. **Filter with Action** - Does it enable action?
+6. **Frame as empowering** - Make them feel capable
+7. **Validate** - Does it achieve its purpose?
+
+---
+
+## Related Resources
+
+- **Asset Generation:** `skill:wds-6-asset-generation`
+- **Content Purpose Guide:** `../../docs/method/content-purpose-guide.md`
+- **Tone of Voice Guide:** `../../docs/method/tone-of-voice-guide.md`
+- **Customer Awareness Cycle:** `../../docs/models/customer-awareness-cycle.md`
+- **Golden Circle:** `../../docs/models/golden-circle.md`
+- **Action Mapping:** `../../docs/models/action-mapping.md`
+- **Kathy Sierra Badass Users:** `../../docs/models/kathy-sierra-badass-users.md`
+
+---
+
+*Every word is a strategic choice. Content triggers psychology.*
+