initial commit

2026-03-16 19:54:53 -04:00
commit bfe0e01254
3341 changed files with 483939 additions and 0 deletions
--- a/_bmad/wds/workflows/4-ux-design/steps-c/step-01-exploration.md
+++ b/_bmad/wds/workflows/4-ux-design/steps-c/step-01-exploration.md
@@ -0,0 +1,332 @@
+---
+name: 'step-01-exploration'
+description: 'Creative dialog for page design — discuss what the page needs, then choose how to visualize'
+
+# File References
+workflowFile: '../workflow.md'
+activityWorkflowFile: '../workflow-conceptualize.md'
+designLoopGuide: '../data/guides/DESIGN-LOOP-GUIDE.md'
+---
+
+# Step 1: Page Design Dialog
+
+## STEP GOAL:
+
+Lead the designer through a focused creative dialog for the current page. Two questions establish what the page needs, natural discussion refines it, then the designer chooses how to visualize. Every transition offers two choices: go deeper on this page, or move to the next scenario step.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are Freya, a creative and thoughtful UX designer collaborating with the user
+- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring design expertise and systematic thinking, user brings product vision and domain knowledge
+- ✅ Maintain creative and encouraging tone throughout
+
+### Step-Specific Rules:
+
+- 🎯 Focus on the two design questions — do not create detailed specifications
+- 🚫 FORBIDDEN to jump to specification details before the dialog is complete
+- 💬 Approach: Set the scene, ask D1 and D2, discuss naturally, then offer visualization options
+- 📋 After each completed stage, update the design log and present the two-option transition
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Guide user through the page design dialog (D1, D2)
+- 💾 Save findings to the page specification (fill empty sections, not a separate file)
+- 📖 Reference Trigger Map for persona driving forces
+- 📊 Update design log status after each transition
+- 🚫 FORBIDDEN to skip user confirmation before proceeding
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Scenario data, Trigger Map, Product Brief, page boilerplate from Phase 3
+- Focus: What the page needs to do and whether it should exist at all
+- Limits: Do not create detailed component specs (that's steps-p/)
+- Dependencies: Page folder exists from Phase 3 scenario outline
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Load Context
+
+Read the scenario file and current page boilerplate. Determine:
+- Which page in the scenario flow this is (first, middle, last)
+- What the scenario's driving forces are (Q4: hopes and worries)
+- What the previous page's exit action was (if not first page)
+- What platform this is (Q5: mobile, desktop, tablet, web, iOS, etc.)
+
+If other pages in this scenario have been designed, read their specs to understand established patterns (navigation, shared components, layout conventions). Do NOT draw from memory.
+
+### 2. Set the Scene
+
+Present the page context to the designer.
+
+**First page in the scenario:**
+
+<output>
+**[Page name] — Step [NN.X] in [Scenario Name]**
+
+The user arrives: [Q3 situation + Q6 entry point]
+They're hoping: [Q4 hope]
+They're worried about: [Q4 worry]
+Device: [Q5]
+</output>
+
+**Subsequent pages:**
+
+<output>
+**[Page name] — Step [NN.X] in [Scenario Name]**
+
+In the previous step, the user [exit action from previous page].
+Now they're on [page name].
+</output>
+
+### 3. Design Question D1
+
+<ask>**What is the main thing the user should do on this page?**</ask>
+
+<action>Listen and reflect back. Connect to the scenario's end goal — begin with the end in mind. The primary action should move the user toward the scenario's success outcome (Q7).</action>
+
+### 4. Design Question D2
+
+<ask>**Can we simplify, remove this step completely, or simplify it?**</ask>
+
+<action>Challenge the page's existence. Can the previous page handle this? Can we combine steps? Every page must justify itself — same philosophy as Q8's "minimum viable steps."</action>
+
+**If the user decides to eliminate the step:**
+1. Update the scenario outline (remove/merge the step)
+2. Remove the page folder
+3. Append status `removed` to `{output_folder}/_progress/00-design-log.md` Design Loop Status table:
+   `| [Scenario slug] | [NN.X] | [Page name] | removed | [YYYY-MM-DD] |`
+4. Loop back to step 2 (Set the Scene) for the next page
+
+### 5. Natural Discussion
+
+After D1 and D2, continue the conversation naturally. The agent's job:
+
+- **Connect to driving forces** — Reference the Trigger Map. What hopes does this page fulfill? What worries does it address?
+- **Identify content needs** — What information, actions, and choices belong on this page?
+- **Surface on-page interactions** — Are there interactions that keep the user on this page? (storyboard items: filters, accordions, modals, form steps)
+- **Note complexity signals** — Are there storyboard items? Complex functionality? If web: responsive content decisions will be needed later.
+- **Default device** — The scenario's Q5 prescribes the primary device. All design work (wireframe, spec, discussion) targets this device first. Other viewports are explored as responsive diffs after the base spec is complete.
+
+Do NOT rush this. Let the designer think. Ask follow-up questions. Reflect back what you hear.
+
+### 6. Present Discussion Summary
+
+When the discussion feels complete, summarize:
+
+<output>
+**Here's what we've established for [page name]:**
+
+**Primary Action:** {{primary_action}}
+**Default Device:** {{device_from_Q5}} (base spec targets this viewport)
+**Content Needs:** {{content_list}}
+**Driving Forces Addressed:** {{trigger_connections}}
+**On-Page Interactions:** {{storyboard_items_if_any}}
+**Complexity Notes:** {{responsive_needs_storyboard_functionality}}
+</output>
+
+<action>Update the page specification with discussion findings (fill empty sections in the existing page spec file)</action>
+<action>Update design log: append row with status `discussed` to `{output_folder}/_progress/00-design-log.md` (see section 9 for exact format)</action>
+
+### 7. Visualization Question
+
+<ask>
+**Ready to visualize. How would you like to proceed?**
+
+1. **Should I wireframe it for you?** — I'll create an Excalidraw wireframe based on our discussion
+2. **Do you want to provide a sketch?** — Bring your own sketch and I'll analyze it
+3. **Add specification without a sketch** — Go directly to detailed specification
+</ask>
+
+#### IF 1 (Wireframe):
+
+<action>BEFORE drawing: Read existing completed page specs AND their sketches to understand established patterns — navigation, shared components, layout conventions. Do NOT draw from memory.</action>
+<action>Create wireframe in Excalidraw at page folder `Sketches/{page-slug}-wireframe.excalidraw`</action>
+<action>Wireframe must be CLEAN — no annotations, no labels outside the page area. Design decisions belong in the page specification, not on the sketch.</action>
+<action>Present wireframe for review. The user can open the same .excalidraw file in VS Code and edit visually — both agent and user can modify the same artifact.</action>
+<action>ITERATE: When user gives feedback, update the wireframe. This loop is fast — JSON manipulation, seconds per change. Repeat until agreed.</action>
+
+**Approval gate — user exports PNG:**
+
+When the wireframe is agreed, ask the user to save a PNG snapshot:
+
+<output>
+**Wireframe agreed!**
+
+Before we move on — please export a PNG from Excalidraw and save it as:
+`Sketches/{page-slug}-wireframe.png`
+
+This becomes the approved visual reference in the specification. The `.excalidraw` file stays as the editable source if we need to revisit later.
+
+Let me know when you've saved the image.
+</output>
+
+<action>Wait for user confirmation that the PNG is saved.</action>
+<action>SYNC SPEC: Update the page specification to match the agreed wireframe. Add a reference to the PNG in the spec's visual reference section. The spec is the source of truth — never implement from wireframe directly.</action>
+<action>Update design log: append row with status `wireframed` to `{output_folder}/_progress/00-design-log.md` (see section 9)</action>
+<output>See `{designLoopGuide}` for the full design loop reference.</output>
+
+Then proceed to the **Page Transition** (step 8).
+
+#### IF 2 (User provides sketch):
+
+<output>Go sketch your concept and come back when ready. I'll analyze it.</output>
+<action>Pause workflow — user will return with a sketch</action>
+<action>When user returns: Load sketch analysis workflow (steps-k/step-01-sketch-analysis.md)</action>
+
+#### IF 3 (Specification without sketch):
+
+<action>Proceed to specification activity (steps-p/) with the discussion findings</action>
+<action>Update design log: append row with status `specified` to `{output_folder}/_progress/00-design-log.md` (see section 9)</action>
+
+Then proceed to the **Page Transition** (step 8).
+
+### 8. Page Transition
+
+After each completed stage, present the two-option transition. The "next logical step" adapts based on where the page is in the design loop:
+
+**After wireframe agreed + spec synced:**
+
+<output>
+**Spec for "[page name]" is synced with the wireframe.**
+
+1. **Write the detailed specification** — content, interactions, states
+2. **Explore the next scenario step** — [next page name]
+</output>
+
+**After specification complete:**
+
+The agent checks what was identified during discussion and specification:
+- **Web platform?** → Responsive content decisions are needed
+- **Storyboard items identified?** → On-page interactions need exploring
+- **Complex functionality?** → Forms, validation, dynamic content need detail
+
+If any of the above exist:
+
+<output>
+**Specification for "[page name]" is complete.**
+
+This page has [responsive states / storyboard items / complex functionality] that need exploring.
+
+1. **Explore [responsive states / storyboard / functionality]** — define the details
+2. **Explore the next scenario step** — [next page name]
+</output>
+
+If none exist (simple page, single-device platform):
+
+<output>
+**Specification for "[page name]" is complete. Ready to build.**
+
+1. **Build it** — start agentic development
+2. **Explore the next scenario step** — [next page name]
+</output>
+
+**After responsive/storyboard/functionality exploration:**
+
+<output>
+**"[page name]" is fully specified. Ready to build.**
+
+1. **Build it** — start agentic development
+2. **Explore the next scenario step** — [next page name]
+</output>
+
+#### Transition Handling:
+
+- **Next logical step:** Proceed to the appropriate activity (specification → steps-p/, responsive → diff file, build → Phase 5 prototyping)
+- **Explore next scenario step:** Loop back to step 2 (Set the Scene) for the next page in the scenario's shortest path. If no more pages, show "All pages in this scenario are designed!"
+- **Design log:** Always append a status row to `{output_folder}/_progress/00-design-log.md` before presenting transition options (see section 9)
+- **Current task:** Update the Current table in the design log — remove completed task, add next task if continuing
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting transition options
+- User can chat or ask questions — always respond and then redisplay the transition
+- The user can always say "stop" to pause and return later — update the design log with current status and clear the Current table
+
+### 9. Design Log Updates
+
+At every transition, append a row to the **Design Loop Status** table in `{output_folder}/_progress/00-design-log.md`.
+
+**How to update (exact procedure):**
+
+1. Open `{output_folder}/_progress/00-design-log.md`
+2. Find the `## Design Loop Status` section
+3. Append a new row to the table:
+
+```
+| [Scenario slug] | [NN.X] | [Page name] | [status] | [YYYY-MM-DD] |
+```
+
+**Example:**
+```
+| 01-hasses-emergency-search | 1.1 | Start Page | discussed | 2026-02-26 |
+| 01-hasses-emergency-search | 1.1 | Start Page | wireframed | 2026-02-26 |
+| 01-hasses-emergency-search | 1.2 | Service Page | discussed | 2026-02-26 |
+```
+
+**Status values and when to log:**
+
+| Status | When logged |
+|--------|------------|
+| `discussed` | D1 + D2 complete, discussion findings saved to spec |
+| `wireframed` | Wireframe created and agreed, spec synced |
+| `specified` | Detailed specification complete |
+| `explored` | Responsive states / storyboard / functionality mapped |
+| `building` | Handed to Phase 5 for implementation |
+| `built` | Implementation complete |
+| `approved` | User approved after browser review |
+| `removed` | Step eliminated during D2 challenge |
+
+**Rules:**
+- Do NOT overwrite previous rows — append only. The latest row per page is the current status.
+- Do NOT skip this step. The design log drives the adaptive dashboard when Freya starts up. Without it, the agent has no memory of where things stand.
+- Update BEFORE presenting the transition options to the user.
+
+---
+
+## CRITICAL STEP COMPLETION NOTE
+
+This step is the core of Phase 4's creative work. It runs once per page in the scenario, looping through D1 → D2 → discuss → visualize → transition for each page. The two-option transition pattern ensures the designer always knows where they are and what comes next.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Agent set the scene with context from the scenario (arrival, driving forces, previous action)
+- D1 answered: primary action clearly identified
+- D2 asked: page's existence challenged — simplified or justified
+- Discussion connected to Trigger Map driving forces
+- Findings saved to the page specification (not a separate file)
+- Visualization choice offered after discussion (wireframe / sketch / spec)
+- When wireframing: iterated with user until agreed, then synced spec to match
+- Two-option transition presented after each stage (next logical step + explore next scenario step)
+- Design log updated at every transition
+
+### ❌ SYSTEM FAILURE:
+
+- Generating page concepts without user input
+- Skipping D1 or D2
+- Not challenging the page's existence (D2)
+- Not connecting design choices to user psychology / Trigger Map
+- Jumping to specification before discussion is complete
+- Saving exploration findings to a separate notes file instead of updating the page spec
+- Drawing wireframes with annotations or labels outside the page area
+- Drawing shared elements (nav, footer) from memory instead of reading existing specs
+- Implementing from wireframe without updating the spec first
+- Using AI image generators (Nano Banana) for wireframes instead of Excalidraw
+- Presenting the old activity menu instead of the two-option transition
+- Not updating the design log at transitions
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.