From afdfcd0f1cd9fd60af7cac755c40892a345b87c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A5rten=20Angner?= Date: Fri, 6 Feb 2026 22:30:50 +0100 Subject: [PATCH] Sync optimized workflows from expansion repo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All step files now comply with BMAD v6 (<200 lines, 250 max): Optimized phases: - Phase 1: step-11-tone-of-voice (233→162 lines) - Phase 2: step-02-generate-business-goals (231→86 lines) - Phase 4: page workshops (578→135, 406→169, 355→197 lines) - Phase 6: handoff dialogs (441→107, 327→130, 414→137 lines) - Phase 7: testing steps (683→158, 517→112, 441→101, etc.) - Phase 8: ongoing development (498→164, 381→131, etc.) - Shared: vtc customer-awareness (256→193 lines) Created 18 substep files for templates and examples. Total: 59 files changed, 5605 insertions, 8885 deletions. Co-Authored-By: Claude Opus 4.5 --- .../complete/steps-c/step-11-tone-of-voice.md | 75 +- .../steps-c/substeps/11-output-template.md | 76 ++ .../step-02-generate-business-goals.md | 161 +-- .../substeps/02-business-goals-template.md | 150 +++ src/workflows/3-prd-platform/instructions.md | 1188 +---------------- .../3-prd-platform/steps/step-01-welcome.md | 52 + .../steps/step-02-platform-architecture.md | 72 + .../steps/step-03-integration-mapping.md | 81 ++ .../steps/step-04-technical-validation.md | 56 + .../steps/step-05-security-framework.md | 65 + .../steps/step-06-api-specifications.md | 56 + .../steps/step-07-data-and-performance.md | 67 + .../steps/step-08-backlog-recommendations.md | 64 + .../steps/step-09-prd-finalization.md | 86 ++ .../3-prd-platform/steps/step-10-summary.md | 55 + .../guides/EXECUTION-PRINCIPLES.md | 75 ++ .../guides/FEEDBACK-PROTOCOL.md | 86 ++ .../guides/SESSION-PROTOCOL.md | 46 + .../agentic-development/workflow.md | 629 +-------- .../4-ux-design/object-types/workflow.md | 401 +----- .../page-init/page-init-lightweight.md | 177 +-- .../page-init/substeps/flow-a-sketch.md | 28 + .../page-init/substeps/flow-b-verbal.md | 138 ++ .../page-init/substeps/flow-c-ascii.md | 92 ++ .../page-init/substeps/flow-d-reference.md | 69 + .../page-init/substeps/flow-e-html.md | 131 ++ .../substeps/lightweight-page-template.md | 135 ++ .../substeps/page-process-templates.md | 130 ++ .../substeps/placeholder-templates.md | 153 +++ .../page-init/workshop-c-placeholder-pages.md | 272 +--- .../page-init/workshop-page-creation.md | 472 +------ .../page-init/workshop-page-process.md | 152 +-- .../steps/step-6.4-handoff-dialog.md | 371 +---- .../steps/step-6.5-hand-off.md | 224 +--- .../steps/step-6.6-continue.md | 334 +---- .../steps/substeps/delivery-templates.md | 188 +++ .../steps/substeps/handoff-dialog-scripts.md | 276 ++++ .../7-testing/steps/step-7.3-run-tests.md | 626 +-------- .../7-testing/steps/step-7.4-create-issues.md | 498 +------ .../7-testing/steps/step-7.5-create-report.md | 429 +----- .../7-testing/steps/step-7.6-send-to-bmad.md | 356 +---- .../steps/step-7.7-iterate-or-approve.md | 569 +------- .../steps/substeps/issue-templates.md | 213 +++ .../steps/substeps/test-result-templates.md | 210 +++ .../steps/step-8.1-identify-opportunity.md | 380 +----- .../steps/step-8.2-gather-context.md | 302 +---- .../steps/step-8.3-design-update.md | 387 +----- .../steps/step-8.4-create-delivery.md | 340 +---- .../steps/step-8.6-validate.md | 103 +- .../steps/step-8.7-monitor.md | 316 +---- .../steps/step-8.8-iterate.md | 460 +------ .../steps/substeps/context-templates.md | 409 ++++++ .../steps/substeps/delivery-templates.md | 357 +++++ .../steps/substeps/design-templates.md | 312 +++++ .../steps/substeps/kaizen-principles.md | 276 ++++ .../steps/substeps/monitoring-templates.md | 388 ++++++ src/workflows/9-agent-dialogs/workflow.md | 343 +---- .../WORKFLOW-OPTIMIZATION-COMPLETE.md | 261 ++++ .../step-06-customer-awareness.md | 106 +- 59 files changed, 5622 insertions(+), 8902 deletions(-) create mode 100644 src/workflows/1-project-brief/project-brief/complete/steps-c/substeps/11-output-template.md create mode 100644 src/workflows/2-trigger-mapping/document-generation/steps-c/substeps/02-business-goals-template.md create mode 100644 src/workflows/3-prd-platform/steps/step-01-welcome.md create mode 100644 src/workflows/3-prd-platform/steps/step-02-platform-architecture.md create mode 100644 src/workflows/3-prd-platform/steps/step-03-integration-mapping.md create mode 100644 src/workflows/3-prd-platform/steps/step-04-technical-validation.md create mode 100644 src/workflows/3-prd-platform/steps/step-05-security-framework.md create mode 100644 src/workflows/3-prd-platform/steps/step-06-api-specifications.md create mode 100644 src/workflows/3-prd-platform/steps/step-07-data-and-performance.md create mode 100644 src/workflows/3-prd-platform/steps/step-08-backlog-recommendations.md create mode 100644 src/workflows/3-prd-platform/steps/step-09-prd-finalization.md create mode 100644 src/workflows/3-prd-platform/steps/step-10-summary.md create mode 100644 src/workflows/4-ux-design/agentic-development/guides/EXECUTION-PRINCIPLES.md create mode 100644 src/workflows/4-ux-design/agentic-development/guides/FEEDBACK-PROTOCOL.md create mode 100644 src/workflows/4-ux-design/agentic-development/guides/SESSION-PROTOCOL.md create mode 100644 src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/flow-a-sketch.md create mode 100644 src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/flow-b-verbal.md create mode 100644 src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/flow-c-ascii.md create mode 100644 src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/flow-d-reference.md create mode 100644 src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/flow-e-html.md create mode 100644 src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/lightweight-page-template.md create mode 100644 src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/page-process-templates.md create mode 100644 src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/placeholder-templates.md create mode 100644 src/workflows/6-design-deliveries/steps/substeps/delivery-templates.md create mode 100644 src/workflows/6-design-deliveries/steps/substeps/handoff-dialog-scripts.md create mode 100644 src/workflows/7-testing/steps/substeps/issue-templates.md create mode 100644 src/workflows/7-testing/steps/substeps/test-result-templates.md create mode 100644 src/workflows/8-ongoing-development/steps/substeps/context-templates.md create mode 100644 src/workflows/8-ongoing-development/steps/substeps/delivery-templates.md create mode 100644 src/workflows/8-ongoing-development/steps/substeps/design-templates.md create mode 100644 src/workflows/8-ongoing-development/steps/substeps/kaizen-principles.md create mode 100644 src/workflows/8-ongoing-development/steps/substeps/monitoring-templates.md create mode 100644 src/workflows/WORKFLOW-OPTIMIZATION-COMPLETE.md diff --git a/src/workflows/1-project-brief/project-brief/complete/steps-c/step-11-tone-of-voice.md b/src/workflows/1-project-brief/project-brief/complete/steps-c/step-11-tone-of-voice.md index b853b753c..013cea0b8 100644 --- a/src/workflows/1-project-brief/project-brief/complete/steps-c/step-11-tone-of-voice.md +++ b/src/workflows/1-project-brief/project-brief/complete/steps-c/step-11-tone-of-voice.md @@ -75,33 +75,7 @@ Does this feel aligned with your brand vision? ### 3. Provide Examples -Show the tone in action with side-by-side comparisons: - -**Format:** - -``` -Example UI Microcopy: - -Error Message: -❌ Generic: "Error: Invalid input" -✅ Our Tone: [Rewritten in proposed tone] - -Button Text: -❌ Generic: "Submit" -✅ Our Tone: [Rewritten in proposed tone] - -Empty State: -❌ Generic: "No results found" -✅ Our Tone: [Rewritten in proposed tone] - -Form Label: -❌ Generic: "Email address" -✅ Our Tone: [Rewritten in proposed tone] - -Success Message: -❌ Generic: "Operation successful" -✅ Our Tone: [Rewritten in proposed tone] -``` +Show the tone in action with side-by-side comparisons. **See:** [substeps/11-output-template.md](substeps/11-output-template.md) for the example format. ### 4. Refine Based on Feedback @@ -147,52 +121,7 @@ Before proceeding: ## Output Format -Document in Product Brief: - -```markdown -## Tone of Voice - -**For UI Microcopy & System Messages** - -### Tone Attributes - -1. **[Attribute 1]**: [Brief description] -2. **[Attribute 2]**: [Brief description] -3. **[Attribute 3]**: [Brief description] - -### Examples - -**Error Messages:** -- ✅ "Hmm, that doesn't look like an email. Check for typos?" -- ❌ "Error: Invalid email format" - -**Button Text:** -- ✅ "Let's get started" -- ❌ "Submit" - -**Empty States:** -- ✅ "Nothing here yet. Ready to add your first item?" -- ❌ "No results found" - -**Success Messages:** -- ✅ "You're all set! We've sent a confirmation to your email." -- ❌ "Operation completed successfully" - -### Guidelines - -**Do:** -- [Tone-appropriate practice 1] -- [Tone-appropriate practice 2] -- [Tone-appropriate practice 3] - -**Don't:** -- [Tone-inappropriate practice 1] -- [Tone-inappropriate practice 2] - ---- - -*Note: Tone of Voice applies to UI microcopy. Strategic content (headlines, feature descriptions, value propositions) uses the Content Creation Workshop based on page-specific purpose and context.* -``` +**See:** [substeps/11-output-template.md](substeps/11-output-template.md) for the complete Product Brief template. ## Next Step diff --git a/src/workflows/1-project-brief/project-brief/complete/steps-c/substeps/11-output-template.md b/src/workflows/1-project-brief/project-brief/complete/steps-c/substeps/11-output-template.md new file mode 100644 index 000000000..f2aeb90dc --- /dev/null +++ b/src/workflows/1-project-brief/project-brief/complete/steps-c/substeps/11-output-template.md @@ -0,0 +1,76 @@ +# Tone of Voice - Output Template + +Use this template to document the final Tone of Voice in the Product Brief. + +```markdown +## Tone of Voice + +**For UI Microcopy & System Messages** + +### Tone Attributes + +1. **[Attribute 1]**: [Brief description] +2. **[Attribute 2]**: [Brief description] +3. **[Attribute 3]**: [Brief description] + +### Examples + +**Error Messages:** +- ✅ "Hmm, that doesn't look like an email. Check for typos?" +- ❌ "Error: Invalid email format" + +**Button Text:** +- ✅ "Let's get started" +- ❌ "Submit" + +**Empty States:** +- ✅ "Nothing here yet. Ready to add your first item?" +- ❌ "No results found" + +**Success Messages:** +- ✅ "You're all set! We've sent a confirmation to your email." +- ❌ "Operation completed successfully" + +### Guidelines + +**Do:** +- [Tone-appropriate practice 1] +- [Tone-appropriate practice 2] +- [Tone-appropriate practice 3] + +**Don't:** +- [Tone-inappropriate practice 1] +- [Tone-inappropriate practice 2] + +--- + +*Note: Tone of Voice applies to UI microcopy. Strategic content (headlines, feature descriptions, value propositions) uses the Content Creation Workshop based on page-specific purpose and context.* +``` + +## Example Microcopy Format + +When presenting examples, use this comparison format: + +``` +Example UI Microcopy: + +Error Message: +❌ Generic: "Error: Invalid input" +✅ Our Tone: [Rewritten in proposed tone] + +Button Text: +❌ Generic: "Submit" +✅ Our Tone: [Rewritten in proposed tone] + +Empty State: +❌ Generic: "No results found" +✅ Our Tone: [Rewritten in proposed tone] + +Form Label: +❌ Generic: "Email address" +✅ Our Tone: [Rewritten in proposed tone] + +Success Message: +❌ Generic: "Operation successful" +✅ Our Tone: [Rewritten in proposed tone] +``` diff --git a/src/workflows/2-trigger-mapping/document-generation/steps-c/step-02-generate-business-goals.md b/src/workflows/2-trigger-mapping/document-generation/steps-c/step-02-generate-business-goals.md index fe6878b44..6c2ecf2d8 100644 --- a/src/workflows/2-trigger-mapping/document-generation/steps-c/step-02-generate-business-goals.md +++ b/src/workflows/2-trigger-mapping/document-generation/steps-c/step-02-generate-business-goals.md @@ -17,160 +17,15 @@ Document the strategic foundation: ## Document Structure -### 1. Header +**See:** [substeps/02-business-goals-template.md](substeps/02-business-goals-template.md) for the complete template. -```markdown -# Business Goals & Objectives - -> Strategic goals and measurable objectives for [Project Name] - -**Document:** Trigger Map - Business Goals -**Created:** [Date] -**Status:** COMPLETE -``` - ---- - -### 2. Vision Statement - -```markdown -## Vision - -**[Insert vision statement from workshop]** - -[Should be 1-2 sentences describing the ultimate goal/transformation] -``` - ---- - -### 3. Business Objectives (3 Priority Tiers) - -**Structure with clear hierarchy:** - -```markdown -## Business Objectives - -### ⭐ PRIMARY GOAL: [Title] (THE ENGINE) -- **Statement:** [What we're building] -- **Metric:** [How we measure it] -- **Target:** [Specific number] -- **Timeline:** [X months] -- **Impact:** This drives ALL other objectives - this is the key to expansion -``` - -**Follow with SECONDARY and TERTIARY tiers:** - -```markdown ---- - -### 🚀 [SECONDARY GOALS CATEGORY] (Driven by [Primary Goal]) - -**Objective 1: [Title]** -- **Statement:** [What we're achieving] -- **Metric:** [How we measure] -- **Target:** [Number] -- **Timeline:** [X months from launch] - -[Repeat for all secondary objectives: 2, 3, 4...] - ---- - -### 🌟 [TERTIARY GOALS CATEGORY] (Real-World Benefits for Members) - -**Note:** These are opportunities [Product] creates FOR the community members - [benefit description]. - -**Objective X: [Title]** -- **Statement:** [What members get] -- **Metric:** [How we measure member success] -- **Target:** [Number] -- **Timeline:** [X months] -- **Benefit to Members:** [Career/personal growth impact] - -[Repeat for all tertiary objectives] -``` - ---- - -### 4. The Flywheel Section - -**Explain how goals connect:** - -```markdown -## The Flywheel: How Goals Connect - -**THE ENGINE (Priority #1):** -- [Primary goal number] [primary goal description] -- Timeline: [X] months -- These [users] [action that drives everything] -- They create the flywheel that drives ALL other objectives - -**[Secondary Category] (Priority #2):** -- Driven BY the [primary goal achievers] -- [List key targets with numbers] -- Timeline: [X] months -- Focus: [What this tier achieves] - -**[Tertiary Category] (Priority #3):** -- Real-world benefits FOR community members -- [List key opportunities] -- Timeline: [X] months -- **Key benefit**: [How members' lives improve] -``` - ---- - -### 5. Success Metrics Alignment - -**Show how personas connect to objectives:** - -```markdown -## Success Metrics Alignment - -### How Trigger Map Connects to Objectives (Properly Prioritized): - -**⭐ PRIMARY: Creating Awesome [Users] Who Become [Champions] → Achieves:** -- ✅ **[Number] [champions]** (THE ENGINE - [Persona] becomes one of them naturally) -- ✅ [Action 1] -- ✅ [Action 2] -- ✅ [Natural outcome] -- **Timeline: [X] months** -- **This drives ALL other objectives** - -**🚀 SECONDARY: [Champions] Drive [Product] Adoption → Achieves:** -- ✅ [Objective 1] ([champions] spread the word) -- ✅ [Objective 2] ([champions] demonstrate value) -- ✅ [Objective 3] ([champions] create engagement) -- **Timeline: [X] months** - -**🌟 TERTIARY: [Product] Success Creates Opportunities for Community → Achieves:** -- ✅ [Opportunity 1] (members [benefit]) -- ✅ [Opportunity 2] (members [benefit]) -- ✅ [Opportunity 3] (members [benefit]) -- **Timeline: [X] months** -- **Benefit: [Impact on members' lives/careers]** - -**The Trigger Map IS the Strategic Foundation - And Prioritization Matters** - -The page must empower [Primary Persona] → make [them] awesome → [they] naturally become [champions] → [champions] drive adoption → adoption creates opportunities for all members. -``` - ---- - -### 6. Related Documents Footer - -```markdown -## Related Documents - -- **[00-trigger-map.md](00-trigger-map.md)** - Visual overview and navigation -- **[02-[Primary].md](02-[Primary].md)** - Primary persona -- **[03-[Secondary].md](03-[Secondary].md)** - Secondary persona -- **[04-[Tertiary].md](04-[Tertiary].md)** - Tertiary persona [if exists] -- **[05-Key-Insights.md](05-Key-Insights.md)** - Strategic implications - ---- - -_Back to [Trigger Map](00-trigger-map.md)_ -``` +The document includes these sections: +1. **Header** - Project name, date, status +2. **Vision Statement** - 1-2 sentence transformation goal +3. **Business Objectives** - 3 priority tiers (Primary/Secondary/Tertiary) +4. **The Flywheel** - How goals connect causally +5. **Success Metrics Alignment** - Persona → objective connections +6. **Related Documents Footer** - Links to other trigger map docs --- diff --git a/src/workflows/2-trigger-mapping/document-generation/steps-c/substeps/02-business-goals-template.md b/src/workflows/2-trigger-mapping/document-generation/steps-c/substeps/02-business-goals-template.md new file mode 100644 index 000000000..ac6a22fd8 --- /dev/null +++ b/src/workflows/2-trigger-mapping/document-generation/steps-c/substeps/02-business-goals-template.md @@ -0,0 +1,150 @@ +# Business Goals Document Template + +Complete template structure for 01-Business-Goals.md + +--- + +## 1. Header + +```markdown +# Business Goals & Objectives + +> Strategic goals and measurable objectives for [Project Name] + +**Document:** Trigger Map - Business Goals +**Created:** [Date] +**Status:** COMPLETE +``` + +--- + +## 2. Vision Statement + +```markdown +## Vision + +**[Insert vision statement from workshop]** + +[Should be 1-2 sentences describing the ultimate goal/transformation] +``` + +--- + +## 3. Business Objectives (3 Priority Tiers) + +```markdown +## Business Objectives + +### ⭐ PRIMARY GOAL: [Title] (THE ENGINE) +- **Statement:** [What we're building] +- **Metric:** [How we measure it] +- **Target:** [Specific number] +- **Timeline:** [X months] +- **Impact:** This drives ALL other objectives - this is the key to expansion + +--- + +### 🚀 [SECONDARY GOALS CATEGORY] (Driven by [Primary Goal]) + +**Objective 1: [Title]** +- **Statement:** [What we're achieving] +- **Metric:** [How we measure] +- **Target:** [Number] +- **Timeline:** [X months from launch] + +[Repeat for all secondary objectives: 2, 3, 4...] + +--- + +### 🌟 [TERTIARY GOALS CATEGORY] (Real-World Benefits for Members) + +**Note:** These are opportunities [Product] creates FOR the community members - [benefit description]. + +**Objective X: [Title]** +- **Statement:** [What members get] +- **Metric:** [How we measure member success] +- **Target:** [Number] +- **Timeline:** [X months] +- **Benefit to Members:** [Career/personal growth impact] + +[Repeat for all tertiary objectives] +``` + +--- + +## 4. The Flywheel Section + +```markdown +## The Flywheel: How Goals Connect + +**THE ENGINE (Priority #1):** +- [Primary goal number] [primary goal description] +- Timeline: [X] months +- These [users] [action that drives everything] +- They create the flywheel that drives ALL other objectives + +**[Secondary Category] (Priority #2):** +- Driven BY the [primary goal achievers] +- [List key targets with numbers] +- Timeline: [X] months +- Focus: [What this tier achieves] + +**[Tertiary Category] (Priority #3):** +- Real-world benefits FOR community members +- [List key opportunities] +- Timeline: [X] months +- **Key benefit**: [How members' lives improve] +``` + +--- + +## 5. Success Metrics Alignment + +```markdown +## Success Metrics Alignment + +### How Trigger Map Connects to Objectives (Properly Prioritized): + +**⭐ PRIMARY: Creating Awesome [Users] Who Become [Champions] → Achieves:** +- ✅ **[Number] [champions]** (THE ENGINE - [Persona] becomes one of them naturally) +- ✅ [Action 1] +- ✅ [Action 2] +- ✅ [Natural outcome] +- **Timeline: [X] months** +- **This drives ALL other objectives** + +**🚀 SECONDARY: [Champions] Drive [Product] Adoption → Achieves:** +- ✅ [Objective 1] ([champions] spread the word) +- ✅ [Objective 2] ([champions] demonstrate value) +- ✅ [Objective 3] ([champions] create engagement) +- **Timeline: [X] months** + +**🌟 TERTIARY: [Product] Success Creates Opportunities for Community → Achieves:** +- ✅ [Opportunity 1] (members [benefit]) +- ✅ [Opportunity 2] (members [benefit]) +- ✅ [Opportunity 3] (members [benefit]) +- **Timeline: [X] months** +- **Benefit: [Impact on members' lives/careers]** + +**The Trigger Map IS the Strategic Foundation - And Prioritization Matters** + +The page must empower [Primary Persona] → make [them] awesome → [they] naturally become [champions] → [champions] drive adoption → adoption creates opportunities for all members. +``` + +--- + +## 6. Related Documents Footer + +```markdown +## Related Documents + +- **[00-trigger-map.md](00-trigger-map.md)** - Visual overview and navigation +- **[02-[Primary].md](02-[Primary].md)** - Primary persona +- **[03-[Secondary].md](03-[Secondary].md)** - Secondary persona +- **[04-[Tertiary].md](04-[Tertiary].md)** - Tertiary persona [if exists] +- **[05-Key-Insights.md](05-Key-Insights.md)** - Strategic implications + +--- + +_Back to [Trigger Map](00-trigger-map.md)_ +``` diff --git a/src/workflows/3-prd-platform/instructions.md b/src/workflows/3-prd-platform/instructions.md index cd43bfc5d..b8144a4ad 100644 --- a/src/workflows/3-prd-platform/instructions.md +++ b/src/workflows/3-prd-platform/instructions.md @@ -1,1161 +1,57 @@ # Phase 3: PRD Platform (Technical Foundation) -**Agent:** Freya the PM -**Output Folder:** `C-Requirements/` (or user's configured prefix) +**Agent:** Idunn the PM +**Output Folder:** `C-Requirements/` --- ## Overview -This phase establishes the technical foundation for the product—everything that can be validated and documented **before** the final UI is designed. The goal is to prove that innovative features are technically feasible, establish platform decisions, and set up experimental endpoints that enable parallel development work. +This phase establishes the technical foundation — everything that can be validated and documented **before** the final UI is designed. Prove that innovative features are technically feasible, establish platform decisions, and enable parallel development work. -**Core Principle:** Prove our concept works technically — in parallel with design work. - ---- - -## What You'll Create - -By the end of this phase, the `C-Requirements/` folder will contain comprehensive technical specifications: - -1. **00-Platform-Architecture.md** - Technology stack and infrastructure decisions -2. **01-Integration-Map.md** - External services and how they connect -3. **02-Technical-Proofs-Of-Concept.md** - Validation of risky features -4. **03-Security-Framework.md** - Authentication, authorization, compliance -5. **04-API-Specifications.md** - Service contracts and endpoint definitions (API-first) -6. **05-Data-Models.md** - Database schemas and entity relationships -7. **06-Performance-Requirements.md** - Scalability and benchmarks -8. **07-Technical-Constraints.md** - What UX design needs to know -9. **08-Acceptance-Criteria.md** - Testable success definitions -10. **09-Platform-Backlog-Recommendations.md** - Suggested epics/initiatives for BMM -11. **10-PRD.md** - Product Requirements Document (started here, grows in Phase 4) - -**Note:** These are requirements documents. The actual backlog creation (epics, stories, E-Backlog/ structure) will be handled by BMM agents based on these recommendations. - ---- +**Core Principle:** Prove the concept works technically — in parallel with design work. ## Prerequisites -Before starting, ensure you have: - -- ✅ Product Brief (Phase 1) - Strategic context -- ✅ Trigger Map with Feature Impact Analysis (Phase 2) - Prioritized features -- ✅ Development team availability (for PoC work if needed) - ---- - -## Workflow Steps - -### Step 1: Welcome and Context Review - -**Freya's Role:** - -Greet the user and explain this phase: - -- "We're establishing your technical foundation—proving that innovative features work before investing in design." -- "We'll make platform decisions, validate risky features with PoCs, and set up experimental endpoints." -- "This enables backend development to start in parallel with UX design." - -Review available context: - -- Read the Product Brief to understand project scope and constraints -- Read the Feature Impact Analysis to identify high-priority features -- Ask: "Do you already have any technical constraints or platform preferences?" - ---- - -### Step 2: Platform Architecture Decisions - -**Goal:** Define the technology stack and infrastructure through systematic discussion. - -**Freya's Approach:** - -"Let's establish your technical foundation. I'll walk through each major area, and we'll document your decisions, business rules, and constraints as we go." - -**2A: Technology Stack** - -Ask each question and document the answer: - -1. **Backend:** - - "What backend framework/language are you using?" - - "Why this choice? Any specific requirements or constraints?" - - **Business Rules to Capture:** - - Language version requirements - - Framework-specific patterns or conventions - - Performance characteristics needed - -2. **Frontend:** - - "What frontend framework are you using?" - - "Any UI library or component framework?" - - "Why this choice?" - - **Business Rules to Capture:** - - Browser support requirements - - Mobile responsiveness needs - - Accessibility standards - -3. **Database:** - - "What database system(s) will you use?" - - "What are your core data entities?" (Start listing them) - - "How do they relate to each other?" - - **Business Rules to Capture:** - - Data retention policies - - Backup/recovery requirements - - Data consistency needs (ACID vs. eventual consistency) - -**2B: Architecture Style** - -Ask systematically: - -1. "Are you building a monolith, microservices, or serverless architecture?" -2. Based on answer, dive deeper: - - **If Monolith:** "How will you structure the codebase? Any module boundaries?" - - **If Microservices:** "What are your service boundaries? How will they communicate?" - - **If Serverless:** "What functions/lambdas? What triggers them?" -3. **Business Rules to Capture:** - - Deployment patterns - - Service boundaries and responsibilities - - Communication protocols - -**2C: Infrastructure & Hosting** - -Ask systematically: - -1. "What cloud provider or hosting platform?" -2. "Any specific infrastructure services needed?" (CDN, load balancers, etc.) -3. "What's your deployment approach?" (containers, VMs, serverless) -4. **Business Rules to Capture:** - - Geographic regions/data residency - - Disaster recovery requirements - - Cost constraints - -**2D: Platform Requirements & Standards** - -Ask systematically about critical platform concerns: - -1. **Accessibility:** - - "What accessibility standards do you need to meet?" (WCAG 2.1 Level AA, etc.) - - "Who are your accessibility-dependent users?" (screen reader users, keyboard-only, etc.) - - **Business Rules to Capture:** - - WCAG compliance level required - - Keyboard navigation requirements - - Screen reader compatibility - - Color contrast standards - - Alt text and ARIA label policies - -2. **Internationalization & Localization:** - - "What languages/regions do you need to support?" - - "Are there currency, date, or number format requirements?" - - **Business Rules to Capture:** - - Supported languages and locales - - RTL (right-to-left) language support - - Translation management approach - - Regional data formats - -3. **Browser & Device Compatibility:** - - "What browsers and versions must you support?" - - "What devices?" (desktop, mobile, tablet) - - "Any specific OS requirements?" - - **Business Rules to Capture:** - - Minimum browser versions - - Mobile responsiveness requirements - - Tablet-specific considerations - - Progressive web app (PWA) capabilities - -4. **Monitoring & Observability:** - - "What monitoring and logging do you need?" - - "Error tracking? Performance monitoring?" - - **Business Rules to Capture:** - - Logging level requirements - - Error tracking service - - Performance monitoring tools - - Uptime monitoring - - Alert thresholds - -**2E: Performance & Scale** - -Ask systematically: - -1. "What are your performance requirements?" - - Expected response times? - - How many concurrent users? - - Peak load expectations? -2. "What's your availability target?" (99%, 99.9%, 99.99%?) -3. "Any scalability concerns?" -4. **Business Rules to Capture:** - - SLA requirements - - Peak usage patterns - - Growth projections - -**After completing all sections:** - -"Let me summarize what we've covered for platform architecture... [summarize key points]" - -**Ask:** "Is there anything about the platform or infrastructure we should add? Any constraints or requirements we missed?" - -**Output:** Create `00-Platform-Architecture.md` using the template, incorporating all documented answers. - ---- - -### Step 3: Integration Mapping - -**Goal:** Systematically identify all external dependencies through intelligent, context-aware discussion. - -**Freya's Approach:** - -"Let me review your Product Brief to understand which integrations you'll likely need, then we'll go through each relevant category systematically." - -**First: Analyze Product Brief** - -Read the Product Brief and identify relevant integration categories based on features mentioned: - -- **Payment Processing:** Transactions, subscriptions, e-commerce, paid features, pricing -- **Communication:** User notifications, emails, SMS, alerts, reminders -- **Maps/Location:** Geographic features, addresses, directions, proximity, location-based services -- **Search:** Large content volumes, filtering, discovery features -- **Calendar/Scheduling:** Bookings, appointments, events, availability -- **Social Media:** Sharing, social login, content from social platforms -- **Analytics:** User tracking, behavior analysis, conversion tracking -- **Storage/Media:** File uploads, images, videos, documents -- **Customer Support:** Help features, ticketing, live chat -- **Authentication:** User accounts, SSO, enterprise login -- **Domain-Specific:** Industry-specific services mentioned - -**Present Relevant Categories:** - -"Based on your Product Brief, I've identified these integration categories that seem relevant:" - -[List only applicable categories with reasons from brief] - -"Let's go through each of these, then check if there are others you need." - ---- - -**Go through each relevant category systematically:** - -**3A: Authentication & Identity** - -- "How will users authenticate?" (OAuth, email/password, SSO, passwordless) -- "Which providers?" (Google, Microsoft, Auth0, etc.) -- **Document for each:** - - Service name & purpose - - Business rules (token lifetime, MFA requirements) - - Priority (must-have/nice-to-have) - - Cost estimate - - Technical risk (high/medium/low) - -**3B: Payment Processing** (if applicable) - -- "Do you need payment processing?" -- "Which payment providers?" (Stripe, PayPal, Klarna, Swish, regional systems) -- "What payment methods?" (credit cards, bank transfers, mobile payments, digital wallets) -- "What currencies do you need to support?" -- "Do you need subscription/recurring billing?" -- **Document for each:** - - Service name & purpose - - **Business rules:** - - Supported payment methods - - Currency handling - - Refund policies and workflows - - Failed payment retry logic - - Subscription management (if applicable) - - Tax calculation and collection - - Invoice generation requirements - - Payment confirmation/receipt delivery - - **Compliance needs:** PCI-DSS requirements - - **Integration complexity:** Webhooks, payment status tracking - - Priority & cost (transaction fees, monthly costs) - - Technical risk level - -**3C: Communication Services** - -- "Do you need to send emails?" → Which service? (SendGrid, Mailgun, AWS SES, Postmark) -- "Do you need SMS?" → Which service? (Twilio, MessageBird, Vonage) -- "Push notifications?" → Which service? (Firebase Cloud Messaging, OneSignal, Pusher) -- "In-app messaging or chat?" → Which service? (Twilio, Stream, PubNub) -- **Document for each:** - - Service name & purpose - - **Business rules:** - - Message templates and customization - - Delivery guarantees and retries - - Opt-out/unsubscribe handling - - Bounce and complaint management - - Multi-language support - - Transactional vs marketing messages - - Volume estimates (messages per month) - - Priority & cost - -**3D: Search Services** (if applicable) - -- "Do you need advanced search functionality?" -- "Which service?" (Algolia, Elasticsearch, Typesense, Meilisearch) -- **Document for each:** - - Service name & purpose - - **Business rules:** - - What needs to be searchable? - - Faceted search requirements - - Auto-complete/type-ahead needs - - Search result ranking logic - - Filter and sort options - - Multi-language search - - Index size estimates - - Query volume expectations - - Priority & cost - -**3E: Maps & Location** (if applicable) - -- "Do you need maps or geolocation?" -- "Which service?" (Google Maps, Mapbox, OpenStreetMap, Here) -- **Document for each:** - - Service name & purpose - - **Business rules:** - - Geocoding (address → coordinates) - - Reverse geocoding (coordinates → address) - - Route calculation - - Distance/duration estimation - - Map display and interaction - - Geofencing requirements - - API call limits and caching strategy - - Accuracy requirements - - Expected API call volume - - Cost per API call - - Priority & risk level - -**3F: Data & Analytics** - -- "What analytics do you need?" (Google Analytics, Mixpanel, Amplitude, custom) -- "Error tracking?" (Sentry, Rollbar, Bugsnag) -- "Application monitoring?" (New Relic, Datadog, AppDynamics) -- "User session recording?" (FullStory, Hotjar, LogRocket) -- **Document for each:** - - Service name & purpose - - **Business rules:** - - Events to track - - User privacy considerations - - Data retention policies - - GDPR compliance for tracking - - Custom dashboards/reports needed - - Data volume estimates - - Priority & cost - -**3G: Storage & Media** - -- "Do you need file/image storage?" (S3, Azure Blob, Google Cloud Storage, Cloudinary) -- "CDN for assets?" (CloudFlare, Fastly, AWS CloudFront) -- "Video hosting/streaming?" (Vimeo, YouTube, Mux, AWS Media Services) -- "Document processing?" (PDF generation, document conversion) -- **Document for each:** - - Service name & purpose - - **Business rules:** - - File size limits - - Supported file types - - Image/video processing (resizing, transcoding) - - Retention policies and backup - - Access control (public/private) - - Virus scanning requirements - - Volume estimates (storage, bandwidth) - - Priority & cost - -**3H: Calendar & Scheduling** (if applicable) - -- "Do you need calendar integrations?" -- "Which services?" (Google Calendar, Outlook/Microsoft 365, iCal) -- "Scheduling/booking systems?" (Calendly-style booking) -- **Document for each:** - - Service name & purpose - - **Business rules:** - - Event creation and updates - - Availability checking - - Timezone handling - - Recurring events - - Reminders and notifications - - Priority & cost - -**3I: Social Media & Content** (if applicable) - -- "Do you need social media integrations?" -- "Which platforms?" (Facebook, Twitter/X, LinkedIn, Instagram) -- "Social login?" (covered in 3A, but cross-reference) -- "Content sharing?" (Open Graph, Twitter Cards) -- **Document for each:** - - Service name & purpose - - **Business rules:** - - What data to fetch/post - - Authentication flow - - Rate limits - - Content moderation needs - - Priority & cost - -**3J: Customer Support & Help** (if applicable) - -- "Do you need customer support tools?" -- "Which services?" (Intercom, Zendesk, Helpscout, Crisp) -- "Live chat?" (service or custom) -- "Knowledge base/docs?" (service or custom) -- **Document for each:** - - Service name & purpose - - **Business rules:** - - User identification and context - - Ticket creation workflow - - SLA requirements - - Multi-language support - - Priority & cost - -**3K: Marketing & Growth** (if applicable) - -- "Do you need marketing automation?" -- "Which services?" (Mailchimp, HubSpot, ActiveCampaign) -- "A/B testing?" (Optimizely, VWO, custom) -- "Feature flags?" (LaunchDarkly, Flagsmith, custom) -- **Document for each:** - - Service name & purpose - - **Business rules:** - - Audience segmentation - - Campaign triggers - - Testing methodology - - Rollout strategies - - Priority & cost - -**3L: Domain-Specific APIs** - -- "Any other APIs specific to your domain?" (industry-specific services) -- Examples: Weather APIs, financial data, shipping/logistics, government data, industry databases -- **Document for each:** - - Service name & purpose - - Business rules & constraints - - Data format requirements - - Priority & risk level - -**After completing all categories:** - -"Let me list all the external services we've identified... [summarize]" - -**Ask:** "Are there any other external services, APIs, or integrations we should include? Anything we missed?" - -**Output:** Create `01-Integration-Map.md` with all services categorized and documented. - ---- - -### Step 4: Identify Features Needing Technical Validation - -**Goal:** Determine which features need Proofs of Concept (PoCs). - -Review the Feature Impact Analysis and ask: - -- **Which features are innovative or unproven?** -- **Which features depend on external APIs that might have limitations?** -- **Which features have unknown performance characteristics?** -- **Which features might not be technically feasible?** - -**Red Flags That Suggest PoC Needed:** - -- "Can we actually get X data from Y service?" -- "Will this perform fast enough?" -- "Does this API return data in a usable format?" -- "Can we achieve real-time updates at scale?" - -Create a list of features requiring validation, prioritized by: - -1. **High Feature Impact Score** (from Phase 2) + **High Technical Risk** -2. **Medium Feature Impact** + **High Technical Risk** -3. **High Feature Impact** + **Medium Technical Risk** - ---- - -### Step 5: Technical Proofs of Concept (PoCs) - -**Goal:** Validate that risky features are technically feasible. - -For each feature identified in Step 4: - -1. **Define the Question:** - - What exactly needs to be proven? - - Example: "Can we get walking time between two coordinates from Google Maps API?" - -2. **Create or Request PoC:** - - If development team is available: Assign PoC task - - If conducting PoC now: Guide user through quick validation - - Document the approach taken - -3. **Document Results:** - - **Status:** ✅ Proven / ⚠️ Limited / ❌ Not Feasible - - **Findings:** What worked, what didn't - - **Limitations:** Edge cases, performance concerns, cost implications - - **Recommendation:** Go / No-Go / Modify Feature - -4. **Code Snippets:** Include working code examples when possible - -**Output:** Create `02-Technical-Proofs-Of-Concept.md` documenting all PoC work. - -**Positive Framing:** - -- When features work: "Great! This proves [feature] is technically sound. Design can proceed with confidence." -- When features have limitations: "Valuable discovery! We found [limitation] early. This helps design account for it from the start." -- When features don't work: "Important learning! This saves weeks of design work on an infeasible feature. Let's explore alternatives." - ---- - -### Step 6: Security & Compliance Framework - -**Goal:** Systematically define security, authentication, and compliance through detailed discussion. - -**Freya's Approach:** - -"Security is critical. Let's go through each security area methodically and document all business rules and requirements." - -**6A: Authentication** - -Ask systematically: - -1. "How will users authenticate?" (List options: email/password, OAuth, SSO, passwordless, biometric) -2. "Do you need multi-factor authentication?" -3. "What's your session management approach?" - - Session lifetime? - - Remember me functionality? - - Concurrent session handling? -4. **Business Rules to Capture:** - - Password requirements (length, complexity, expiration) - - Account lockout policies - - Password reset flow - - Session timeout rules - -**6B: Authorization** - -Ask systematically: - -1. "What user roles do you need?" (List them: admin, user, moderator, etc.) -2. "What can each role do?" (Go through each role) -3. "Do you need row-level security?" (Can users only see their own data?) -4. "How will API access be controlled?" -5. **Business Rules to Capture:** - - Permission matrix (role × action) - - Data visibility rules - - API rate limiting per role - - Admin capabilities and restrictions - -**6C: Data Protection** - -Ask systematically: - -1. "What sensitive data needs encryption at rest?" - - Passwords? (always yes) - - Personal information? - - Payment data? - - Other sensitive fields? -2. "TLS/HTTPS for all traffic?" (should be yes) -3. "What's your backup strategy?" - - Backup frequency? - - Retention period? - - Recovery time objective (RTO)? - - Recovery point objective (RPO)? -4. **Business Rules to Capture:** - - Encryption algorithms - - Key management approach - - Data deletion policies (right to be forgotten) - - Backup and recovery procedures - -**6D: Compliance & Regulations** - -Ask systematically about all regulatory requirements: - -1. **GDPR (EU General Data Protection Regulation):** - - "Do you have EU users or process EU citizen data?" - - If yes, document requirements: - - **Consent Management:** - - Cookie consent mechanism - - Data processing consent - - Consent withdrawal process - - **User Rights:** - - Right to access (data export) - - Right to deletion (right to be forgotten) - - Right to rectification (data correction) - - Right to data portability - - Right to object to processing - - **Data Protection:** - - Privacy policy requirements - - Data processing agreements - - Data breach notification procedures (72-hour rule) - - Data Protection Impact Assessment (DPIA) needs - - **Business Rules to Capture:** - - Consent storage and tracking - - Data retention periods - - Data deletion workflows - - User data export format - - Third-party data processor agreements - -2. **Other Privacy Regulations:** - - "Are you subject to CCPA (California)?" → California Consumer Privacy Act requirements - - "HIPAA (Healthcare)?" → Health data protection standards - - "PCI-DSS (Payments)?" → Payment card data security - - "COPPA (Children)?" → Children's online privacy protection - - **Business Rules for each applicable regulation** - -3. **Data Residency & Sovereignty:** - - "Must data stay in specific geographic regions?" - - "Any country-specific data laws?" - - **Business Rules to Capture:** - - Data storage location requirements - - Cross-border data transfer restrictions - - Regional compliance needs - -4. **Industry-Specific Regulations:** - - "Any industry-specific compliance?" (Financial, healthcare, education, etc.) - - **Business Rules to Capture:** - - Specific regulatory requirements - - Compliance documentation needs - - Regular audit requirements - -5. **Audit Logging & Compliance Tracking:** - - "Do you need audit trails for compliance?" - - "What actions must be logged?" - - **Business Rules to Capture:** - - Events requiring audit logs (user actions, data access, changes) - - Log retention period (often 7 years for compliance) - - Who can access audit logs - - Tamper-proof logging requirements - - Regular compliance reporting needs - -**After completing all security areas:** - -"Let me summarize our security framework... [summarize key points]" - -**Ask:** "Is there anything about security, privacy, or compliance we should add? Any requirements or constraints we missed?" - -**Output:** Create `03-Security-Framework.md` with all security rules and requirements documented. - ---- - -### Step 7: API Specifications (API-First Design) - -**Goal:** Define comprehensive API contracts through systematic category-by-category discussion. - -**Freya explains:** - -"We're taking an API-first approach. By defining clear service contracts now, we enable backend development to proceed in parallel with UX design. These APIs will serve as the foundation for all future UI work." - -**7A: Authentication APIs** - -"Let's start with authentication. Based on our security framework, what auth endpoints do you need?" - -For each endpoint: - -- Method & Path (e.g., `POST /api/auth/login`) -- Purpose & business value -- Request/response format with detailed schemas -- **Business Rules:** - - Token lifetime & refresh behavior - - Error responses (invalid credentials, locked account, etc.) - - Security requirements (HTTPS, rate limiting, etc.) -- Status (planned/in-progress/complete) - -Common auth endpoints: login, logout, token refresh, password reset, email verification - -**7B: Core Entity APIs (CRUD Operations)** - -"Now let's define APIs for your main data entities." - -Go through each entity from the data model systematically: - -For each entity, define all CRUD operations: - -- `GET /api/{entity}` - List with pagination -- `GET /api/{entity}/:id` - Get single item -- `POST /api/{entity}` - Create new -- `PUT /api/{entity}/:id` - Update existing -- `DELETE /api/{entity}/:id` - Delete item - -**Business Rules for each:** - -- Validation rules (required fields, formats, constraints) -- Authorization (who can perform this operation?) -- Pagination parameters (page size, sorting, filtering) -- Related data inclusion (nested objects, joins) -- Business logic constraints - -**7C: External Integration APIs** - -"Which external services need API endpoints? Let's create wrappers for each." - -For each external service from Step 3: - -- Method & Path -- Purpose ("Wraps Google Maps API to get walking time") -- Request/response format -- **Business Rules:** - - Pre-call validation - - Caching strategy - - Fallback behavior on external failure - - Rate limiting - - Cost tracking per call -- External service dependencies - -**7D: Business Logic APIs** - -"What calculations or business operations need dedicated endpoints?" - -Examples: availability checks, pricing, recommendations, aggregations - -For each: - -- Method & Path -- Purpose & business value -- Request/response format -- **Business Rules:** - - Calculation logic - - Data sources - - Edge cases & error handling - - Performance expectations -- Dependencies - -**After defining all APIs:** - -"Let me summarize the API surface... [list by category]" - -**Ask:** "Are there any other API operations we should include? Any data needs we forgot?" - -**Output:** Create `04-API-Specifications.md` with complete service contracts. - ---- - -### Step 8: Data Models & Performance Requirements - -**Goal:** Document database schemas and performance benchmarks. - -**Freya's Approach:** - -"Let's formalize the data model and set clear performance expectations." - -**8A: Data Models** - -"We identified your core entities earlier. Now let's document the complete data model." - -For each entity: - -- Entity name & purpose -- All fields with types, constraints, defaults -- Relationships to other entities (one-to-many, many-to-many) -- Indexes for performance -- **Business Rules:** - - Data validation rules - - Required vs. optional fields - - Unique constraints - - Cascade delete behavior - - Audit trail needs - -Create entity relationship diagram (ERD) showing all connections. - -**8B: Performance Requirements** - -"What are your performance and scalability expectations?" - -Document systematically: - -- **Response Times:** Expected latency for each API category -- **Throughput:** Concurrent users, requests per second -- **Data Volume:** Expected record counts, storage needs -- **Availability:** Uptime requirements (99%, 99.9%, 99.99%?) -- **Scalability:** Growth projections and scaling triggers - -**Ask:** "Any other data modeling or performance considerations we should capture?" - -**Outputs:** - -- `05-Data-Models.md` - Complete schemas and ERD -- `06-Performance-Requirements.md` - Benchmarks and scalability specs - ---- - -### Step 9: Technical Constraints & Acceptance Criteria - -**Goal:** Create UX design handoff document and define success criteria. - -**9A: Technical Constraints Document** - -"This document tells the UX team what they need to know about technical possibilities and limitations." - -**Include:** - -- **What's Possible:** Validated features from PoCs, platform capabilities -- **What Has Limitations:** Technical constraints, API limits, performance characteristics -- **What Affects Design:** Loading states, offline behavior, real-time vs. polling -- **What's Expensive:** Cost-sensitive features requiring careful UX - -**9B: Acceptance Criteria** - -"How do we know when each platform component is 'done'?" - -For each major platform area (auth, integrations, security, etc.): - -- **Functional Criteria:** What must work? -- **Performance Criteria:** How fast/scalable must it be? -- **Security Criteria:** What security standards must be met? -- **Testing Criteria:** What tests must pass? - -**Ask:** "Any other constraints or success criteria we should document?" - -**Outputs:** - -- `07-Technical-Constraints.md` - UX design handoff -- `08-Acceptance-Criteria.md` - Testable success definitions - ---- - -### Step 10: Platform Backlog Recommendations - -**Goal:** Recommend platform infrastructure work for BMM to organize into epics and stories, prioritized by Feature Impact Analysis. - -**Freya explains:** - -"Based on all the technical requirements we've documented AND the Feature Impact Analysis from Phase 2, let me suggest how this platform work could be organized for development. We'll prioritize platform work that enables your highest-impact features first." - -**10A: Review Feature Impact Analysis** - -"Let's look at your high-priority features from Phase 2..." - -Read the Feature Impact Analysis (B-Trigger-Map/03-Feature-Impact-Analysis.md) and identify: - -- **Must Have features** (high scores, high for primary persona) -- **Consider for MVP features** (balanced scores) -- **Platform dependencies** - What platform work is needed to enable each high-impact feature? - -**10B: Identify Recommended Initiatives & Epics** - -"Based on your Feature Impact Analysis and technical requirements, here are the major platform initiatives I recommend:" - -For each recommended epic, note which high-priority features it enables: - -**Initiative: Platform Foundation** - -- **Epic: Trusted User Access** (Authentication & user management) - - Suggested from: Security Framework, API Specifications (auth endpoints) - - **Enables features:** [List high-impact features requiring authentication] - - **Feature Impact scores:** [Reference specific features from Phase 2] - - Business value: Enable secure user access and identity management - - Key deliverables: Auth system, user management, session handling - -- **Epic: [External Service] Integration** (One per major integration) - - Suggested from: Integration Map, API Specifications (integration endpoints) - - **Enables features:** [List high-impact features requiring this integration] - - **Feature Impact scores:** [Reference specific features from Phase 2] - - Business value: Connect to [service] to enable [specific high-priority features] - - Key deliverables: Service integration, error handling, data sync - -- **Epic: Data Platform Foundation** (Database, models, synchronization) - - Suggested from: Data Models, Performance Requirements - - **Enables features:** [List high-impact features requiring data storage] - - **Feature Impact scores:** [Reference specific features from Phase 2] - - Business value: Reliable data storage and access for all features - - Key deliverables: Database setup, schema implementation, migrations - -- **Epic: Enterprise Security & Compliance** - - Suggested from: Security Framework, Acceptance Criteria - - **Enables features:** [Security-dependent features] - - Business value: Meet security and compliance requirements - - Key deliverables: Encryption, audit logging, compliance controls - -- **Epic: High-Performance Infrastructure** - - Suggested from: Performance Requirements, Platform Architecture - - **Enables features:** [Performance-sensitive features from Phase 2] - - Business value: Scalable, responsive system that meets performance targets - - Key deliverables: Caching, optimization, monitoring - -**10C: Recommended Development Sequence (Priority-Driven)** - -"Here's the order I'd recommend, based on Feature Impact Analysis:" - -**Priority 1: Enable Must-Have Features** - -1. **Foundation First:** Core infrastructure (hosting, database, basic security) -2. **High-Impact Dependencies:** Platform work needed for Must-Have features - - [Epic] enables [Feature] (Score: X) for [Primary Persona] - - [Epic] enables [Feature] (Score: Y) for [Primary Persona] - -**Priority 2: Risk Mitigation** 3. **Complex Integrations:** External APIs that are risky or complex (fail fast) - -- [Integration Epic] enables [Feature] (Score: X) - -**Priority 3: Secondary Features** 4. **Remaining Integrations:** Other external services 5. **Advanced Features:** Performance optimization, advanced security - -**Priority 4: Operations** 6. **Monitoring & Tools:** Logging, analytics, maintenance tools - -**10D: Feature-to-Epic Mapping** - -"Here's how each high-priority feature maps to platform work:" - -Create a table: -| Feature (from Phase 2) | Score | Priority | Required Platform Epics | Notes | -|------------------------|-------|----------|-------------------------|-------| -| [Feature Name] | 7 | Must Have | Trusted User Access, Data Platform | Needs auth + storage | -| [Feature Name] | 7 | Must Have | [Integration] Epic, Data Platform | Critical integration | -| [Feature Name] | 5 | Must Have | Data Platform, High-Performance | Primary persona critical | - -**10E: API Contracts for Future UI Development** - -"These API specifications are ready for frontend development:" - -- [List key API categories organized by priority features they enable] -- Backend can implement these in parallel with Phase 4 (UX Design) - -**10F: Dependencies & Parallel Work** - -"Key dependencies to consider:" - -- What must be done before high-impact features can be built? -- What can be developed independently in parallel? -- What provides the most risk reduction AND feature enablement if done early? - -**Ask:** "Does this platform work organization make sense based on your feature priorities? Any initiatives or priorities you'd adjust?" - -**Output:** Create `09-Platform-Backlog-Recommendations.md` with: - -- **Feature Impact Summary** - High-priority features from Phase 2 -- **Feature-to-Epic Mapping** - Clear connections between features and platform work -- Recommended initiative structure -- Suggested epic breakdown with business value statements -- **Priority-driven development sequence** - Based on Feature Impact Analysis -- Dependencies and parallel work opportunities -- API contract readiness for future UI -- Notes for BMM agents on implementation approach - -**Handoff to BMM:** "These recommendations, informed by your Feature Impact Analysis, will guide BMM agents when they create the actual E-Backlog/ structure with detailed epics and stories. They'll know exactly which platform work enables your highest-value features." - ---- - -### Step 11: Finalize the PRD - -**Goal:** Create the master PRD that references all Phase 3 work. - -**Freya explains:** - -"The PRD is your single source of truth. It starts here with technical foundation and will grow during Phase 4 as functional requirements are added from UX design." - -**PRD Structure:** - -```markdown -# Product Requirements Document: [Project Name] - -_Phase 3 Complete: Technical Foundation Established_ -_Last Updated: [Date]_ - ---- - -## 1. Executive Summary - -[Link to Product Brief from Phase 1] -[Link to Trigger Map from Phase 2] - ---- - -## 2. Technical Foundation (Phase 3) - -### 2.1 Platform Architecture - -[Link to C-Requirements/00-Platform-Architecture.md] - -### 2.2 External Integrations - -[Link to C-Requirements/01-Integration-Map.md] - -### 2.3 Technical Validation - -[Link to C-Requirements/02-Technical-Proofs-Of-Concept.md] - -### 2.4 Security & Compliance - -[Link to C-Requirements/03-Security-Framework.md] - -### 2.5 API Specifications - -[Link to C-Requirements/04-API-Specifications.md] - -### 2.6 Data Models - -[Link to C-Requirements/05-Data-Models.md] - -### 2.7 Performance Requirements - -[Link to C-Requirements/06-Performance-Requirements.md] - -### 2.8 Technical Constraints - -[Link to C-Requirements/07-Technical-Constraints.md] - -### 2.9 Acceptance Criteria - -[Link to C-Requirements/08-Acceptance-Criteria.md] - ---- - -## 3. Platform Backlog Recommendations - -[Link to C-Requirements/09-Platform-Backlog-Recommendations.md] - -**Summary:** - -- **Recommended Initiatives:** [List] -- **Suggested Epics:** [Count] -- **API Contracts Ready:** [Key APIs] -- **Ready for BMM:** Platform requirements complete for backlog creation - ---- - -## 4. Functional Requirements (Phase 4) - -_This section will be populated during Phase 4 (UX Design) as each page/scenario is completed._ - -### [Feature Area 1] - -_Coming from Phase 4_ - -### [Feature Area 2] - -_Coming from Phase 4_ - ---- - -## 5. Next Steps - -**For BMM Agents:** - -- Use platform backlog recommendations to create E-Backlog/ structure -- Create detailed epics and stories from requirements documents -- Establish implementation roadmap with dependencies - -**For Phase 4 (UX Design):** - -- Technical constraints document provides design boundaries -- API specifications define data available to UI -- Begin UX design with confidence in technical feasibility - ---- - -## 6. Change Log - -- [Date] - Phase 3 complete: Technical foundation established -- [Date] - Platform backlog recommendations provided for BMM -``` - -**Output:** Create `C-Requirements/10-PRD.md` - ---- - -### Step 12: Summary and Completeness Check - -**Freya congratulates the user:** - -"Excellent work! We've systematically documented your technical foundation. Let me summarize what we've created:" - -**Review each document:** - -1. ✅ **Platform Architecture** - Technology stack, infrastructure, data model -2. ✅ **Integration Map** - All external services with business rules -3. ✅ **Technical Proofs of Concept** - Validated risky features -4. ✅ **Security Framework** - Authentication, authorization, compliance rules -5. ✅ **API Specifications** - Service contracts for all endpoints (API-first) -6. ✅ **Data Models** - Complete schemas and ERD -7. ✅ **Performance Requirements** - Scalability and benchmarks -8. ✅ **Technical Constraints** - What UX design needs to know -9. ✅ **Acceptance Criteria** - Success definitions -10. ✅ **Platform Backlog Recommendations** - Suggested work organization for BMM -11. ✅ **PRD Initialized** - Ready to grow in Phase 4 - -**Completeness Check:** - -"Before we finish, let's make sure we haven't missed anything important:" - -**Ask systematically:** - -1. **"Looking at your platform architecture - is there any technology choice, constraint, or requirement we didn't discuss?"** - -2. **"For integrations - are there any external services, APIs, or third-party tools we forgot to include?"** - -3. **"Thinking about security - any authentication flows, data protection needs, or compliance requirements we should add?"** - -4. **"For API specifications - any endpoints, data operations, or service contracts we missed?"** - -5. **"Looking at the platform backlog recommendations - any initiatives, epics, or priorities we should adjust before handing off to BMM?"** - -6. **"Are there any business rules, limitations, or requirements that came to mind as we went through this that we should document somewhere?"** - -7. **"Anything about performance, scalability, or deployment we should capture?"** - -**If user identifies gaps:** - -- Document the additional items in the appropriate files -- "Great catch! Let me add that to [relevant document]..." -- After adding, return to completeness check - -**When user confirms nothing missing:** - -"Perfect! Your technical foundation is solid and complete." - -**Parallel Workflows Enabled:** - -"With Phase 3 complete, multiple work streams can now proceed:" - -1. **BMM Backlog Creation:** - - BMM agents use platform backlog recommendations - - Create E-Backlog/ structure with detailed epics and stories - - Establish implementation roadmap - -2. **Backend/Platform Development:** - - Infrastructure setup can begin - - API endpoints can be implemented - - Database schema can be created - - External integrations can be configured - -3. **Phase 4: UX Design:** - - Design work proceeds with confidence about technical feasibility - - Technical constraints inform design decisions - - Each completed page will add functional requirements to the PRD - -**What happens next:** - -- Platform backlog recommendations guide BMM agents in creating E-Backlog/ -- Development teams can begin platform work based on requirements -- Phase 4 (UX Design) can begin, informed by technical constraints - -**Ask:** "Would you like to proceed to Phase 4 (UX Design) now, hand off to BMM for backlog creation, or need time for backend development planning?" - ---- - -## Tips for Great Sessions - -### For Freya the PM: - -**Validate Early, Often:** - -- Don't let risky features proceed without PoC validation -- "Let's prove this works before investing in design" - -**Positive Language:** - -- Frame discoveries as valuable, not failures -- "Great that we learned this now, not after design is complete" - -**Stay Connected to Strategy:** - -- Reference Feature Impact Analysis scores when prioritizing PoCs -- High-impact features deserve thorough validation - -**Enable Parallel Work:** - -- Think about what backend teams can start building immediately -- Experimental endpoints should focus on clear, achievable tasks - -**Document for Design:** - -- Technical Constraints doc is crucial for Phase 4 success -- Be specific about what design needs to accommodate - ---- - -## Template Files - -Use these templates to structure outputs: +- Product Brief (Phase 1) +- Trigger Map with Feature Impact Analysis (Phase 2) +- Development team availability (for PoC work if needed) + +## Steps + +Follow each step file in sequence from the `steps/` directory: + +1. **[step-01-welcome](steps/step-01-welcome.md)** — Welcome and context review +2. **[step-02-platform-architecture](steps/step-02-platform-architecture.md)** — Technology stack, infrastructure, standards +3. **[step-03-integration-mapping](steps/step-03-integration-mapping.md)** — External services and dependencies +4. **[step-04-technical-validation](steps/step-04-technical-validation.md)** — Feature validation and PoCs +5. **[step-05-security-framework](steps/step-05-security-framework.md)** — Authentication, authorization, compliance +6. **[step-06-api-specifications](steps/step-06-api-specifications.md)** — API-first service contracts +7. **[step-07-data-and-performance](steps/step-07-data-and-performance.md)** — Data models, performance, constraints, acceptance criteria +8. **[step-08-backlog-recommendations](steps/step-08-backlog-recommendations.md)** — Priority-driven platform work for BMM +9. **[step-09-prd-finalization](steps/step-09-prd-finalization.md)** — Master PRD document +10. **[step-10-summary](steps/step-10-summary.md)** — Completeness check and next steps + +## Outputs + +By completion, `C-Requirements/` will contain: + +| # | Document | Purpose | +|---|----------|---------| +| 00 | Platform-Architecture.md | Technology stack and infrastructure | +| 01 | Integration-Map.md | External services and connections | +| 02 | Technical-Proofs-Of-Concept.md | Validated risky features | +| 03 | Security-Framework.md | Auth, authorization, compliance | +| 04 | API-Specifications.md | Service contracts (API-first) | +| 05 | Data-Models.md | Schemas and relationships | +| 06 | Performance-Requirements.md | Scalability and benchmarks | +| 07 | Technical-Constraints.md | UX design handoff | +| 08 | Acceptance-Criteria.md | Testable success definitions | +| 09 | Platform-Backlog-Recommendations.md | Suggested epics for BMM | +| 10 | PRD.md | Product Requirements Document | + +## Templates - `templates/platform-architecture.template.md` - `templates/technical-constraints.template.md` - `templates/experimental-endpoints.template.md` - ---- - -_Phase 3 workflow for Whiteport Design Studio (WDS) methodology_ diff --git a/src/workflows/3-prd-platform/steps/step-01-welcome.md b/src/workflows/3-prd-platform/steps/step-01-welcome.md new file mode 100644 index 000000000..bcd892a58 --- /dev/null +++ b/src/workflows/3-prd-platform/steps/step-01-welcome.md @@ -0,0 +1,52 @@ +# Step 1: Welcome and Context Review + +## Purpose + +Greet user and establish context for Phase 3 — the technical foundation. + +## Context for Agent + +You are Idunn, guiding the user through establishing the technical platform. This phase proves technical feasibility in parallel with design work. + +## Key Elements + +By the end of this phase, the `C-Requirements/` folder will contain: + +1. **00-Platform-Architecture.md** - Technology stack and infrastructure +2. **01-Integration-Map.md** - External services and connections +3. **02-Technical-Proofs-Of-Concept.md** - Validation of risky features +4. **03-Security-Framework.md** - Authentication, authorization, compliance +5. **04-API-Specifications.md** - Service contracts and endpoints (API-first) +6. **05-Data-Models.md** - Database schemas and relationships +7. **06-Performance-Requirements.md** - Scalability and benchmarks +8. **07-Technical-Constraints.md** - What UX design needs to know +9. **08-Acceptance-Criteria.md** - Testable success definitions +10. **09-Platform-Backlog-Recommendations.md** - Suggested epics for BMM +11. **10-PRD.md** - Product Requirements Document (grows in Phase 4) + +## Prerequisites + +- Product Brief (Phase 1) +- Trigger Map with Feature Impact Analysis (Phase 2) +- Development team availability (for PoC work if needed) + +## Instructions + +1. Greet the user and explain this phase: + - "We're establishing your technical foundation — proving innovative features work before investing in design." + - "This enables backend development to start in parallel with UX design." + +2. Review available context: + - Read Product Brief to understand project scope and constraints + - Read Feature Impact Analysis to identify high-priority features + - Ask: "Do you already have any technical constraints or platform preferences?" + +## Next Step + +When user confirms readiness, proceed to step-02-platform-architecture.md + +## State Update + +```yaml +stepsCompleted: ['step-01-welcome.md'] +``` diff --git a/src/workflows/3-prd-platform/steps/step-02-platform-architecture.md b/src/workflows/3-prd-platform/steps/step-02-platform-architecture.md new file mode 100644 index 000000000..9e0768f78 --- /dev/null +++ b/src/workflows/3-prd-platform/steps/step-02-platform-architecture.md @@ -0,0 +1,72 @@ +# Step 2: Platform Architecture Decisions + +## Purpose + +Define the technology stack and infrastructure through systematic discussion. + +## Context for Agent + +Walk through each major technical area, document decisions, business rules, and constraints as you go. + +## Instructions + +"Let's establish your technical foundation. I'll walk through each major area." + +### 2A: Technology Stack + +Ask each question and document the answer: + +1. **Backend:** + - "What backend framework/language are you using? Why?" + - Capture: Language version, framework patterns, performance needs + +2. **Frontend:** + - "What frontend framework? Any UI library?" + - Capture: Browser support, mobile responsiveness, accessibility standards + +3. **Database:** + - "What database system(s)? What are your core data entities?" + - Capture: Data retention, backup/recovery, consistency needs + +### 2B: Architecture Style + +1. "Monolith, microservices, or serverless?" +2. Dive deeper based on answer (module boundaries, service boundaries, or function triggers) +3. Capture: Deployment patterns, service responsibilities, communication protocols + +### 2C: Infrastructure & Hosting + +1. "What cloud provider or hosting platform?" +2. "Specific infrastructure services needed?" (CDN, load balancers, etc.) +3. "Deployment approach?" (containers, VMs, serverless) +4. Capture: Geographic regions, disaster recovery, cost constraints + +### 2D: Platform Requirements & Standards + +1. **Accessibility:** WCAG level, keyboard nav, screen readers, ARIA policies +2. **Internationalization:** Languages, RTL support, regional formats +3. **Browser/Device Compatibility:** Minimum versions, mobile, tablet, PWA +4. **Monitoring:** Logging, error tracking, performance monitoring, alert thresholds + +### 2E: Performance & Scale + +1. "Performance requirements?" (response times, concurrent users, peak load) +2. "Availability target?" (99%, 99.9%, 99.99%?) +3. "Scalability concerns?" +4. Capture: SLA requirements, peak patterns, growth projections + +## After All Sections + +Summarize key points and ask: "Anything about platform or infrastructure we should add?" + +**Output:** Create `00-Platform-Architecture.md` using the template. + +## Next Step + +Proceed to step-03-integration-mapping.md + +## State Update + +```yaml +stepsCompleted: ['step-01-welcome.md', 'step-02-platform-architecture.md'] +``` diff --git a/src/workflows/3-prd-platform/steps/step-03-integration-mapping.md b/src/workflows/3-prd-platform/steps/step-03-integration-mapping.md new file mode 100644 index 000000000..d11df5181 --- /dev/null +++ b/src/workflows/3-prd-platform/steps/step-03-integration-mapping.md @@ -0,0 +1,81 @@ +# Step 3: Integration Mapping + +## Purpose + +Systematically identify all external dependencies through context-aware discussion. + +## Context for Agent + +Review the Product Brief first to identify which integration categories are relevant, then only discuss applicable ones. For each integration, document: service name, purpose, business rules, priority, cost estimate, and technical risk. + +## Instructions + +### Analyze Product Brief First + +Read the Product Brief and identify relevant categories based on features mentioned. Present only applicable categories with reasons. + +### Go Through Each Relevant Category + +**3A: Authentication & Identity** +- Authentication methods (OAuth, email/password, SSO, passwordless) +- Providers, token lifetime, MFA requirements + +**3B: Payment Processing** (if applicable) +- Providers (Stripe, PayPal, Klarna, regional systems) +- Payment methods, currencies, subscriptions +- Business rules: refund policies, retry logic, tax calculation, invoicing +- Compliance: PCI-DSS requirements + +**3C: Communication Services** +- Email (SendGrid, Mailgun), SMS (Twilio), push notifications, in-app chat +- Business rules: templates, delivery guarantees, opt-out handling, multi-language + +**3D: Search Services** (if applicable) +- Provider (Algolia, Elasticsearch, Typesense) +- Business rules: searchable content, facets, auto-complete, ranking logic + +**3E: Maps & Location** (if applicable) +- Provider (Google Maps, Mapbox, OpenStreetMap) +- Business rules: geocoding, routing, geofencing, caching strategy + +**3F: Data & Analytics** +- Analytics (GA, Mixpanel), error tracking (Sentry), monitoring (Datadog) +- Business rules: events to track, privacy, GDPR compliance, retention + +**3G: Storage & Media** +- File storage (S3, Cloudinary), CDN, video hosting, document processing +- Business rules: size limits, file types, processing, access control, virus scanning + +**3H: Calendar & Scheduling** (if applicable) +- Integrations (Google Calendar, Outlook), booking systems +- Business rules: availability, timezones, recurring events, reminders + +**3I: Social Media & Content** (if applicable) +- Platforms, social login, content sharing (Open Graph, Twitter Cards) + +**3J: Customer Support** (if applicable) +- Tools (Intercom, Zendesk), live chat, knowledge base +- Business rules: user context, SLA, multi-language + +**3K: Marketing & Growth** (if applicable) +- Automation (Mailchimp, HubSpot), A/B testing, feature flags +- Business rules: segmentation, triggers, rollout strategies + +**3L: Domain-Specific APIs** +- Industry-specific services (weather, financial, shipping, government) + +## After All Categories + +Summarize all identified services and ask: "Any other services, APIs, or integrations we should include?" + +**Output:** Create `01-Integration-Map.md` with all services categorized and documented. + +## Next Step + +Proceed to step-04-technical-validation.md + +## State Update + +```yaml +stepsCompleted: ['step-01-welcome.md', 'step-02-platform-architecture.md', 'step-03-integration-mapping.md'] +``` diff --git a/src/workflows/3-prd-platform/steps/step-04-technical-validation.md b/src/workflows/3-prd-platform/steps/step-04-technical-validation.md new file mode 100644 index 000000000..791ce40b6 --- /dev/null +++ b/src/workflows/3-prd-platform/steps/step-04-technical-validation.md @@ -0,0 +1,56 @@ +# Step 4: Technical Validation & Proofs of Concept + +## Purpose + +Identify features needing validation and execute PoCs to prove feasibility. + +## Context for Agent + +Review Feature Impact Analysis to find risky features. High-impact + high-risk features get priority. Frame all results positively — even failed PoCs save weeks of design work. + +## Instructions + +### Identify Features Needing PoCs + +Review Feature Impact Analysis and ask: + +- Which features are innovative or unproven? +- Which depend on external APIs with potential limitations? +- Which have unknown performance characteristics? +- Which might not be technically feasible? + +Prioritize by: +1. High Feature Impact Score + High Technical Risk +2. Medium Impact + High Risk +3. High Impact + Medium Risk + +### Execute PoCs + +For each identified feature: + +1. **Define the question** — What exactly needs to be proven? +2. **Create or request PoC** — Guide through validation or assign to dev team +3. **Document results:** + - Status: Proven / Limited / Not Feasible + - Findings: What worked, what didn't + - Limitations: Edge cases, performance, cost + - Recommendation: Go / No-Go / Modify Feature +4. **Include code snippets** when possible + +### Positive Framing + +- Works: "This proves [feature] is technically sound. Design can proceed with confidence." +- Limited: "Valuable discovery! We found [limitation] early — design can account for it." +- Doesn't work: "Important learning! This saves weeks of design work. Let's explore alternatives." + +**Output:** Create `02-Technical-Proofs-Of-Concept.md` + +## Next Step + +Proceed to step-05-security-framework.md + +## State Update + +```yaml +stepsCompleted: ['step-01-welcome.md', 'step-02-platform-architecture.md', 'step-03-integration-mapping.md', 'step-04-technical-validation.md'] +``` diff --git a/src/workflows/3-prd-platform/steps/step-05-security-framework.md b/src/workflows/3-prd-platform/steps/step-05-security-framework.md new file mode 100644 index 000000000..0ff44877c --- /dev/null +++ b/src/workflows/3-prd-platform/steps/step-05-security-framework.md @@ -0,0 +1,65 @@ +# Step 5: Security & Compliance Framework + +## Purpose + +Define security, authentication, and compliance through detailed discussion. + +## Context for Agent + +Go through each security area methodically. Document all business rules and requirements. + +## Instructions + +### 5A: Authentication + +1. Methods: email/password, OAuth, SSO, passwordless, biometric +2. Multi-factor authentication needs +3. Session management: lifetime, remember me, concurrent sessions +4. Business rules: password requirements, lockout policies, reset flow, timeout + +### 5B: Authorization + +1. User roles (admin, user, moderator, etc.) +2. Per-role capabilities +3. Row-level security (can users only see their own data?) +4. API access control +5. Business rules: permission matrix, data visibility, rate limiting per role + +### 5C: Data Protection + +1. Encryption at rest: passwords, PII, payment data, other sensitive fields +2. TLS/HTTPS for all traffic +3. Backup strategy: frequency, retention, RTO, RPO +4. Business rules: encryption algorithms, key management, deletion policies + +### 5D: Compliance & Regulations + +1. **GDPR** (if EU users): + - Consent: cookie consent, processing consent, withdrawal + - User rights: access, deletion, rectification, portability, objection + - Protection: privacy policy, breach notification (72h), DPIA + - Business rules: consent tracking, retention periods, export format + +2. **Other regulations:** CCPA, HIPAA, PCI-DSS, COPPA — document applicable ones + +3. **Data residency:** Geographic storage requirements, cross-border restrictions + +4. **Industry-specific:** Financial, healthcare, education compliance + +5. **Audit logging:** Events to log, retention period, access controls, tamper-proofing + +## After All Sections + +Summarize and ask: "Anything about security, privacy, or compliance we should add?" + +**Output:** Create `03-Security-Framework.md` + +## Next Step + +Proceed to step-06-api-specifications.md + +## State Update + +```yaml +stepsCompleted: ['step-01-welcome.md', 'step-02-platform-architecture.md', 'step-03-integration-mapping.md', 'step-04-technical-validation.md', 'step-05-security-framework.md'] +``` diff --git a/src/workflows/3-prd-platform/steps/step-06-api-specifications.md b/src/workflows/3-prd-platform/steps/step-06-api-specifications.md new file mode 100644 index 000000000..e225d0b41 --- /dev/null +++ b/src/workflows/3-prd-platform/steps/step-06-api-specifications.md @@ -0,0 +1,56 @@ +# Step 6: API Specifications (API-First Design) + +## Purpose + +Define comprehensive API contracts through systematic category-by-category discussion. + +## Context for Agent + +API-first approach: clear service contracts enable backend development in parallel with UX design. For each endpoint, document method, path, purpose, request/response format, and business rules. + +## Instructions + +Explain: "By defining clear service contracts now, we enable backend development to proceed in parallel with UX design." + +### 6A: Authentication APIs + +Based on the security framework, define auth endpoints: +- Login, logout, token refresh, password reset, email verification +- For each: method/path, request/response, business rules (token lifetime, error responses, rate limiting) + +### 6B: Core Entity APIs (CRUD) + +For each entity from the data model: +- `GET /api/{entity}` - List with pagination +- `GET /api/{entity}/:id` - Get single +- `POST /api/{entity}` - Create +- `PUT /api/{entity}/:id` - Update +- `DELETE /api/{entity}/:id` - Delete +- Business rules: validation, authorization, pagination, related data, constraints + +### 6C: External Integration APIs + +For each external service from Step 3: +- Wrapper endpoints with method/path +- Business rules: pre-call validation, caching, fallback on failure, rate limiting, cost tracking + +### 6D: Business Logic APIs + +Dedicated endpoints for calculations, availability checks, pricing, recommendations, aggregations: +- For each: method/path, purpose, request/response, calculation logic, edge cases, performance expectations + +## After All APIs + +Summarize the API surface and ask: "Any other API operations we should include?" + +**Output:** Create `04-API-Specifications.md` + +## Next Step + +Proceed to step-07-data-and-performance.md + +## State Update + +```yaml +stepsCompleted: ['step-01-welcome.md', 'step-02-platform-architecture.md', 'step-03-integration-mapping.md', 'step-04-technical-validation.md', 'step-05-security-framework.md', 'step-06-api-specifications.md'] +``` diff --git a/src/workflows/3-prd-platform/steps/step-07-data-and-performance.md b/src/workflows/3-prd-platform/steps/step-07-data-and-performance.md new file mode 100644 index 000000000..bc1d27e14 --- /dev/null +++ b/src/workflows/3-prd-platform/steps/step-07-data-and-performance.md @@ -0,0 +1,67 @@ +# Step 7: Data Models & Performance Requirements + +## Purpose + +Document database schemas, entity relationships, and performance benchmarks. + +## Context for Agent + +Formalize the data model from earlier discussions and set clear performance expectations. + +## Instructions + +### 7A: Data Models + +"We identified your core entities earlier. Now let's document the complete data model." + +For each entity: +- Entity name and purpose +- All fields with types, constraints, defaults +- Relationships (one-to-many, many-to-many) +- Indexes for performance +- Business rules: validation, required/optional, unique constraints, cascade delete, audit trail + +Create entity relationship diagram (ERD) showing all connections. + +### 7B: Performance Requirements + +Document systematically: +- **Response Times:** Expected latency per API category +- **Throughput:** Concurrent users, requests per second +- **Data Volume:** Expected record counts, storage needs +- **Availability:** Uptime requirements (99%, 99.9%, 99.99%?) +- **Scalability:** Growth projections and scaling triggers + +### 7C: Technical Constraints for UX + +Create handoff document for UX team: +- **What's Possible:** Validated features from PoCs +- **What Has Limitations:** API limits, performance constraints +- **What Affects Design:** Loading states, offline behavior, real-time vs polling +- **What's Expensive:** Cost-sensitive features requiring careful UX + +### 7D: Acceptance Criteria + +For each major platform area (auth, integrations, security, etc.): +- Functional criteria: What must work? +- Performance criteria: How fast/scalable? +- Security criteria: What standards? +- Testing criteria: What tests must pass? + +Ask: "Any other data modeling, performance, or constraint considerations?" + +**Outputs:** +- `05-Data-Models.md` +- `06-Performance-Requirements.md` +- `07-Technical-Constraints.md` +- `08-Acceptance-Criteria.md` + +## Next Step + +Proceed to step-08-backlog-recommendations.md + +## State Update + +```yaml +stepsCompleted: ['step-01-welcome.md', 'step-02-platform-architecture.md', 'step-03-integration-mapping.md', 'step-04-technical-validation.md', 'step-05-security-framework.md', 'step-06-api-specifications.md', 'step-07-data-and-performance.md'] +``` diff --git a/src/workflows/3-prd-platform/steps/step-08-backlog-recommendations.md b/src/workflows/3-prd-platform/steps/step-08-backlog-recommendations.md new file mode 100644 index 000000000..63879c9c1 --- /dev/null +++ b/src/workflows/3-prd-platform/steps/step-08-backlog-recommendations.md @@ -0,0 +1,64 @@ +# Step 8: Platform Backlog Recommendations + +## Purpose + +Recommend platform infrastructure work for BMM, prioritized by Feature Impact Analysis. + +## Context for Agent + +Connect technical requirements to feature priorities from Phase 2. Recommend epic structure that enables highest-impact features first. This is recommendations — BMM agents handle actual backlog creation. + +## Instructions + +### 8A: Review Feature Impact Analysis + +Read `B-Trigger-Map/03-Feature-Impact-Analysis.md` and identify: +- Must Have features (high scores, primary persona) +- Consider for MVP features (balanced scores) +- Platform dependencies for each high-impact feature + +### 8B: Recommended Initiatives & Epics + +For each recommended epic, note which high-priority features it enables: + +- **Trusted User Access** — Auth system, user management, sessions +- **[External Service] Integration** — One per major integration +- **Data Platform Foundation** — Database, models, synchronization +- **Enterprise Security & Compliance** — Encryption, audit, controls +- **High-Performance Infrastructure** — Caching, optimization, monitoring + +### 8C: Priority-Driven Development Sequence + +1. **Foundation First:** Core infrastructure (hosting, database, basic security) +2. **High-Impact Dependencies:** Platform work for Must-Have features +3. **Risk Mitigation:** Complex/risky integrations (fail fast) +4. **Secondary Features:** Remaining integrations, advanced features +5. **Operations:** Monitoring, analytics, maintenance tools + +### 8D: Feature-to-Epic Mapping + +Create table: Feature | Score | Priority | Required Platform Epics | Notes + +### 8E: API Contracts for UI Development + +List key API categories organized by priority features they enable — backend can implement in parallel with Phase 4. + +### 8F: Dependencies & Parallel Work + +- What must be done before high-impact features? +- What can proceed independently in parallel? +- What provides most risk reduction if done early? + +Ask: "Does this organization make sense based on your feature priorities?" + +**Output:** Create `09-Platform-Backlog-Recommendations.md` + +## Next Step + +Proceed to step-09-prd-finalization.md + +## State Update + +```yaml +stepsCompleted: ['step-01-welcome.md', 'step-02-platform-architecture.md', 'step-03-integration-mapping.md', 'step-04-technical-validation.md', 'step-05-security-framework.md', 'step-06-api-specifications.md', 'step-07-data-and-performance.md', 'step-08-backlog-recommendations.md'] +``` diff --git a/src/workflows/3-prd-platform/steps/step-09-prd-finalization.md b/src/workflows/3-prd-platform/steps/step-09-prd-finalization.md new file mode 100644 index 000000000..3ba4eb67c --- /dev/null +++ b/src/workflows/3-prd-platform/steps/step-09-prd-finalization.md @@ -0,0 +1,86 @@ +# Step 9: Finalize the PRD + +## Purpose + +Create the master PRD that references all Phase 3 work. + +## Context for Agent + +The PRD is the single source of truth. It starts here with technical foundation and grows during Phase 4 as functional requirements are added from UX design. + +## Instructions + +Create `C-Requirements/10-PRD.md` with this structure: + +```markdown +# Product Requirements Document: [Project Name] + +_Phase 3 Complete: Technical Foundation Established_ +_Last Updated: [Date]_ + +## 1. Executive Summary +[Link to Product Brief from Phase 1] +[Link to Trigger Map from Phase 2] + +## 2. Technical Foundation (Phase 3) + +### 2.1 Platform Architecture +[Link to C-Requirements/00-Platform-Architecture.md] + +### 2.2 External Integrations +[Link to C-Requirements/01-Integration-Map.md] + +### 2.3 Technical Validation +[Link to C-Requirements/02-Technical-Proofs-Of-Concept.md] + +### 2.4 Security & Compliance +[Link to C-Requirements/03-Security-Framework.md] + +### 2.5 API Specifications +[Link to C-Requirements/04-API-Specifications.md] + +### 2.6 Data Models +[Link to C-Requirements/05-Data-Models.md] + +### 2.7 Performance Requirements +[Link to C-Requirements/06-Performance-Requirements.md] + +### 2.8 Technical Constraints +[Link to C-Requirements/07-Technical-Constraints.md] + +### 2.9 Acceptance Criteria +[Link to C-Requirements/08-Acceptance-Criteria.md] + +## 3. Platform Backlog Recommendations +[Link to C-Requirements/09-Platform-Backlog-Recommendations.md] + +## 4. Functional Requirements (Phase 4) +_Populated during Phase 4 (UX Design) as pages/scenarios complete._ + +## 5. Next Steps + +**For BMM Agents:** +- Use platform backlog recommendations to create E-Backlog/ +- Create detailed epics and stories from requirements +- Establish implementation roadmap + +**For Phase 4 (UX Design):** +- Technical constraints provide design boundaries +- API specifications define data available to UI +- Begin UX design with confidence in feasibility + +## 6. Change Log +- [Date] - Phase 3 complete: Technical foundation established +``` + +**Output:** Create `C-Requirements/10-PRD.md` + +## Next Step + +Proceed to step-10-summary.md + +## State Update + +```yaml +stepsCompleted: ['step-01-welcome.md', 'step-02-platform-architecture.md', 'step-03-integration-mapping.md', 'step-04-technical-validation.md', 'step-05-security-framework.md', 'step-06-api-specifications.md', 'step-07-data-and-performance.md', 'step-08-backlog-recommendations.md', 'step-09-prd-finalization.md'] +``` diff --git a/src/workflows/3-prd-platform/steps/step-10-summary.md b/src/workflows/3-prd-platform/steps/step-10-summary.md new file mode 100644 index 000000000..3670ebf57 --- /dev/null +++ b/src/workflows/3-prd-platform/steps/step-10-summary.md @@ -0,0 +1,55 @@ +# Step 10: Summary and Completeness Check + +## Purpose + +Review all documents created, check for gaps, and explain next steps. + +## Context for Agent + +Celebrate the work done. Run a systematic completeness check before closing the phase. + +## Instructions + +### Review Documents Created + +1. Platform Architecture — Technology stack, infrastructure +2. Integration Map — All external services with business rules +3. Technical Proofs of Concept — Validated risky features +4. Security Framework — Authentication, authorization, compliance +5. API Specifications — Service contracts for all endpoints +6. Data Models — Complete schemas and ERD +7. Performance Requirements — Scalability and benchmarks +8. Technical Constraints — What UX design needs to know +9. Acceptance Criteria — Testable success definitions +10. Platform Backlog Recommendations — Suggested work for BMM +11. PRD Initialized — Ready to grow in Phase 4 + +### Completeness Check + +Ask systematically: + +1. "Looking at platform architecture — any technology choice or requirement we didn't discuss?" +2. "For integrations — any external services or APIs we forgot?" +3. "Thinking about security — any flows, data protection, or compliance we should add?" +4. "For API specifications — any endpoints or operations we missed?" +5. "Looking at backlog recommendations — any priorities to adjust before BMM handoff?" +6. "Any business rules or limitations that came to mind?" +7. "Anything about performance, scalability, or deployment to capture?" + +If gaps found: document in appropriate files, then return to check. + +### Parallel Workflows Enabled + +"With Phase 3 complete, multiple work streams can now proceed:" + +1. **BMM Backlog Creation** — BMM agents use recommendations to create E-Backlog/ +2. **Backend Development** — Infrastructure, APIs, database, integrations can begin +3. **Phase 4: UX Design** — Design proceeds with confidence about feasibility + +Ask: "Would you like to proceed to Phase 4 (UX Design), hand off to BMM for backlog creation, or plan backend development?" + +## State Update + +```yaml +stepsCompleted: ['step-01-welcome.md', 'step-02-platform-architecture.md', 'step-03-integration-mapping.md', 'step-04-technical-validation.md', 'step-05-security-framework.md', 'step-06-api-specifications.md', 'step-07-data-and-performance.md', 'step-08-backlog-recommendations.md', 'step-09-prd-finalization.md', 'step-10-summary.md'] +``` diff --git a/src/workflows/4-ux-design/agentic-development/guides/EXECUTION-PRINCIPLES.md b/src/workflows/4-ux-design/agentic-development/guides/EXECUTION-PRINCIPLES.md new file mode 100644 index 000000000..35d8e38d8 --- /dev/null +++ b/src/workflows/4-ux-design/agentic-development/guides/EXECUTION-PRINCIPLES.md @@ -0,0 +1,75 @@ +# Execution Principles + +## Document Before Acting + +**Every decision, action, and problem must be documented in the dialog file BEFORE acting on it.** + +This ensures full traceability, clean handoff, and the dialog document is always the source of truth. + +## Sketch Fidelity + +**Implement code as close to the provided sketches as possible.** + +Sketches are intentional design decisions, not loose suggestions: + +| Element | Approach | +|---------|----------| +| **Text sizes** | Match relative sizes (headings vs body vs labels) | +| **Proportions** | Preserve ratios between elements | +| **Spacing** | Maintain visual rhythm and whitespace | +| **Layout** | Follow the arrangement precisely | +| **Component style** | Match the visual pattern (pills, cards, buttons) | + +When in doubt: ask the designer. If constraints make exact matching impossible, document the deviation and explain why. + +## Sub-Steps During Execution + +While working on a step, add discovered tasks as sub-steps: + +```markdown +| # | Section | Status | Notes | +|---|---------|--------|-------| +| 14 | Book It Button | Done | Complete | +| 14a | Fix button alignment | Done | Added during 14 | +| 14b | Add loading state | Done | Added during 14 | +| 15 | Cancel Button | In Progress | | +``` + +Sub-steps use letter suffixes (14a, 14b) to maintain parent position. + +## Dynamic Planning After Step Completion + +After completing each step, review and adjust the plan: + +1. Review remaining steps — still accurate? +2. Shuffle if needed — reorder based on learnings +3. Add new steps — if implementation revealed new requirements +4. Remove steps — if no longer needed +5. Update the dialog file + +**Numbering rules:** Completed steps = fixed numbering. Future steps = dynamic numbering. + +## Plan-then-Execute Pattern + +**Separate planning from execution into distinct sessions.** + +Context windows are finite. Long sessions accumulate noise. The solution: + +**Planning Session:** +1. Explore codebase and requirements +2. Discuss approach with designer +3. Write plan to dialog file +4. End with clear handoff + +**Execution Session:** +1. Start fresh (new conversation) +2. Read product brief for context +3. Read page specification for requirements +4. Read dialog document for plan and progress +5. Execute steps one by one + +**When to split:** After complex exploration, when plan is complete, when session is getting long, before major implementation. + +## Handoff Always References Dialog + +Any handoff — to a new session, agent, or human — **MUST** reference the dialog document. Never hand off verbally. Always point to the dialog. diff --git a/src/workflows/4-ux-design/agentic-development/guides/FEEDBACK-PROTOCOL.md b/src/workflows/4-ux-design/agentic-development/guides/FEEDBACK-PROTOCOL.md new file mode 100644 index 000000000..da522112e --- /dev/null +++ b/src/workflows/4-ux-design/agentic-development/guides/FEEDBACK-PROTOCOL.md @@ -0,0 +1,86 @@ +# User Feedback Protocol + +**CRITICAL: Never implement feedback without first classifying it and stating when it should be addressed.** + +## Feedback Types + +| Type | What It Is | When to Address | +|------|------------|-----------------| +| **Bug/Issue** | Something broken, error, not working | Now — fix immediately, iterate until resolved | +| **Quick Adjustment** | Small tweak, change X to Y | Now — implement immediately | +| **Addition** | New requirement that fits current dialog | Later step — add to plan | +| **Change Request** | Outside current dialog scope | Future session — document in Change Requests | + +## The 2-Minute Rule (GTD) + +**If a fix takes less than 2 minutes, do it immediately.** + +From David Allen's "Getting Things Done": planning overhead should not exceed task complexity. + +| Situation | Action | +|-----------|--------| +| Missing condition check | Fix now, log as sub-step | +| Wrong variable name | Fix now, log as sub-step | +| Needs new component | Add to plan | +| Architectural change | Add to plan | + +**Pattern:** Do the fix → Log as sub-step (e.g., 20a-1) → Continue main task + +## Response Flow + +When user reports something: + +1. **CLASSIFY** — What type of feedback is this? +2. **TIMING** — When should it be addressed? +3. **DOCUMENT** — For bugs, add to plan BEFORE fixing +4. **CONFIRM** — For additions and change requests, confirm before proceeding +5. **EXECUTE** — Implement or document as appropriate + +### Bug/Issue (Document First, Then Fix) + +**User says:** "This is broken" / "Error occurred" / "Not working" + +**Agent response:** +``` +This is a bug — [brief description]. +Let's call it 10A and let me add it to the plan, then fix it. +``` + +Required sequence: +1. Identify — Understand and describe the bug +2. Document — Add to dialog plan as sub-step (e.g., 21a, 21b) +3. Execute — Fix and iterate until resolved +4. Log — Record resolution in progress log + +If user reports multiple issues: list each separately, add ALL to plan first, then fix one by one. + +### Quick Adjustment (Fix Now) + +**User says:** "Change X to Y" / "Make this button go here" + +**Agent response:** "Quick adjustment — I'll implement this now." Then implement. + +### Addition (Add to Plan) + +**User says:** "We should also add X" + +**Agent response:** "This is an addition that fits the current dialog. I'll add it to Step {N}. Confirm?" + +### Change Request (Document for Later) + +**User says:** "We need a settings page" + +**Agent response:** +``` +This is outside the current dialog scope. +It doesn't block {feature name}. +I'll add it to Change Requests for a future session. Confirm? +``` + +**WAIT for user confirmation.** If user says "do it now" → treat as quick adjustment. + +### Anti-Pattern + +**NEVER** immediately implement without classifying. **ALWAYS** classify, state timing, then confirm or act. + +The extra seconds to classify and confirm build trust and ensure alignment. diff --git a/src/workflows/4-ux-design/agentic-development/guides/SESSION-PROTOCOL.md b/src/workflows/4-ux-design/agentic-development/guides/SESSION-PROTOCOL.md new file mode 100644 index 000000000..3604862a2 --- /dev/null +++ b/src/workflows/4-ux-design/agentic-development/guides/SESSION-PROTOCOL.md @@ -0,0 +1,46 @@ +# Session Start Protocol + +When starting or resuming a session, **always follow this sequence before implementing anything:** + +## 1. Read the Dialog Document + +Read the dialog file completely to understand: +- What steps are done +- What steps remain +- Any blockers or change requests +- Current context and decisions + +## 2. Verify Plan Against Reality + +**The plan may be outdated.** Check if: +- Steps marked "To Do" have actually been implemented +- Steps marked "Done" are truly complete +- Numbering is sequential and accurate + +If the plan is outdated → Update it before proceeding. + +## 3. Present Current Status + +Summarize for the designer: +- What's done (with step numbers) +- What's remaining (with step numbers) +- Any change requests pending + +## 4. Before Implementing a Step + +**Always check the specification/sketches first:** + +``` +Agent: "Before implementing step 20, let me check the sketches..." +Agent: "I see this requires a nested drawer pattern, not inline buttons. + Should I break this into sub-steps?" +``` + +This prevents building the wrong thing and wasting effort. + +## Why This Matters + +Sessions can be interrupted. Context can be lost. The dialog document survives — but only if it's kept accurate. This protocol ensures: +- No duplicate work (re-implementing what exists) +- No missed work (skipping what's actually needed) +- Correct understanding of requirements before implementation diff --git a/src/workflows/4-ux-design/agentic-development/workflow.md b/src/workflows/4-ux-design/agentic-development/workflow.md index f6f8f958e..1ad071512 100644 --- a/src/workflows/4-ux-design/agentic-development/workflow.md +++ b/src/workflows/4-ux-design/agentic-development/workflow.md @@ -12,620 +12,91 @@ web_bundle: true --- -## OVERVIEW - -Agentic Development is about **how** you work with AI — not **what** you build. - -Use this workflow to build a prototype, extend a production app, create a new feature, or anything else. The AI handles implementation while you focus on what to build and how it should behave. - -This workflow enables: -- ✅ Direct implementation from specifications -- ✅ Step-by-step development with approval gates -- ✅ Clear feedback protocol with timing guidance -- ✅ Agent Dialog structure for context and handoff -- ✅ Dynamic planning that adapts as we learn - -**Note:** We use "scenario step" instead of "page" - a step can be a full page, modal, overlay, state change, or any UI change requiring a new sketch. - ---- - ## WHEN TO USE -Use this workflow when: -- ✅ Page specifications are complete and approved -- ✅ Ready to build working implementations -- ✅ Working with AI to develop production-ready code -- ✅ Want iterative development with approval gates -- ✅ Need structured collaboration with clear feedback handling +- Page specifications are complete and approved +- Ready to build working implementations with AI +- Want iterative development with approval gates -Skip this workflow when: -- ❌ Specifications not complete yet -- ❌ Still in sketching or wireframe phase -- ❌ Simple one-file changes that don't need documentation -- ❌ Pure exploration where the path is unclear +**Skip when:** Specifications incomplete, still sketching, simple one-file changes, or pure exploration. --- -## USER FEEDBACK PROTOCOL - -During development, the designer provides feedback. **CRITICAL: Never implement feedback without first classifying it and stating when it should be addressed.** - -### Feedback Types - -| Type | What It Is | When to Address | -|------|------------|-----------------| -| **Bug/Issue** | Something broken, error, not working | Now — fix immediately, iterate until resolved | -| **Quick Adjustment** | Small tweak, change X to Y | Now — implement immediately | -| **Addition** | New requirement that fits current dialog | Later step — add to plan | -| **Change Request** | Outside current dialog scope | Future session — document in Change Requests | - -### The 2-Minute Rule (GTD) - -**If a fix takes less than 2 minutes, do it immediately.** - -From David Allen's "Getting Things Done": planning overhead should not exceed task complexity. See [GTD Model](../../../docs/models/gtd-getting-things-done.md). - -| Situation | Action | -|-----------|--------| -| Missing condition check | Fix now, log as sub-step | -| Wrong variable name | Fix now, log as sub-step | -| Needs new component | Add to plan | -| Architectural change | Add to plan | - -**Pattern:** Do the fix → Log as sub-step (e.g., 20a-1) → Continue main task - -### Response Flow - -**When user reports something:** - -1. **CLASSIFY** — What type of feedback is this? -2. **TIMING** — When should it be addressed? -3. **DOCUMENT** — For bugs, add to plan BEFORE fixing -4. **CONFIRM** — For additions and change requests, confirm before proceeding -5. **EXECUTE** — Implement or document as appropriate - -### Bug/Issue (Document First, Then Fix) - -**User says:** "This is broken" / "Error occurred" / "Not working" - -**Agent response:** -``` -This is a bug — [brief description of issue]. -Let's call it 10A and let me add it to the plan, then fix it. -``` - -**Required sequence:** -1. **Identify** — Understand and describe the bug clearly -2. **Document** — Add to dialog plan as sub-step (e.g., 21a, 21b) -3. **Execute** — Fix and iterate until resolved -4. **Log** — Record resolution in progress log - -**If user reports multiple issues at once:** -1. Identify and list each issue separately -2. Add ALL to the plan first -3. Then work through them one by one - -**Why document first:** Bugs discovered during implementation are valuable context. Recording them ensures traceability, prevents forgotten fixes, and creates a clear record for handoff. - -**Example:** -``` -User: "The drawer appears behind the overlay and the reassign doesn't work" - -Agent: "I see two issues: - 1. Drawer z-index (appears behind overlay) - 2. Reassign not working - - Let me add both to the plan as 21a and 21b, then fix them." -``` - -### Quick Adjustment (Fix Now) - -**User says:** "Change X to Y" / "Make this button go here" / "Use different color" - -**Agent response:** -``` -Quick adjustment — I'll implement this now. -``` - -Then implement the change. - -### Addition (Add to Plan) - -**User says:** "We should also add X" / "Don't forget to handle Y" - -**Agent response:** -``` -This is an addition that fits the current dialog. -I'll add it to Step {N} for later. Confirm? -``` - -Then add to the appropriate step or To Do section in the dialog file. - -### Change Request (Document for Later) - -**User says:** "The profile button should go to /family" / "We need a settings page" - -**Agent response:** -``` -This is outside the current dialog scope. -It doesn't block {feature name}. - -I'll add it to Change Requests for a future session. Confirm? -``` - -**WAIT for user confirmation.** - -If user confirms → Add to Change Requests section -If user says "do it now" → Treat as quick adjustment and implement - -### Anti-Pattern: What NOT to Do - -**NEVER do this:** - -User: "The profile button should go to /family" -Agent: *immediately edits the file* - -**ALWAYS do this:** - -User: "The profile button should go to /family" -Agent: "This is outside current scope. I'll add it to Change Requests. Confirm?" -User: "Yes" or "No, do it now" -*then acts accordingly* - -### Why This Matters - -From experience, skipping the classify-and-timing step leads to: -- Agent implementing things the user didn't want -- User frustration from lack of visibility -- Lost context when user wanted to discuss first -- Scope creep pulling focus from current implementation - -The extra seconds to classify and confirm build trust and ensure alignment. - ---- - -## SESSION START PROTOCOL - -When starting or resuming a session, **always follow this sequence before implementing anything:** - -### 1. Read the Dialog Document - -``` -Agent: "Let me read the dialog document to understand where we are." -``` - -Read the dialog file completely to understand: -- What steps are done -- What steps remain -- Any blockers or change requests -- Current context and decisions - -### 2. Verify Plan Against Reality - -**The plan may be outdated.** Check if: -- Steps marked "To Do" have actually been implemented -- Steps marked "Done" are truly complete -- The numbering is sequential and accurate - -``` -Agent: "I see steps 11-18 in To Do, but let me check the code..." -Agent: "These are already implemented. Let me update the plan." -``` - -If the plan is outdated → Update it before proceeding. - -### 3. Present Current Status - -Summarize for the designer: -- What's done (with step numbers) -- What's remaining (with step numbers) -- Any change requests pending - -``` -Agent: "Here's where we are: - Done: Steps 9b, 10, 11-19 - To Do: Steps 20, 21 - Ready to continue?" -``` - -### 4. Before Implementing a Step - -**Always check the specification/sketches first:** - -``` -Agent: "Before implementing step 20, let me check the sketches..." -Agent: "I see this requires a nested drawer pattern, not inline buttons. - Should I break this into sub-steps?" -``` - -This prevents building the wrong thing and wasting effort. - -### Why This Matters - -Sessions can be interrupted. Context can be lost. The dialog document survives — but only if it's kept accurate. This protocol ensures: -- No duplicate work (re-implementing what exists) -- No missed work (skipping what's actually needed) -- Correct understanding of requirements before implementation - ---- - -## EXECUTION PRINCIPLES - -### Document Before Acting - -**Every decision, action, and problem must be documented in the dialog file BEFORE acting on it.** - -This ensures: -- Full traceability of what was decided and why -- Clean handoff if context is lost or session changes -- The dialog document is always the source of truth for progress - -### Sketch Fidelity - -**Implement code as close to the provided sketches as possible.** - -Sketches are intentional design decisions, not loose suggestions. Text sizes, proportions, spacing, and layout choices are made for a reason: - -| Element | Approach | -|---------|----------| -| **Text sizes** | Match relative sizes in sketch (headings vs body vs labels) | -| **Proportions** | Preserve ratios between elements | -| **Spacing** | Maintain visual rhythm and whitespace | -| **Layout** | Follow the arrangement precisely | -| **Component style** | Match the visual pattern (pills, cards, buttons) | - -**When in doubt:** -1. Ask the designer for clarification -2. Reference the sketch directly in your question -3. Don't assume "close enough" is acceptable - -**If constraints make exact matching impossible** (e.g., responsive behavior, platform limitations), document the deviation and explain why. - -### Sub-Steps During Execution - -While working on a step, you may discover additional tasks needed. Add these as sub-steps: - -```markdown -| # | Section | Status | Notes | -|---|---------|--------|-------| -| 14 | Book It Button | ✅ | Complete | -| 14a | Fix button alignment | ✅ | Added during 14 | -| 14b | Add loading state | ✅ | Added during 14 | -| 15 | Cancel Button | 🔄 | In progress | -``` - -Sub-steps use letter suffixes (14a, 14b) to maintain the parent step's position. - -### Dynamic Planning After Step Completion - -**After completing each step, review and adjust the plan:** - -1. **Review remaining steps** — Are they still accurate? -2. **Shuffle if needed** — Reorder based on what we learned -3. **Add new steps** — If implementation revealed new requirements -4. **Remove steps** — If no longer needed -5. **Update the dialog file** — Document the changes - -**Numbering Rules:** -- **Completed steps:** Fixed numbering (never renumber) -- **Future steps:** Dynamic numbering (can change) - -Example: -```markdown -### Done -| 9b | Carousel Refactor | ✅ | ← Fixed, never changes -| 10 | Deep Linking | ✅ | ← Fixed - -### To Do -| 11 | Wire up handlers | 🔲 | ← Can be renumbered -| 12 | Add poop toggle | 🔲 | ← Can be removed or moved -| 13 | NEW: Error states | 🔲 | ← Can be inserted -``` - -### Handoff Always References Dialog - -**Any handoff — to a new session, new agent, or human — MUST reference the dialog document.** - -The dialog document is the single source of truth for: -- What has been done -- What decisions were made -- What remains to be done -- Any issues or blockers - -Never hand off by describing the task verbally. Always point to the dialog. - -### Plan-then-Execute Pattern - -**Separate planning from execution into distinct sessions.** - -Context windows are finite. Long sessions accumulate noise and risk context loss mid-implementation. The solution: end planning sessions deliberately, start execution sessions fresh. - -**Planning Session:** -1. Explore the codebase and requirements -2. Discuss approach with the designer -3. Write the plan to the dialog file -4. End with a clear handoff: *"The plan is documented. Hasta la vista!"* - -**Execution Session:** -1. Start fresh (new conversation) -2. Read the product brief for overall context -3. Read the page specification for requirements -4. Read the dialog document to understand the plan and progress -5. Execute the steps one by one - -**Why This Works:** -- Fresh context window for execution = maximum working memory -- Dialog document carries all decisions and context forward -- No risk of context loss mid-implementation -- Each session has a clear, focused purpose - -**When to Split:** -- After complex exploration or analysis -- When the plan is complete and approved -- When current session is getting long -- Before starting a major implementation phase - -**The Dialog is the Bridge:** -``` -┌─────────────────────┐ Dialog ┌─────────────────────┐ -│ PLANNING SESSION │─────File────▶│ EXECUTION SESSION │ -│ │ │ │ -│ • Explore codebase │ │ • Fresh context │ -│ • Discuss approach │ │ • Read brief + spec │ -│ • Write plan │ │ • Read dialog │ -│ • "Hasta la vista!" │ │ • Execute steps │ -└─────────────────────┘ └─────────────────────┘ -``` - ---- - -## WORKFLOW ARCHITECTURE - -This uses **multi-phase architecture** with iterative loops: - -### Phase Structure - -**Sequential Phases (1-3, 5):** Setup → Analysis → Selection → Finalization - -**Iterative Phase (4):** Section implementation loop with 7 micro-tasks - -### Critical Rules - -- 🎯 **ALWAYS** complete Phase 1 setup before starting -- 📊 **ALWAYS** analyze scenario before selecting views -- 🔁 **ALWAYS** use section-by-section approach (Phase 4 loop) -- ✅ **ALWAYS** get approval before moving to next section -- 📝 **ALWAYS** create story files just-in-time (not upfront) +## ESSENTIAL GUIDES (Read Before Starting) + +- **[Feedback Protocol](guides/FEEDBACK-PROTOCOL.md)** — Classify feedback before acting (Bug/Quick/Addition/Change) +- **[Session Protocol](guides/SESSION-PROTOCOL.md)** — Read dialog, verify plan, present status before implementing +- **[Execution Principles](guides/EXECUTION-PRINCIPLES.md)** — Document-first, sketch fidelity, plan-then-execute pattern + +**Process Guides:** +- [Agentic Development Guide](guides/AGENTIC-DEVELOPMENT-GUIDE.md) +- [Creation Guide](guides/CREATION-GUIDE.md) +- [Prototype Initiation Dialog](guides/PROTOTYPE-INITIATION-DIALOG.md) +- [Prototype Analysis](guides/PROTOTYPE-ANALYSIS.md) +- [File Index](guides/FILE-INDEX.md) --- ## THE 5 PHASES -### Phase 1: Prototype Setup -**When:** Starting new scenario prototype (one-time per scenario) - -**What:** Set up prototype environment and folder structure - -**Creates:** -- Prototype folder with complete structure -- Demo data files -- Roadmap document -- All working folders (work/, stories/, shared/, components/, etc.) - +### Phase 1: Prototype Setup (one-time per scenario) +Set up prototype environment and folder structure. **Go to:** [steps-c/1-prototype-setup.md](steps-c/1-prototype-setup.md) ---- - -### Phase 2: Scenario Analysis -**When:** Setup complete, ready to start building (one-time per scenario) - -**What:** Analyze all scenario steps and identify logical views - -**Creates:** -- Logical View Map (maps steps to views) -- View identification and relationships - +### Phase 2: Scenario Analysis (one-time per scenario) +Analyze all scenario steps and identify logical views. **Go to:** [steps-c/2-scenario-analysis.md](steps-c/2-scenario-analysis.md) ---- - -### Phase 3: Logical View Selection & Breakdown -**When:** User selects which logical view to build (per view) - -**What:** Identify all objects and break view into sections - -**Creates:** -- Work file with section breakdown -- Implementation sequence - +### Phase 3: Logical View Selection & Breakdown (per view) +Identify objects and break view into sections. **Go to:** [steps-c/3-logical-view-breakdown.md](steps-c/3-logical-view-breakdown.md) ---- +### Phase 4: Section Story & Implementation Loop (per section) -### Phase 4: Section Story & Implementation Loop -**When:** Ready to build sections (iterative per section) +| Step | Task | File | +|------|------|------| +| 4a | Announce & Gather | [4a-announce-and-gather.md](steps-c/4a-announce-and-gather.md) | +| 4b | Create Story File | [4b-create-story-file.md](steps-c/4b-create-story-file.md) | +| 4c | Implement Section | [4c-implement-section.md](steps-c/4c-implement-section.md) | +| 4d | Present for Testing | [4d-present-for-testing.md](steps-c/4d-present-for-testing.md) | +| 4e | Handle Issue | [4e-handle-issue.md](steps-c/4e-handle-issue.md) | +| 4f | Handle Improvement | [4f-handle-improvement.md](steps-c/4f-handle-improvement.md) | +| 4g | Section Approved | [4g-section-approved.md](steps-c/4g-section-approved.md) | -**What:** For each section - prepare, create story, implement, test, handle feedback, approve - -**The 7 Micro-Tasks:** - -1. **[4a: Announce & Gather](steps-c/4a-announce-and-gather.md)** - - Announce section and gather requirements - -2. **[4b: Create Story File](steps-c/4b-create-story-file.md)** - - Create focused story file for this section - -3. **[4c: Implement Section](steps-c/4c-implement-section.md)** - - Implement code following story - -4. **[4d: Present for Testing](steps-c/4d-present-for-testing.md)** - - Present to user with test instructions - -5. **[4e: Handle Issue](steps-c/4e-handle-issue.md)** - - Fix issues if user reports problems (loop back to 4d) - -6. **[4f: Handle Improvement](steps-c/4f-handle-improvement.md)** - - Implement improvements if user suggests (loop back to 4d) - -7. **[4g: Section Approved](steps-c/4g-section-approved.md)** - - Finalize approval and move to next section (back to 4a) - -**Flow:** 4a → 4b → 4c → 4d → [4e or 4f if needed, loops to 4d] → 4g → [back to 4a for next section] - -**Creates (per section):** -- Story file (just-in-time) -- Incremental updates to view HTML -- Learnings captured - -**Key:** One clear task per file → No confusion → Linear execution → Better results! - ---- - -### Phase 5: Finalization -**When:** All sections complete for a logical view (end of view) - -**What:** Integration test all states and final approval - -**Result:** Production-ready logical view handling all its states +**Flow:** 4a → 4b → 4c → 4d → [4e/4f if needed → 4d] → 4g → [next section] +### Phase 5: Finalization (per view) +Integration test all states and final approval. **Go to:** [steps-c/5-finalization.md](steps-c/5-finalization.md) --- -## INITIALIZATION +## CRITICAL RULES -### Guide References - -**Process Guides:** -- [AGENTIC-DEVELOPMENT-GUIDE.md](guides/AGENTIC-DEVELOPMENT-GUIDE.md) - Overview and methodology -- [CREATION-GUIDE.md](guides/CREATION-GUIDE.md) - Technical implementation details -- [PROTOTYPE-INITIATION-DIALOG.md](guides/PROTOTYPE-INITIATION-DIALOG.md) - Conversation scripts -- [PROTOTYPE-ANALYSIS.md](guides/PROTOTYPE-ANALYSIS.md) - Quality standards -- [FILE-INDEX.md](guides/FILE-INDEX.md) - Complete file reference - -**Templates:** -- templates/work-file-template.yaml -- templates/story-file-template.md -- templates/page-template.html -- templates/components/dev-mode.* - -### First Step Execution - -Load, read and execute `steps-c/1-prototype-setup.md` to begin workflow. +- **ALWAYS** complete Phase 1 setup before starting +- **ALWAYS** analyze scenario before selecting views +- **ALWAYS** use section-by-section approach (Phase 4 loop) +- **ALWAYS** get approval before moving to next section +- **ALWAYS** create story files just-in-time (not upfront) --- ## OUTPUT -**Per Scenario:** ``` -[Scenario-Number]-[Scenario-Name]-Prototype/ -├── [View].html files (in root, one per logical view) -├── shared/ (ONE COPY of shared code) -├── components/ (ONE COPY of reusable components) -├── pages/ (page-specific scripts if complex) -├── data/ (demo data JSON files) -├── stories/ (section development files - created just-in-time) +[Scenario]-Prototype/ +├── [View].html files (one per logical view) +├── shared/ (shared code) +├── components/ (reusable components) +├── pages/ (page-specific scripts) +├── data/ (demo data JSON) +├── stories/ (section dev files, created just-in-time) ├── work/ (planning files) └── PROTOTYPE-ROADMAP.md ``` -**Result:** Self-contained, production-ready interactive prototypes with: -- Clean HTML using Tailwind CSS -- Vanilla JavaScript components -- Demo data auto-loading -- All states implemented and tested - --- -## PROTOTYPE FOLDER STRUCTURE +## FIRST STEP -``` -[Scenario-Number]-[Scenario-Name]-Prototype/ -├── [Page].html files ← Logical view HTML files (root) -├── shared/ ← ONE COPY of shared code -├── components/ ← ONE COPY of reusable components -├── pages/ ← Page-specific scripts (if complex) -├── data/ ← Demo data JSON files -├── stories/ ← Section development files (JIT) -├── work/ ← Planning files -│ ├── Logical-View-Map.md ← Maps steps to views -│ └── [View]-Work.yaml ← Section breakdowns per view -└── PROTOTYPE-ROADMAP.md ← Overall roadmap -``` - ---- - -## ITERATIVE WORKFLOW - -**Phase 1-2:** One-time setup and analysis per scenario - -**Phase 3:** Repeat for each logical view in scenario - -**Phase 4:** Repeat for each section in current view -- Inner loop: Repeat 4d-4e-4f until approved - -**Phase 5:** Repeat for each logical view (finalization) - -**Pattern:** -``` -Setup → Analysis → [View Selection → [Section Loop*] → Finalization]* -``` - ---- - -## EXAMPLES - -**Typical Scenarios:** - -1. **E-commerce Checkout:** 5 views (cart, shipping, payment, review, confirmation) -2. **SaaS Onboarding:** 4 views (signup, profile, preferences, dashboard) -3. **Booking System:** 6 views (search, select, details, confirm, payment, confirmation) - -Each view breaks into 3-8 sections depending on complexity. - ---- - -## QUALITY PRINCIPLES - -**Section-by-Section Approval:** Never implement entire view at once - break into sections with approval gates - -**Just-In-Time Stories:** Create story files only when needed (4b), not upfront - -**Incremental Implementation:** Each section builds on previous approved sections - -**Demo Data:** Use realistic demo data for testing and validation - -**Self-Contained:** Each prototype folder is complete and portable - ---- - -## TROUBLESHOOTING - -**Issue:** User feedback requires rework -**Solution:** Use Phase 4e (issues) or 4f (improvements) to handle, then loop back to 4d - -**Issue:** Section too complex -**Solution:** Break down further in Phase 3 before starting Phase 4 - -**Issue:** Logical view unclear -**Solution:** Revisit Phase 2 analysis to refine view mapping - ---- - -## NOTES - -This workflow enables **non-technical designers to build with AI** — whether that's: -- A quick prototype for user testing -- New features in an existing production app -- A complete application from scratch - -The methodology stays the same: -- Step-by-step with approval gates -- Clear feedback protocol ensures alignment -- Agent Dialogs provide structure and traceability -- AI handles implementation, designer focuses on what and how - ---- - -_Agentic Development - AI-assisted development for non-technical designers_ +Load, read and execute `steps-c/1-prototype-setup.md` to begin. diff --git a/src/workflows/4-ux-design/object-types/workflow.md b/src/workflows/4-ux-design/object-types/workflow.md index 8b4587ca4..cdce9a488 100644 --- a/src/workflows/4-ux-design/object-types/workflow.md +++ b/src/workflows/4-ux-design/object-types/workflow.md @@ -14,189 +14,45 @@ web_bundle: true ## OVERVIEW -This is a **router workflow** used within the page specification process. +Router workflow used within the page specification process (called from step 4c-03). -**Purpose:** Detect what UI objects are in a sketch and guide proper specification - -**Key Features:** -- ✅ Text detection priority (horizontal line pairs = text) -- ✅ Intelligent object interpretation -- ✅ Complexity assessment and routing -- ✅ User confirmation of interpretations -- ✅ Decomposition coaching for complex components +**Not a standalone workflow** — only used within page specification. --- -## WHEN TO USE +## THE 3-STEP PROCESS -**Use this router when:** -- ✅ In page specification process (step 4c-03) -- ✅ Need to identify object type from sketch -- ✅ Want AI interpretation of UI elements -- ✅ Need complexity routing for components -- ✅ Require specification template for object - -**This is NOT a standalone workflow:** -- ❌ Don't call directly from user request -- ❌ Only used within page specification workflow -- ❌ Part of larger specification process - ---- - -## HOW IT WORKS - -### The 3-Step Process - -**Step 1: Detection** -- Apply text detection rules (priority) -- Analyze visual characteristics -- Consider context and placement - -**Step 2: Interpretation** -- Suggest object type with confidence -- Explain reasoning -- Request user confirmation - -**Step 3: Routing** -- Route to appropriate template -- Load object-specific instructions -- Guide specification process - ---- - -## ROUTING LOGIC - -### Text Detection Priority +### Step 1: Text Detection (Priority) **FIRST:** Check for horizontal line pairs - 2 parallel lines = 1 line of text - Multiple pairs = multiple text lines - Single lines = decorative (borders, dividers) -**If text detected:** -→ Route immediately to [heading-text.md](templates/heading-text.md) +**If text detected** → Route to [heading-text.md](templates/heading-text.md) **Reference:** [TEXT-DETECTION-PRIORITY.md](TEXT-DETECTION-PRIORITY.md) ---- +### Step 2: Object Analysis (if not text) -### Object Type Detection - -**If not text, analyze:** -- Visual shape and style -- Interactive indicators -- Context and placement -- Common UI patterns - -**Make interpretation:** -- Suggest object type -- Explain reasoning +- Analyze visual shape, style, interactive indicators, context +- Suggest object type with reasoning - Get user confirmation **Reference:** [object-router.md](object-router.md) ---- +### Step 3: Complexity Assessment -### Complexity Assessment - -**After type confirmed:** - -**Simple Component:** -- Single state -- No complex interactions -- No business logic +**Simple Component** (single state, no business logic): → Document in page specification only -**Complex Component:** -- Multiple states (3+) -- Business rules -- Multi-step interactions -- State machines +**Complex Component** (3+ states, business rules, multi-step interactions): → Route to decomposition coaching **Reference:** [COMPLEXITY-ROUTER.md](COMPLEXITY-ROUTER.md) --- -## AVAILABLE OBJECT TYPES - -### Text Elements - -**[Heading / Text](templates/heading-text.md)** -- Headings (H1-H6) -- Paragraphs -- Labels -- Captions -- Includes sketch analysis (line pairs, character capacity) - ---- - -### Interactive Elements - -**[Button](templates/button.md)** -- Primary, secondary, tertiary buttons -- Icon buttons -- Button groups - -**[Text Input](templates/text-input.md)** -- Single-line inputs -- Search fields -- Form inputs - -**[Link](templates/link.md)** -- Text links -- Navigation links -- Action links - -**[Image](templates/image.md)** -- Static images -- Responsive images -- Image placeholders - -**Additional (referenced):** -- Textarea -- Select dropdown -- Checkbox -- Radio button -- Toggle switch - ---- - -### Container Elements - -**Referenced:** -- Card -- Modal/Dialog -- Table -- List - ---- - -### Navigation Elements - -**Referenced:** -- Navigation menu -- Tabs -- Breadcrumbs - ---- - -### Status Elements - -**Referenced:** -- Badge -- Alert/Toast -- Progress indicator - ---- - -### Custom Components - -**Referenced:** -- Custom components (unique to project) - ---- - ## ROUTING FLOW ``` @@ -204,7 +60,7 @@ Start ↓ [1] Text Detection Priority ├─ Horizontal line pairs? - │ ├─ YES → Route to heading-text.md ✓ + │ ├─ YES → Route to heading-text.md │ └─ NO → Continue to [2] ↓ [2] Object Analysis @@ -214,226 +70,59 @@ Start └─ Confirmed type → Continue to [3] ↓ [3] Complexity Assessment - ├─ Simple component? - │ └─ YES → Route to object template ✓ - └─ Complex component? - └─ YES → Complexity Router (decomposition) ✓ + ├─ Simple → Route to object template + └─ Complex → Complexity Router (decomposition) ``` -**Visual Reference:** [ROUTER-FLOW-DIAGRAM.md](ROUTER-FLOW-DIAGRAM.md) +**Full diagram:** [ROUTER-FLOW-DIAGRAM.md](ROUTER-FLOW-DIAGRAM.md) --- -## INTERPRETATION EXAMPLES +## AVAILABLE OBJECT TYPES -### Example 1: Button Detection +### Text Elements +**[Heading / Text](templates/heading-text.md)** — Headings, paragraphs, labels, captions -``` -My interpretation: +### Interactive Elements +- **[Button](templates/button.md)** — Primary, secondary, icon buttons +- **[Text Input](templates/text-input.md)** — Single-line inputs, search, forms +- **[Link](templates/link.md)** — Text, navigation, action links +- **[Image](templates/image.md)** — Static, responsive, placeholders +- Additional: Textarea, Select, Checkbox, Radio, Toggle -This looks like a PRIMARY BUTTON. +### Container Elements +Card, Modal/Dialog, Table, List -Based on what I see: -- Prominent placement at bottom of form -- Bright blue background (primary color) -- White text saying "Save Profile" -- Located after all form fields +### Navigation Elements +Navigation menu, Tabs, Breadcrumbs -I think this "Save Profile Button": -- Saves the form data to the database -- Updates the user's profile information -- Shows loading state during save -- Navigates to profile view on success +### Status Elements +Badge, Alert/Toast, Progress indicator -Does this match your intent? -``` +### Custom Components +Unique to project — decomposed via Complexity Router --- -### Example 2: Text Detection +## INTERPRETATION APPROACH -``` -✓ TEXT ELEMENT DETECTED +**Trust-the-Agent:** Agent interprets with reasoning, user confirms. -I see horizontal line pairs in the sketch - this is text content. +When interpreting, explain: +- What visual cues you see (placement, color, shape) +- What you think it does (purpose, behavior) +- Why you chose this type -Quick Detection: -- 3 line pairs → 3 lines of text -- Routing to text analysis for detailed specification... - -→ Loading text-specific instructions... - -Text Analysis from Sketch: -- 3 lines of text (3 horizontal bar groups) -- Line thickness: 2px → ~20-24px font size -- Line spacing: 2px between lines → ~1.4 line-height -- Alignment: Left -- Content capacity: ~150-180 characters (50-60 per line) -``` - ---- - -### Example 3: Complex Component - -``` -🔍 Complex Component Detected - -I see this "Booking Calendar" has multiple states and interactions. - -Complexity Indicators I Found: -- Time-based interactions (selecting dates) -- Multiple states (available, booked, selected, disabled) -- Business rules (booking validation, date constraints) -- Cross-component sync (updates booking summary) - -To keep this manageable, I'll help you separate: -1. Page Context - Where it appears, size, position -2. Visual Design - How each state looks (for Figma) -3. Functional Logic - How it behaves, business rules - -Shall we decompose this component? -``` - ---- - -## KEY PRINCIPLES - -**Trust-the-Agent Approach:** -- Agent interprets, user confirms -- Not procedural checkbox selection -- Demonstrates intelligence and reasoning - -**Text Detection Priority:** -- Always check for text first -- Horizontal line pairs = text content -- Prevents misclassification - -**Complexity Routing:** -- Simple components stay in page -- Complex components get decomposed -- Enables modular architecture - -**Context-Aware:** -- Understands form flow -- Recognizes UI patterns -- Applies common sense - ---- - -## INTEGRATION - -### Within Page Specification Workflow - -**Called from:** `page-specification/steps-c/4c-03-document-section.md` - -**Flow:** -1. Designer working on section specification -2. Agent encounters object in sketch -3. Loads object router -4. Detects type and routes -5. Completes specification -6. Returns to section documentation - ---- - -### With Modular Architecture - -**Simple components:** -- Documented inline in page specification -- No separate component file needed - -**Complex components:** -- Routed through Complexity Router -- Creates feature folder structure -- Enables three-tier architecture -- See: `modular-architecture/` workflow - ---- - -## COMPLEXITY ROUTER - -**[COMPLEXITY-ROUTER.md](COMPLEXITY-ROUTER.md)** - -Provides decomposition coaching for complex components. - -**Features:** -- Detects complexity indicators -- Guides three-tier separation: - - Page context (where it appears) - - Visual design (how it looks) - - Functional logic (how it behaves) -- Creates feature folder structure -- Maintains modular architecture - -**Use when:** Component has multiple states, business rules, or complex interactions - ---- - -## TROUBLESHOOTING - -### "Agent misidentified the object" - -**Solution:** User provides clarification at confirmation step -- Choice 2: "Close but let me clarify" -- Choice 3: "No, it's actually something different" - -Agent adjusts interpretation and proceeds. - ---- - -### "Text not detected" - -**Check:** Are there horizontal line PAIRS? -- Single lines = decorative elements -- Line pairs = text markers - -**Reference:** [TEXT-DETECTION-PRIORITY.md](TEXT-DETECTION-PRIORITY.md) - ---- - -### "Component seems complex but agent didn't route to decomposition" - -**Solution:** Agent may have classified as simple -- User can request decomposition manually -- Or continue with inline documentation if preferred - -**Note:** Complexity routing is a suggestion, not mandatory +User can confirm, clarify, or correct. --- ## FILES REFERENCE -### Router Files +**Router Files:** +- [object-router.md](object-router.md) — Main routing logic +- [COMPLEXITY-ROUTER.md](COMPLEXITY-ROUTER.md) — Complexity assessment +- [ROUTER-FLOW-DIAGRAM.md](ROUTER-FLOW-DIAGRAM.md) — Visual flow +- [TEXT-DETECTION-PRIORITY.md](TEXT-DETECTION-PRIORITY.md) — Text detection rules -- **[object-router.md](object-router.md)** - Main routing logic -- **[COMPLEXITY-ROUTER.md](COMPLEXITY-ROUTER.md)** - Complexity assessment and coaching -- **[ROUTER-FLOW-DIAGRAM.md](ROUTER-FLOW-DIAGRAM.md)** - Visual flow documentation -- **[TEXT-DETECTION-PRIORITY.md](TEXT-DETECTION-PRIORITY.md)** - Text detection rules - -### Object Templates - -All templates in [templates/](templates/) folder: -- button.md -- heading-text.md -- text-input.md -- image.md -- link.md -- [Additional types referenced but not yet created] - ---- - -## NOTES - -**This is routing infrastructure** - not a user-facing workflow. - -**Used automatically** within page specification process when encountering objects in sketches. - -**Enables:** -- Consistent object specification -- Intelligent type detection -- Proper complexity routing -- Modular architecture support - ---- - -_Object Type Router - Intelligent detection, proper routing_ +**Object Templates:** All in [templates/](templates/) — button.md, heading-text.md, text-input.md, image.md, link.md diff --git a/src/workflows/4-ux-design/steps/step-02-substeps/page-init/page-init-lightweight.md b/src/workflows/4-ux-design/steps/step-02-substeps/page-init/page-init-lightweight.md index eaab8647d..d0e640fba 100644 --- a/src/workflows/4-ux-design/steps/step-02-substeps/page-init/page-init-lightweight.md +++ b/src/workflows/4-ux-design/steps/step-02-substeps/page-init/page-init-lightweight.md @@ -64,14 +64,14 @@ User situation: **Which scenario does this page belong to?** - + Existing scenarios: {{#each scenario in existing_scenarios}} - {{scenario.number}}: {{scenario.name}} {{/each}} - + Choose scenario [number] or "new" for a new scenario: - + Store scenario_number @@ -95,16 +95,7 @@ User situation: **What page comes BEFORE this one?** -{{#if existing_pages_in_scenario.length > 0}} -Existing pages: -{{#each page in existing_pages_in_scenario}} -- {{page.number}}: {{page.name}} -{{/each}} - Type page number, or "none" if this is the first page: -{{else}} -This is the first page in the scenario. Type "none": -{{/if}} Previous page: @@ -134,120 +125,9 @@ Path: `4-scenarios/{{scenario_path}}/{{page_number}}-{{page_slug}}/` Create: 1. Page folder: `{{page_number}}-{{page_slug}}/` 2. Sketches folder: `{{page_number}}-{{page_slug}}/sketches/` -3. Placeholder document: `{{page_number}}-{{page_slug}}.md` - +3. Placeholder document using template - -**Generate placeholder document:** - -File: `4-scenarios/{{scenario_path}}/{{page_number}}-{{page_slug}}/{{page_number}}-{{page_slug}}.md` - -Content: -```markdown -{{#if previous_page != "none"}} -← [{{previous_page}}](../{{previous_page_slug}}/{{previous_page_slug}}.md) -{{/if}} -{{#if next_page != "none" and next_page != "TBD"}} - | [{{next_page}}](../{{next_page_slug}}/{{next_page_slug}}.md) → -{{/if}} -{{#if next_page == "TBD"}} - | Next: TBD -{{/if}} - -![{{page_name}}](sketches/{{page_slug}}-concept.jpg) - -{{#if previous_page != "none"}} -← [{{previous_page}}](../{{previous_page_slug}}/{{previous_page_slug}}.md) -{{/if}} -{{#if next_page != "none" and next_page != "TBD"}} - | [{{next_page}}](../{{next_page_slug}}/{{next_page_slug}}.md) → -{{/if}} - -# {{page_number}} {{page_name}} - -**User Situation:** {{user_situation}} - -**Page Purpose:** {{page_purpose}} - ---- - -## Status - -⚠️ **PLACEHOLDER** - This page needs: -- [ ] Sketch or screenshot -- [ ] Section breakdown -- [ ] Object specifications -- [ ] Component links -- [ ] Interaction definitions -- [ ] States and variants - ---- - -## Navigation Context - -{{#if previous_page != "none"}} -**Previous:** {{previous_page}} -{{else}} -**This is the first page in the scenario** -{{/if}} - -{{#if next_page == "TBD"}} -**Next:** TBD (to be defined) -{{else if next_page != "none"}} -**Next:** {{next_page}} -{{else}} -**This is the last page in the scenario** -{{/if}} - ---- - -## Open Questions - - - -_No open questions at this time._ - ---- - -## Next Steps - -To complete this page specification: - -1. **Add a sketch**: Place your sketch in `sketches/` folder -2. **Run Page Process Workshop**: Analyze your sketch -3. **Specify sections**: Define all page sections -4. **Specify objects**: Define all interactive elements with Object IDs -5. **Link components**: Connect to design system components -6. **Document states**: Define loading, error, success, empty states -7. **Review open-questions.instructions.md**: Add relevant questions to Open Questions section -8. **Generate prototype**: Create interactive HTML preview - ---- - -{{#if previous_page != "none"}} -**Previous Step**: ← [{{previous_page}}](../{{previous_page_slug}}/{{previous_page_slug}}.md) -{{/if}} -{{#if next_page != "none" and next_page != "TBD"}} -**Next Step**: → [{{next_page}}](../{{next_page_slug}}/{{next_page_slug}}.md) -{{/if}} - ---- - -_Placeholder created using Whiteport Design Studio (WDS) methodology_ -``` +**See:** [substeps/lightweight-page-template.md](substeps/lightweight-page-template.md) --- @@ -280,18 +160,8 @@ _Placeholder created using Whiteport Design Studio (WDS) methodology_ - **Purpose:** {{page_purpose}} **Navigation:** -{{#if previous_page != "none"}} -- Previous: {{previous_page}} ✅ linked -{{else}} -- First page in scenario -{{/if}} -{{#if next_page != "none" and next_page != "TBD"}} -- Next: {{next_page}} ✅ linked -{{else if next_page == "TBD"}} -- Next: TBD -{{else}} -- Last page in scenario -{{/if}} +- Previous: {{previous_page}} {{#if linked}}✅ linked{{/if}} +- Next: {{next_page}} --- @@ -321,35 +191,6 @@ Based on user choice: --- -## KEY PRINCIPLES - -### ✅ **Navigation is Critical** -- Appears three times (above sketch, below sketch, document bottom) -- Links to previous/next pages -- Creates navigable flow -- Essential for comprehension - -### ✅ **Lightweight Setup** -- Quick to create -- No detailed specs yet -- Just enough to get started -- Ready for iteration - -### ✅ **Context Captured** -- Name, purpose, situation -- Scenario placement -- Page number assigned -- Flow established - -### ✅ **Open Questions Ready** -- Section included from start -- Reference `open-questions.instructions.md` during spec creation -- Auto-populate based on page characteristics -- Ensures no edge cases are missed - ---- - -**Created:** December 28, 2025 -**Purpose:** Quick page initialization with navigation +**Created:** December 28, 2025 +**Purpose:** Quick page initialization with navigation **Status:** Ready for WDS Presentation page - diff --git a/src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/flow-a-sketch.md b/src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/flow-a-sketch.md new file mode 100644 index 000000000..1d14565f3 --- /dev/null +++ b/src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/flow-a-sketch.md @@ -0,0 +1,28 @@ +# Flow A: Sketch Path + +**Activates when:** User chooses to draw a sketch (physical/digital) + +--- + +## Process + +**Perfect! Let's set up for your sketch.** + +I'll create: +1. Page placeholder with navigation +2. Sketches folder ready for upload +3. Basic page structure + +When you're ready, upload your sketch and we'll analyze it together using the Page Process Workshop. + +--- + +## Actions + +1. Run `page-init-lightweight.md` to create structure +2. User uploads sketch when ready +3. Return to `workshop-page-process.md` for analysis + +--- + +**This is the preferred path - sketches capture design intent best.** diff --git a/src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/flow-b-verbal.md b/src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/flow-b-verbal.md new file mode 100644 index 000000000..35045fcc4 --- /dev/null +++ b/src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/flow-b-verbal.md @@ -0,0 +1,138 @@ +# Flow B: Verbal Specification + +**Activates when:** User chooses to describe the page through discussion + +--- + +## Introduction + +**Great! Let's build the page concept through conversation.** + +We'll define: +- Page sections (what areas exist?) +- Section purposes (why does each section exist?) +- Key objects (what interactive elements?) +- User flow (how do they move through the page?) + +This creates a conceptual specification - the page where concept meets description. + +--- + +## SUBSTEP B1: Identify Sections + +**What are the main SECTIONS of this page?** + +Think about areas/blocks, like: +- Header/Navigation +- Hero/Banner +- Content areas +- Forms +- Footer + +List the sections from top to bottom: + +Store sections_list + +--- + +## SUBSTEP B2: Section Purposes + +**Now let's define each section's purpose:** + + +For each section in sections_list: + + **{{section.name}}** + + What is the PURPOSE of this section? + - What should the user understand/do here? + - Why does this section exist? + + Purpose: + + + Store section.purpose +End + + +--- + +## SUBSTEP B3: Key Objects + +**What are the KEY INTERACTIVE OBJECTS on this page?** + +Think about: +- Buttons (CTAs, actions) +- Forms (inputs, selectors) +- Links (navigation, external) +- Media (images, videos) + +List the most important interactive elements: + +Store key_objects + +--- + +## SUBSTEP B4: User Flow + +**How does the user move through this page?** + +- Where do they enter? +- What's their first action? +- What's the desired outcome? +- Where do they go next? + +Describe the flow: + +Store user_flow + +--- + +## SUBSTEP B5: Generate Specification + +**Creating conceptual specification...** + + +Generate page specification document: +- Page name and purpose +- Navigation (prev/next) +- For each section: + - Section name + - Section purpose + - Status: "CONCEPTUAL - Needs visualization" +- For each key object: + - Object name + - Object type + - Object purpose + - Status: "CONCEPTUAL - Needs specification" +- User flow description +- Next steps: "Create visualization (sketch/wireframe)" + +Save to: 4-scenarios/{{scenario_path}}/{{page_number}}-{{page_slug}}/{{page_number}}-{{page_slug}}.md + + +--- + +## Completion + +✅ **Conceptual page specification created!** + +**What we defined:** +- {{sections_list.length}} sections with purposes +- {{key_objects.length}} key interactive objects +- Complete user flow + +**Status:** CONCEPTUAL - Ready for visualization + +**Next steps:** +1. Create sketch/wireframe based on this concept +2. Upload visualization +3. Run Page Process Workshop to enhance specification + +Or: + +[A] Create ASCII layout now (quick visual) +[B] Done - I'll create sketch later +[C] Actually, let's refine the concept more + +Choice: diff --git a/src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/flow-c-ascii.md b/src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/flow-c-ascii.md new file mode 100644 index 000000000..92945f8a2 --- /dev/null +++ b/src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/flow-c-ascii.md @@ -0,0 +1,92 @@ +# Flow C: ASCII Layout + +**Activates when:** User chooses to create an ASCII layout + +--- + +## Introduction + +**Let's create a simple ASCII layout together.** + +⚠️ **Note:** ASCII is a last resort - sketches are much better for capturing design intent! + +We'll create a basic box-and-text layout to show structure. + +--- + +## Gather Sections + +**What are the main sections from top to bottom?** + +Example: +- Header +- Hero +- Features (3 columns) +- CTA +- Footer + +List sections: + +Store sections_for_ascii + +--- + +## Generate ASCII + + +Generate ASCII layout: + +``` +┌─────────────────────────────────────────┐ +│ [HEADER] │ +│ Logo | Nav | Contact │ +└─────────────────────────────────────────┘ + +┌─────────────────────────────────────────┐ +│ │ +│ [HERO SECTION] │ +│ │ +│ Headline Goes Here │ +│ Subheadline text here │ +│ │ +│ [CTA Button] │ +│ │ +└─────────────────────────────────────────┘ + +┌───────────┬───────────┬───────────┐ +│ │ │ │ +│ [Feature] │ [Feature] │ [Feature] │ +│ 1 │ 2 │ 3 │ +│ │ │ │ +│ Icon │ Icon │ Icon │ +│ Text │ Text │ Text │ +│ │ │ │ +└───────────┴───────────┴───────────┘ + +... (for each section) +``` + +Save as conceptual specification with ASCII visualization + + +--- + +## Completion + +✅ **ASCII layout created!** + +⚠️ **Remember:** This is a rough structural guide. + +**Recommended next steps:** +1. Use this ASCII as a reference +2. Create a proper sketch/wireframe +3. Upload and run Page Process Workshop + +**ASCII is helpful for structure, but lacks:** +- Visual hierarchy +- Spacing and proportions +- Typography details +- Color and visual design +- Actual content flow + +Ready to move forward? diff --git a/src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/flow-d-reference.md b/src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/flow-d-reference.md new file mode 100644 index 000000000..3ad72b2c7 --- /dev/null +++ b/src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/flow-d-reference.md @@ -0,0 +1,69 @@ +# Flow D: Reference Page + +**Activates when:** User has a similar page to reference + +--- + +## Gather Reference + +**Which page is this similar to?** + +Provide: +- Page name or URL +- What file path (if internal project) +- Or description of reference page + +Reference: + +Store reference_page + +--- + +## Identify Differences + +**What are the KEY DIFFERENCES from the reference?** + +What changes from the reference page? + +Differences: + +Store differences + +--- + +## Generate Specification + +**Creating page based on reference...** + + +If internal reference exists: + 1. Copy reference specification structure + 2. Update with differences + 3. Mark sections that need updates + 4. Preserve navigation pattern + +If external reference: + 1. Describe reference structure + 2. Note differences + 3. Create conceptual specification + 4. Recommend creating sketch showing changes + +Generate specification document + + +--- + +## Completion + +✅ **Reference-based page specification created!** + +**Based on:** {{reference_page}} + +**Key differences noted:** {{differences}} + +**Next steps:** +- Review generated specification +- Create sketch showing unique elements +- Run Page Process Workshop to refine + +Ready? diff --git a/src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/flow-e-html.md b/src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/flow-e-html.md new file mode 100644 index 000000000..ef2d55ec7 --- /dev/null +++ b/src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/flow-e-html.md @@ -0,0 +1,131 @@ +# Flow E: Generate HTML Prototype + +**Activates when:** User chooses to generate HTML and screenshot it + +--- + +## Introduction + +**Perfect! Let's generate an HTML prototype based on your concept.** + +This creates a working page that you can: +- View in browser +- Screenshot for documentation +- Test responsive behavior +- Use as starting point for development + +The screenshot becomes your "sketch" for the specification. + +--- + +## Benefits + +- ✅ Professional, pixel-perfect visualization +- ✅ Tests actual layout behavior +- ✅ Responsive/mobile preview available +- ✅ Can iterate quickly +- ✅ Screenshot becomes the "sketch" +- ✅ Prototype is already built! + +**Perfect for:** +- Users who can describe but can't draw +- Testing responsive layouts +- Quick professional mockups +- When prototype comes before final design + +--- + +## SUBSTEP E1: Define Basic Structure + +**Based on your page concept:** + +**Page:** {{page_name}} +**Sections:** {{sections_list}} +**Key Objects:** {{key_objects}} + +I'll generate a clean HTML prototype with: +- Semantic HTML structure +- Basic Tailwind CSS styling (or vanilla CSS) +- Placeholder content based on your descriptions +- Responsive layout +- Interactive elements (buttons, forms, etc.) + +**Any specific styling preferences?** + +[A] Clean, minimal (default) +[B] Modern SaaS style +[C] Professional/corporate +[D] Creative/bold +[E] Match an existing site (describe) + +Styling: + +Store styling_preference + +--- + +## SUBSTEP E2: Generate HTML + + +**Generate HTML prototype:** + +1. Create semantic HTML structure for each section +2. Add Tailwind CSS classes (or vanilla CSS) +3. Include placeholder content from user's descriptions +4. Add interactive elements with proper attributes +5. Make responsive (mobile-first) +6. Include basic states (hover, focus, etc.) + +File: `prototypes/{{page_slug}}-prototype.html` + +Save to: `4-scenarios/{{scenario_path}}/{{page_number}}-{{page_slug}}/prototypes/` + + +--- + +## SUBSTEP E3: View and Capture + +**Prototype generated!** 🎉 + +**File location:** +`4-scenarios/{{scenario_path}}/{{page_number}}-{{page_slug}}/prototypes/{{page_slug}}-prototype.html` + +**Next steps:** + +1. **Open in browser** - Double-click the HTML file +2. **Review the layout** - Does it match your vision? +3. **Test responsive** - Resize browser window +4. **Take screenshots:** + - Desktop view (full page) + - Mobile view (if needed) + - Key sections (close-ups) +5. **Save screenshots** to `sketches/` folder + +**Screenshot naming:** +- `{{page_slug}}-desktop.jpg` - Full desktop view +- `{{page_slug}}-mobile.jpg` - Mobile view +- `{{page_slug}}-section-name.jpg` - Section close-ups + +**Ready to capture screenshots?** + +Once you've saved the screenshots, type "done" and I'll analyze them: + +Status: + +Wait for user confirmation + +--- + +## SUBSTEP E4: Iterate If Needed + +**How does the prototype look?** + +[A] Perfect - I've captured screenshots +[B] Need adjustments - let me describe changes +[C] Completely different direction - let's revise + +Choice: + +**If A:** Route to `workshop-page-process.md` for analysis +**If B:** Update HTML based on feedback, return to E3 +**If C:** Return to main workshop STEP 1 to redefine concept diff --git a/src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/lightweight-page-template.md b/src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/lightweight-page-template.md new file mode 100644 index 000000000..268506e94 --- /dev/null +++ b/src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/lightweight-page-template.md @@ -0,0 +1,135 @@ +# Lightweight Page Template + +Template for generating page placeholder documents in page-init-lightweight workflow. + +--- + +## File Location + +`4-scenarios/{{scenario_path}}/{{page_number}}-{{page_slug}}/{{page_number}}-{{page_slug}}.md` + +--- + +## Template + +```markdown +{{#if previous_page != "none"}} +← [{{previous_page}}](../{{previous_page_slug}}/{{previous_page_slug}}.md) +{{/if}} +{{#if next_page != "none" and next_page != "TBD"}} + | [{{next_page}}](../{{next_page_slug}}/{{next_page_slug}}.md) → +{{/if}} +{{#if next_page == "TBD"}} + | Next: TBD +{{/if}} + +![{{page_name}}](sketches/{{page_slug}}-concept.jpg) + +{{#if previous_page != "none"}} +← [{{previous_page}}](../{{previous_page_slug}}/{{previous_page_slug}}.md) +{{/if}} +{{#if next_page != "none" and next_page != "TBD"}} + | [{{next_page}}](../{{next_page_slug}}/{{next_page_slug}}.md) → +{{/if}} + +# {{page_number}} {{page_name}} + +**User Situation:** {{user_situation}} + +**Page Purpose:** {{page_purpose}} + +--- + +## Status + +⚠️ **PLACEHOLDER** - This page needs: +- [ ] Sketch or screenshot +- [ ] Section breakdown +- [ ] Object specifications +- [ ] Component links +- [ ] Interaction definitions +- [ ] States and variants + +--- + +## Navigation Context + +{{#if previous_page != "none"}} +**Previous:** {{previous_page}} +{{else}} +**This is the first page in the scenario** +{{/if}} + +{{#if next_page == "TBD"}} +**Next:** TBD (to be defined) +{{else if next_page != "none"}} +**Next:** {{next_page}} +{{else}} +**This is the last page in the scenario** +{{/if}} + +--- + +## Open Questions + + + +_No open questions at this time._ + +--- + +## Next Steps + +To complete this page specification: + +1. **Add a sketch**: Place your sketch in `sketches/` folder +2. **Run Page Process Workshop**: Analyze your sketch +3. **Specify sections**: Define all page sections +4. **Specify objects**: Define all interactive elements with Object IDs +5. **Link components**: Connect to design system components +6. **Document states**: Define loading, error, success, empty states +7. **Review open-questions.instructions.md**: Add relevant questions to Open Questions section +8. **Generate prototype**: Create interactive HTML preview + +--- + +{{#if previous_page != "none"}} +**Previous Step**: ← [{{previous_page}}](../{{previous_page_slug}}/{{previous_page_slug}}.md) +{{/if}} +{{#if next_page != "none" and next_page != "TBD"}} +**Next Step**: → [{{next_page}}](../{{next_page_slug}}/{{next_page_slug}}.md) +{{/if}} + +--- + +_Placeholder created using Whiteport Design Studio (WDS) methodology_ +``` + +--- + +## Key Principles + +### ✅ **Navigation is Critical** +- Appears three times (above sketch, below sketch, document bottom) +- Links to previous/next pages +- Creates navigable flow +- Essential for comprehension + +### ✅ **Open Questions Ready** +- Section included from start +- Reference `open-questions.instructions.md` during spec creation +- Auto-populate based on page characteristics +- Ensures no edge cases are missed diff --git a/src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/page-process-templates.md b/src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/page-process-templates.md new file mode 100644 index 000000000..9246ca14e --- /dev/null +++ b/src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/page-process-templates.md @@ -0,0 +1,130 @@ +# Page Process Workshop Templates + +Templates for comparison output and change detection displays. + +--- + +## Change Detection Output Template + +```handlebars +{{#if has_changes}} +🔍 **Changes detected:** + +{{#if unchanged_sections.length > 0}} +✅ **Unchanged sections** ({{unchanged_sections.length}}): +{{#each section in unchanged_sections}} +- {{section.name}} +{{/each}} +{{/if}} + +{{#if modified_sections.length > 0}} +✏️ **Modified sections** ({{modified_sections.length}}): +{{#each section in modified_sections}} +- {{section.name}}: {{section.change_description}} +{{/each}} +{{/if}} + +{{#if new_sections.length > 0}} +➕ **New sections added** ({{new_sections.length}}): +{{#each section in new_sections}} +- {{section.name}}: {{section.description}} +{{/each}} +{{/if}} + +{{#if completed_sections.length > 0}} +✨ **TBD sections now complete** ({{completed_sections.length}}): +{{#each section in completed_sections}} +- {{section.name}}: Ready to specify +{{/each}} +{{/if}} + +{{#if removed_sections.length > 0}} +⚠️ **Sections removed** ({{removed_sections.length}}): +{{#each section in removed_sections}} +- {{section.name}} +{{/each}} +{{/if}} + +{{else}} +✅ **No changes detected** + +This sketch appears identical to the existing specification. +{{/if}} +``` + +--- + +## Detailed Comparison Template + +```handlebars +**Detailed Section-by-Section Comparison:** + +{{#each section in modified_sections}} + +--- + +### {{section.name}} + +**Current specification:** +{{section.current_spec_summary}} + +**New sketch shows:** +{{section.new_sketch_summary}} + +**Detected changes:** +{{#each change in section.changes}} +- {{change.description}} +{{/each}} + +**Confidence:** {{section.confidence}}% + +--- +{{/each}} +``` + +--- + +## Update Summary Template + +```handlebars +✅ **Page specification updated!** + +**Summary:** +{{#if updated_count > 0}} +- {{updated_count}} sections updated +{{/if}} +{{#if added_count > 0}} +- {{added_count}} sections added +{{/if}} +{{#if preserved_count > 0}} +- {{preserved_count}} sections preserved (unchanged) +{{/if}} +{{#if removed_count > 0}} +- {{removed_count}} sections removed +{{/if}} + +**Updated file:** `{{page_spec_path}}` + +**Sketch saved to:** `{{sketch_path}}` +``` + +--- + +## Menu Options + +**Update Strategy Menu (with changes):** +- [A] Update all changed/new/completed sections +- [B] Pick specific sections to update +- [C] Show me detailed comparison first +- [D] Actually, this is the same - cancel + +**Update Strategy Menu (only removals):** +- [A] Remove deleted sections from spec +- [B] Keep them marked as "removed from design" +- [C] Cancel - I'll fix the sketch + +**Completion Menu:** +- [A] Generate HTML prototype +- [B] Add another page +- [C] Update another section +- [D] Done with this page diff --git a/src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/placeholder-templates.md b/src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/placeholder-templates.md new file mode 100644 index 000000000..a4261bd1f --- /dev/null +++ b/src/workflows/4-ux-design/steps/step-02-substeps/page-init/substeps/placeholder-templates.md @@ -0,0 +1,153 @@ +# Placeholder Page Templates + +Templates for generating placeholder page documents. + +--- + +## Page Placeholder Document Template + +File: `4-scenarios/{{scenario_path}}/{{page.number}}-{{page.slug}}/{{page.number}}-{{page.slug}}.md` + +```markdown +{{#if @index > 0}} +← [{{pages_list[@index - 1].number}}-{{pages_list[@index - 1].slug}}](../{{pages_list[@index - 1].number}}-{{pages_list[@index - 1].slug}}/{{pages_list[@index - 1].number}}-{{pages_list[@index - 1].slug}}.md) +{{/if}} +{{#if @index < pages_list.length - 1}} +| [{{pages_list[@index + 1].number}}-{{pages_list[@index + 1].slug}}](../{{pages_list[@index + 1].number}}-{{pages_list[@index + 1].slug}}/{{pages_list[@index + 1].number}}-{{pages_list[@index + 1].slug}}.md) → +{{/if}} + +# {{page.number}} {{page.name}} + +**User Situation:** {{page.situation}} + +**Page Purpose:** {{page.purpose}} + +--- + +## Status + +⚠️ **PLACEHOLDER** - This page needs: +- [ ] Sketch or screenshot +- [ ] Section breakdown +- [ ] Object specifications +- [ ] Component links +- [ ] Interaction definitions +- [ ] States and variants + +--- + +## Next Steps + +To complete this page specification: + +1. **Add a sketch**: Place sketch in `sketches/` folder +2. **Run Workshop A**: Sketch Analysis Workshop to break down the visual +3. **Specify objects**: Define all interactive elements with Object IDs +4. **Link components**: Connect to design system components +5. **Document states**: Define loading, error, success, empty states + +--- + +{{#if @index > 0}} +**Previous Step**: ← [{{pages_list[@index - 1].number}}-{{pages_list[@index - 1].slug}}](../{{pages_list[@index - 1].number}}-{{pages_list[@index - 1].slug}}/{{pages_list[@index - 1].number}}-{{pages_list[@index - 1].slug}}.md) +{{/if}} +{{#if @index < pages_list.length - 1}} +**Next Step**: → [{{pages_list[@index + 1].number}}-{{pages_list[@index + 1].slug}}](../{{pages_list[@index + 1].number}}-{{pages_list[@index + 1].slug}}/{{pages_list[@index + 1].number}}-{{pages_list[@index + 1].slug}}.md) +{{/if}} + +--- + +_Placeholder created using Whiteport Design Studio (WDS) methodology_ +``` + +--- + +## Scenario Overview Template + +File: `4-scenarios/{{scenario_path}}/00-{{scenario_slug}}-scenario.md` + +```markdown +# {{scenario_number}} {{scenario_name}} - Scenario Overview + +**Project**: {{project_name}} +**Date Created**: {{date}} +**Last Updated**: {{date}} + +## Scenario Overview + +[Brief description of this scenario - to be filled in] + +## Scenario Steps + +{{#each page in pages_list}} +### **{{page.number}} {{page.name}}** +**Purpose**: {{page.purpose}} +**Status**: ⚠️ Placeholder +**Files**: [{{page.number}}-{{page.slug}}.md]({{page.number}}-{{page.slug}}/{{page.number}}-{{page.slug}}.md) + +{{/each}} + +## User Journey Flow + +``` +{{#each page in pages_list}} +{{page.number}}-{{page.slug}}{{#unless @last}} → {{/unless}} +{{/each}} +``` + +## Status + +{{pages_list.length}} placeholder pages created. Each page needs: +- Sketch or visual concept +- Detailed specifications +- Object definitions +- Component links + +--- + +_Created using Whiteport Design Studio (WDS) methodology_ +``` + +--- + +## Scenario Tracking Template + +File: `4-scenarios/{{scenario_path}}/scenario-tracking.yaml` + +```yaml +scenario_number: {{scenario_number}} +scenario_name: "{{scenario_name}}" +pages_list: +{{#each page in pages_list}} + - name: "{{page.name}}" + slug: "{{page.slug}}" + page_number: "{{page.number}}" + purpose: "{{page.purpose}}" + status: "placeholder" +{{/each}} +current_page_index: 0 +total_pages: {{pages_list.length}} +created_date: "{{date}}" +``` + +--- + +## When to Use Placeholders + +**Advantages:** +- Quick mapping of entire flow +- Clear navigation before details +- Easy to see gaps or redundancies +- Can be reviewed by stakeholders early +- Team can work on different pages in parallel + +**Use when:** +- New projects starting from scratch +- Complex multi-page scenarios +- When need for early stakeholder review +- Before diving into visual design + +**Don't use when:** +- Single page projects +- When sketch already exists (use Workshop A) +- Small modifications to existing flow diff --git a/src/workflows/4-ux-design/steps/step-02-substeps/page-init/workshop-c-placeholder-pages.md b/src/workflows/4-ux-design/steps/step-02-substeps/page-init/workshop-c-placeholder-pages.md index 98d77526c..676afea1f 100644 --- a/src/workflows/4-ux-design/steps/step-02-substeps/page-init/workshop-c-placeholder-pages.md +++ b/src/workflows/4-ux-design/steps/step-02-substeps/page-init/workshop-c-placeholder-pages.md @@ -54,9 +54,7 @@ This will be your first scenario. What should we call it? Scenario name: {{/if}} - -Store scenario_number and scenario_name - +Store scenario_number and scenario_name --- @@ -85,56 +83,12 @@ Number of pages: I'll guide you through {{pages_count}} pages... -For page_index from 1 to pages_count, run this loop: +For each page, gather: +1. **Page name** (examples: "Start Page", "Sign In", "Checkout") +2. **Page purpose** (1-2 sentences: what user accomplishes) +3. **User situation** (what just happened, what they're trying to do) ---- - -### Page {{page_index}} of {{pages_count}} - - - -**What should we call this page?** - -Examples: -- "Start Page" / "Home" -- "Sign In" -- "User Profile" -- "Checkout" -- "Confirmation" - -Page name: - - -Store page_name -Generate page_slug -Calculate page_number (scenario.page_index) - - -**What's the PURPOSE of "{{page_name}}"?** - -In 1-2 sentences: -- What does the user accomplish here? -- What happens on this page? - -Purpose: - -Store page_purpose - -**What's the USER'S SITUATION when they arrive?** - -What just happened? What are they trying to do? - -User situation: - -Store user_situation - -✓ **Page {{page_index}} defined:** - -{{page_number}}-{{page_slug}}: {{page_name}} -- Purpose: {{page_purpose}} -- Situation: {{user_situation}} - -Continue to next page +Store page_name, page_purpose, user_situation for each page --- @@ -144,12 +98,7 @@ User situation: **Scenario {{scenario_number}}: {{scenario_name}}** -{{#each page in pages_list}} -{{@index + 1}}. **{{page.number}}-{{page.slug}}** - {{page.name}} - Purpose: {{page.purpose}} - User: {{page.situation}} - -{{/each}} +[Display numbered list of all pages with purposes] Does this flow make sense? Any pages missing or in wrong order? @@ -162,161 +111,25 @@ Does this flow make sense? Any pages missing or in wrong order? Action: - -Process user adjustments: -- Add pages if needed -- Remove pages if requested -- Renumber pages after changes - - --- -## PHASE 6: GENERATE PLACEHOLDER DOCUMENTS +## PHASE 6: GENERATE DOCUMENTS -**Perfect! Creating your placeholder pages now...** - -Generating {{pages_list.length}} page documents... +**Perfect! Creating your placeholder pages now...** For each page in pages_list: +1. Create folder structure with sketches subfolder +2. Generate placeholder document using template +3. Create scenario overview document +4. Create scenario tracking file -**Create folder structure:** -`4-scenarios/{{scenario_path}}/{{page.number}}-{{page.slug}}/` -`4-scenarios/{{scenario_path}}/{{page.number}}-{{page.slug}}/sketches/` - -**Generate placeholder document:** - -File: `4-scenarios/{{scenario_path}}/{{page.number}}-{{page.slug}}/{{page.number}}-{{page.slug}}.md` - -Content: -```markdown -{{#if @index > 0}} -← [{{pages_list[@index - 1].number}}-{{pages_list[@index - 1].slug}}](../{{pages_list[@index - 1].number}}-{{pages_list[@index - 1].slug}}/{{pages_list[@index - 1].number}}-{{pages_list[@index - 1].slug}}.md) -{{/if}} -{{#if @index < pages_list.length - 1}} -| [{{pages_list[@index + 1].number}}-{{pages_list[@index + 1].slug}}](../{{pages_list[@index + 1].number}}-{{pages_list[@index + 1].slug}}/{{pages_list[@index + 1].number}}-{{pages_list[@index + 1].slug}}.md) → -{{/if}} - -# {{page.number}} {{page.name}} - -**User Situation:** {{page.situation}} - -**Page Purpose:** {{page.purpose}} - ---- - -## Status - -⚠️ **PLACEHOLDER** - This page needs: -- [ ] Sketch or screenshot -- [ ] Section breakdown -- [ ] Object specifications -- [ ] Component links -- [ ] Interaction definitions -- [ ] States and variants - ---- - -## Next Steps - -To complete this page specification: - -1. **Add a sketch**: Place sketch in `sketches/` folder -2. **Run Workshop A**: Sketch Analysis Workshop to break down the visual -3. **Specify objects**: Define all interactive elements with Object IDs -4. **Link components**: Connect to design system components -5. **Document states**: Define loading, error, success, empty states - ---- - -{{#if @index > 0}} -**Previous Step**: ← [{{pages_list[@index - 1].number}}-{{pages_list[@index - 1].slug}}](../{{pages_list[@index - 1].number}}-{{pages_list[@index - 1].slug}}/{{pages_list[@index - 1].number}}-{{pages_list[@index - 1].slug}}.md) -{{/if}} -{{#if @index < pages_list.length - 1}} -**Next Step**: → [{{pages_list[@index + 1].number}}-{{pages_list[@index + 1].slug}}](../{{pages_list[@index + 1].number}}-{{pages_list[@index + 1].slug}}/{{pages_list[@index + 1].number}}-{{pages_list[@index + 1].slug}}.md) -{{/if}} - ---- - -_Placeholder created using Whiteport Design Studio (WDS) methodology_ -``` - - - -**Create scenario overview document:** - -File: `4-scenarios/{{scenario_path}}/00-{{scenario_slug}}-scenario.md` - -Content: -```markdown -# {{scenario_number}} {{scenario_name}} - Scenario Overview - -**Project**: {{project_name}} -**Date Created**: {{date}} -**Last Updated**: {{date}} - -## Scenario Overview - -[Brief description of this scenario - to be filled in] - -## Scenario Steps - -{{#each page in pages_list}} -### **{{page.number}} {{page.name}}** -**Purpose**: {{page.purpose}} -**Status**: ⚠️ Placeholder -**Files**: [{{page.number}}-{{page.slug}}.md]({{page.number}}-{{page.slug}}/{{page.number}}-{{page.slug}}.md) - -{{/each}} - -## User Journey Flow - -``` -{{#each page in pages_list}} -{{page.number}}-{{page.slug}}{{#unless @last}} → {{/unless}} -{{/each}} -``` - -## Status - -{{pages_list.length}} placeholder pages created. Each page needs: -- Sketch or visual concept -- Detailed specifications -- Object definitions -- Component links - ---- - -_Created using Whiteport Design Studio (WDS) methodology_ -``` - - - -**Create scenario tracking file:** - -File: `4-scenarios/{{scenario_path}}/scenario-tracking.yaml` - -Content: -```yaml -scenario_number: {{scenario_number}} -scenario_name: "{{scenario_name}}" -pages_list: -{{#each page in pages_list}} - - name: "{{page.name}}" - slug: "{{page.slug}}" - page_number: "{{page.number}}" - purpose: "{{page.purpose}}" - status: "placeholder" -{{/each}} -current_page_index: 0 -total_pages: {{pages_list.length}} -created_date: "{{date}}" -``` +**See:** [substeps/placeholder-templates.md](substeps/placeholder-templates.md) for all templates --- -## PHASE 7: COMPLETION SUMMARY +## PHASE 7: COMPLETION ✅ **Placeholder pages created!** @@ -328,32 +141,7 @@ created_date: "{{date}}" - 1 scenario overview document - 1 scenario tracking file -**File structure:** -``` -4-scenarios/ - {{scenario_path}}/ - 00-{{scenario_slug}}-scenario.md - scenario-tracking.yaml -{{#each page in pages_list}} - {{page.number}}-{{page.slug}}/ - {{page.number}}-{{page.slug}}.md ⚠️ PLACEHOLDER - sketches/ -{{/each}} -``` - -**Your scenario flow:** -``` -{{#each page in pages_list}} -{{page.number}}-{{page.slug}}: {{page.name}} -{{/each}} -``` - ---- - -## Next Steps - -You can now: - +**Next Steps:** 1. **Add sketches** - Upload visuals for each page 2. **Complete specifications** - Run Workshop A (Sketch Analysis) for each page 3. **Add more pages** - Come back and add pages to this scenario @@ -362,9 +150,7 @@ You can now: **Ready to work on a specific page?** Pick a page to work on: -{{#each page in pages_list}} -[{{@index + 1}}] {{page.name}} -{{/each}} +[1-N] Page name [N] Add another scenario [D] Done for now @@ -380,27 +166,3 @@ Choice: - If user selects [N] → Route to scenario-init workshop - If user selects [D] → Return to main UX design menu - ---- - -## NOTES FOR IMPLEMENTATION - -**Advantages of placeholders:** -- Quick mapping of entire flow -- Clear navigation before details -- Easy to see gaps or redundancies -- Can be reviewed by stakeholders early -- Team can work on different pages in parallel - -**When to use:** -- New projects starting from scratch -- Complex multi-page scenarios -- When need for early stakeholder review -- Before diving into visual design - -**When NOT to use:** -- Single page projects -- When sketch already exists (use Workshop A) -- Small modifications to existing flow - - diff --git a/src/workflows/4-ux-design/steps/step-02-substeps/page-init/workshop-page-creation.md b/src/workflows/4-ux-design/steps/step-02-substeps/page-init/workshop-page-creation.md index 76d9faa6c..a94352ce7 100644 --- a/src/workflows/4-ux-design/steps/step-02-substeps/page-init/workshop-page-creation.md +++ b/src/workflows/4-ux-design/steps/step-02-substeps/page-init/workshop-page-creation.md @@ -45,455 +45,19 @@ Choice: --- -## NOTE ON OPTION E (HTML Prototype) +## FLOW ROUTING -**This is the bridge method:** -``` -Concept → HTML Code → Render → Screenshot → Documentation -``` +Based on user choice, load the appropriate flow: -**Benefits:** -- ✅ Professional, pixel-perfect visualization -- ✅ Tests actual layout behavior -- ✅ Responsive/mobile preview available -- ✅ Can iterate quickly -- ✅ Screenshot becomes the "sketch" -- ✅ Prototype is already built! +| Choice | Flow | File | +|--------|------|------| +| **A** | Sketch Path | [substeps/flow-a-sketch.md](substeps/flow-a-sketch.md) | +| **B** | Verbal Specification | [substeps/flow-b-verbal.md](substeps/flow-b-verbal.md) | +| **C** | ASCII Layout | [substeps/flow-c-ascii.md](substeps/flow-c-ascii.md) | +| **D** | Reference Page | [substeps/flow-d-reference.md](substeps/flow-d-reference.md) | +| **E** | HTML Prototype | [substeps/flow-e-html.md](substeps/flow-e-html.md) | -**Perfect for:** -- Users who can describe but can't draw -- Testing responsive layouts -- Quick professional mockups -- When prototype comes before final design - ---- - -## FLOW A: SKETCH PATH - - - -**Perfect! Let's set up for your sketch.** - -I'll create: -1. Page placeholder with navigation -2. Sketches folder ready for upload -3. Basic page structure - -When you're ready, upload your sketch and we'll analyze it together using the Page Process Workshop. - - -1. Run page-init-lightweight.md to create structure -2. User uploads sketch when ready -3. Return to workshop-page-process.md for analysis - - - - ---- - -## FLOW B: VERBAL SPECIFICATION - - - -**Great! Let's build the page concept through conversation.** - -We'll define: -- Page sections (what areas exist?) -- Section purposes (why does each section exist?) -- Key objects (what interactive elements?) -- User flow (how do they move through the page?) - -This creates a conceptual specification - the page where concept meets description. - -### SUBSTEP B1: IDENTIFY SECTIONS - -**What are the main SECTIONS of this page?** - -Think about areas/blocks, like: -- Header/Navigation -- Hero/Banner -- Content areas -- Forms -- Footer - -List the sections from top to bottom: - -Store sections_list - -### SUBSTEP B2: SECTION PURPOSES - -**Now let's define each section's purpose:** - - -For each section in sections_list: - - **{{section.name}}** - - What is the PURPOSE of this section? - - What should the user understand/do here? - - Why does this section exist? - - Purpose: - - - Store section.purpose -End - - -### SUBSTEP B3: KEY OBJECTS - -**What are the KEY INTERACTIVE OBJECTS on this page?** - -Think about: -- Buttons (CTAs, actions) -- Forms (inputs, selectors) -- Links (navigation, external) -- Media (images, videos) - -List the most important interactive elements: - -Store key_objects - -### SUBSTEP B4: USER FLOW - -**How does the user move through this page?** - -- Where do they enter? -- What's their first action? -- What's the desired outcome? -- Where do they go next? - -Describe the flow: - -Store user_flow - -### SUBSTEP B5: GENERATE SPECIFICATION - -**Creating conceptual specification...** - - -Generate page specification document: -- Page name and purpose -- Navigation (prev/next) -- For each section: - - Section name - - Section purpose - - Status: "CONCEPTUAL - Needs visualization" -- For each key object: - - Object name - - Object type - - Object purpose - - Status: "CONCEPTUAL - Needs specification" -- User flow description -- Next steps: "Create visualization (sketch/wireframe)" - -Save to: 4-scenarios/{{scenario_path}}/{{page_number}}-{{page_slug}}/{{page_number}}-{{page_slug}}.md - - -✅ **Conceptual page specification created!** - -**What we defined:** -- {{sections_list.length}} sections with purposes -- {{key_objects.length}} key interactive objects -- Complete user flow - -**Status:** CONCEPTUAL - Ready for visualization - -**Next steps:** -1. Create sketch/wireframe based on this concept -2. Upload visualization -3. Run Page Process Workshop to enhance specification - -Or: - -[A] Create ASCII layout now (quick visual) -[B] Done - I'll create sketch later -[C] Actually, let's refine the concept more - -Choice: - - - ---- - -## FLOW E: GENERATE HTML PROTOTYPE - - - -**Perfect! Let's generate an HTML prototype based on your concept.** - -This creates a working page that you can: -- View in browser -- Screenshot for documentation -- Test responsive behavior -- Use as starting point for development - -The screenshot becomes your "sketch" for the specification. - -### SUBSTEP E1: DEFINE BASIC STRUCTURE - -**Based on your page concept:** - -**Page:** {{page_name}} -**Sections:** {{sections_list}} -**Key Objects:** {{key_objects}} - -I'll generate a clean HTML prototype with: -- Semantic HTML structure -- Basic Tailwind CSS styling (or vanilla CSS) -- Placeholder content based on your descriptions -- Responsive layout -- Interactive elements (buttons, forms, etc.) - -**Any specific styling preferences?** - -[A] Clean, minimal (default) -[B] Modern SaaS style -[C] Professional/corporate -[D] Creative/bold -[E] Match an existing site (describe) - -Styling: - -Store styling_preference - -### SUBSTEP E2: GENERATE HTML - - -**Generate HTML prototype:** - -1. Create semantic HTML structure for each section -2. Add Tailwind CSS classes (or vanilla CSS) -3. Include placeholder content from user's descriptions -4. Add interactive elements with proper attributes -5. Make responsive (mobile-first) -6. Include basic states (hover, focus, etc.) - -File: `prototypes/{{page_slug}}-prototype.html` - -Template structure: -```html - - - - - - {{page_name}} - Prototype - - - - - {{#each section in sections_list}} -
- -
- {{/each}} - - -``` - -Save to: `4-scenarios/{{scenario_path}}/{{page_number}}-{{page_slug}}/prototypes/` - - -### SUBSTEP E3: VIEW AND CAPTURE - -**Prototype generated!** 🎉 - -**File location:** -`4-scenarios/{{scenario_path}}/{{page_number}}-{{page_slug}}/prototypes/{{page_slug}}-prototype.html` - -**Next steps:** - -1. **Open in browser** - Double-click the HTML file -2. **Review the layout** - Does it match your vision? -3. **Test responsive** - Resize browser window -4. **Take screenshots:** - - Desktop view (full page) - - Mobile view (if needed) - - Key sections (close-ups) -5. **Save screenshots** to `sketches/` folder - -**Screenshot naming:** -- `{{page_slug}}-desktop.jpg` - Full desktop view -- `{{page_slug}}-mobile.jpg` - Mobile view -- `{{page_slug}}-section-name.jpg` - Section close-ups - -**Ready to capture screenshots?** - -Once you've saved the screenshots, type "done" and I'll analyze them: - -Status: - -Wait for user confirmation - -### SUBSTEP E4: ITERATE IF NEEDED - -**How does the prototype look?** - -[A] Perfect - I've captured screenshots -[B] Need adjustments - let me describe changes -[C] Completely different direction - let's revise - -Choice: - - - - User should have screenshots in sketches/ folder - Route to: workshop-page-process.md for analysis - - - - - What changes are needed? - - Update HTML prototype based on feedback - Regenerate sections as needed - Return to SUBSTEP E3 (view and capture) - - - - - Return to STEP 1: PAGE CONCEPT to redefine - - - - ---- - - - -**Let's create a simple ASCII layout together.** - -⚠️ **Note:** ASCII is a last resort - sketches are much better for capturing design intent! - -We'll create a basic box-and-text layout to show structure. - -**What are the main sections from top to bottom?** - -Example: -- Header -- Hero -- Features (3 columns) -- CTA -- Footer - -List sections: - -Store sections_for_ascii - - -Generate ASCII layout: - -``` -┌─────────────────────────────────────────┐ -│ [HEADER] │ -│ Logo | Nav | Contact │ -└─────────────────────────────────────────┘ - -┌─────────────────────────────────────────┐ -│ │ -│ [HERO SECTION] │ -│ │ -│ Headline Goes Here │ -│ Subheadline text here │ -│ │ -│ [CTA Button] │ -│ │ -└─────────────────────────────────────────┘ - -┌───────────┬───────────┬───────────┐ -│ │ │ │ -│ [Feature] │ [Feature] │ [Feature] │ -│ 1 │ 2 │ 3 │ -│ │ │ │ -│ Icon │ Icon │ Icon │ -│ Text │ Text │ Text │ -│ │ │ │ -└───────────┴───────────┴───────────┘ - -... (for each section) -``` - -Save as conceptual specification with ASCII visualization - - -✅ **ASCII layout created!** - -⚠️ **Remember:** This is a rough structural guide. - -**Recommended next steps:** -1. Use this ASCII as a reference -2. Create a proper sketch/wireframe -3. Upload and run Page Process Workshop - -**ASCII is helpful for structure, but lacks:** -- Visual hierarchy -- Spacing and proportions -- Typography details -- Color and visual design -- Actual content flow - -Ready to move forward? - - - ---- - -## FLOW D: REFERENCE PAGE - - - -**Which page is this similar to?** - -Provide: -- Page name or URL -- What file path (if internal project) -- Or description of reference page - -Reference: - -Store reference_page - -**What are the KEY DIFFERENCES from the reference?** - -What changes from the reference page? - -Differences: - -Store differences - -**Creating page based on reference...** - - -If internal reference exists: - 1. Copy reference specification structure - 2. Update with differences - 3. Mark sections that need updates - 4. Preserve navigation pattern - -If external reference: - 1. Describe reference structure - 2. Note differences - 3. Create conceptual specification - 4. Recommend creating sketch showing changes - -Generate specification document - - -✅ **Reference-based page specification created!** - -**Based on:** {{reference_page}} - -**Key differences noted:** {{differences}} - -**Next steps:** -- Review generated specification -- Create sketch showing unique elements -- Run Page Process Workshop to refine - -Ready? - - +Load and execute the selected flow substep --- @@ -503,14 +67,7 @@ Ready? **Page:** {{page_name}} **Method:** {{visualization_method_description}} -**Status:** -{{#if has_visualization}} -- ✅ Conceptual specification complete -- ⏳ Visualization pending -{{else}} -- ✅ Conceptual specification complete -- ✅ Visualization method defined -{{/if}} +**Status:** Conceptual specification complete **The page is the place where visualization meets specification.** @@ -571,8 +128,7 @@ Next workshops use: --- -**Created:** December 28, 2025 -**Purpose:** Define page concept, choose visualization method -**Philosophy:** Page first, visualization second +**Created:** December 28, 2025 +**Purpose:** Define page concept, choose visualization method +**Philosophy:** Page first, visualization second **Status:** Ready for use - diff --git a/src/workflows/4-ux-design/steps/step-02-substeps/page-init/workshop-page-process.md b/src/workflows/4-ux-design/steps/step-02-substeps/page-init/workshop-page-process.md index 617fc56a8..f70401b40 100644 --- a/src/workflows/4-ux-design/steps/step-02-substeps/page-init/workshop-page-process.md +++ b/src/workflows/4-ux-design/steps/step-02-substeps/page-init/workshop-page-process.md @@ -10,7 +10,7 @@ **Intelligence:** Detects if this is a new page or update to existing specification. -**Behavior:** +**Behavior:** - New page → Full analysis - Updated page → Change detection, incremental update - Partial completion → Specify ready sections, mark TBD @@ -30,17 +30,17 @@ **This is the first sketch for this page!** - + Let me analyze what you've drawn and create the initial specification. - + Route to: `substeps/4b-sketch-analysis.md` (existing workflow) **I see we already have specifications for this page.** - + Let me compare this sketch to what we have... - + Proceed to STEP 2: Change Detection @@ -60,56 +60,19 @@ - Removed sections - TBD sections now complete - Complete sections now TBD - 4. Calculate confidence for each comparison **Comparison Results:** -{{#if has_changes}} -🔍 **Changes detected:** - -{{#if unchanged_sections.length > 0}} -✅ **Unchanged sections** ({{unchanged_sections.length}}): -{{#each section in unchanged_sections}} -- {{section.name}} -{{/each}} -{{/if}} - -{{#if modified_sections.length > 0}} -✏️ **Modified sections** ({{modified_sections.length}}): -{{#each section in modified_sections}} -- {{section.name}}: {{section.change_description}} -{{/each}} -{{/if}} - -{{#if new_sections.length > 0}} -➕ **New sections added** ({{new_sections.length}}): -{{#each section in new_sections}} -- {{section.name}}: {{section.description}} -{{/each}} -{{/if}} - -{{#if completed_sections.length > 0}} -✨ **TBD sections now complete** ({{completed_sections.length}}): -{{#each section in completed_sections}} -- {{section.name}}: Ready to specify -{{/each}} -{{/if}} - -{{#if removed_sections.length > 0}} -⚠️ **Sections removed** ({{removed_sections.length}}): -{{#each section in removed_sections}} -- {{section.name}} -{{/each}} -{{/if}} - -{{else}} -✅ **No changes detected** - -This sketch appears identical to the existing specification. Are you sure you wanted to upload a new version? -{{/if}} +**See:** [substeps/page-process-templates.md](substeps/page-process-templates.md) for output templates +Display: +- Unchanged sections (✅) +- Modified sections (✏️) +- New sections added (➕) +- TBD sections now complete (✨) +- Sections removed (⚠️) --- @@ -120,16 +83,10 @@ This sketch appears identical to the existing specification. Are you sure you wa **How would you like to proceed?** -{{#if modified_sections.length > 0 or new_sections.length > 0 or completed_sections.length > 0}} [A] Update all changed/new/completed sections [B] Pick specific sections to update [C] Show me detailed comparison first [D] Actually, this is the same - cancel -{{else if removed_sections.length > 0}} -[A] Remove deleted sections from spec -[B] Keep them marked as "removed from design" -[C] Cancel - I'll fix the sketch -{{/if}} Choice: @@ -145,24 +102,7 @@ Choice: **Updating all changed sections:** -I'll process: -{{#if modified_sections.length > 0}} -- {{modified_sections.length}} modified sections -{{/if}} -{{#if new_sections.length > 0}} -- {{new_sections.length}} new sections -{{/if}} -{{#if completed_sections.length > 0}} -- {{completed_sections.length}} completed sections -{{/if}} -{{#if removed_sections.length > 0}} -- {{removed_sections.length}} removed sections -{{/if}} - -**Preserving:** -{{#each section in unchanged_sections}} -- {{section.name}} -{{/each}} +I'll process all modified, new, and completed sections while preserving unchanged sections. Ready to analyze sections? @@ -184,9 +124,7 @@ End **Which sections should I update?** -{{#each section in (modified_sections + new_sections + completed_sections)}} -[{{@index + 1}}] {{section.name}} - {{section.change_type}} -{{/each}} +[List numbered sections with change type] Enter numbers separated by commas (e.g., 1,3,5): @@ -208,27 +146,13 @@ End **Detailed Section-by-Section Comparison:** -{{#each section in modified_sections}} +**See:** [substeps/page-process-templates.md](substeps/page-process-templates.md) for comparison template ---- - -### {{section.name}} - -**Current specification:** -{{section.current_spec_summary}} - -**New sketch shows:** -{{section.new_sketch_summary}} - -**Detected changes:** -{{#each change in section.changes}} -- {{change.description}} -{{/each}} - -**Confidence:** {{section.confidence}}% - ---- -{{/each}} +Display for each modified section: +- Current specification summary +- New sketch interpretation +- Detected changes +- Confidence level After reviewing, what would you like to do? @@ -247,28 +171,14 @@ After reviewing, what would you like to do? ✅ **Page specification updated!** **Summary:** -{{#if updated_count > 0}} -- {{updated_count}} sections updated -{{/if}} -{{#if added_count > 0}} -- {{added_count}} sections added -{{/if}} -{{#if preserved_count > 0}} -- {{preserved_count}} sections preserved (unchanged) -{{/if}} -{{#if removed_count > 0}} -- {{removed_count}} sections removed -{{/if}} +- [X] sections updated +- [X] sections added +- [X] sections preserved (unchanged) +- [X] sections removed **Updated file:** `{{page_spec_path}}` - **Sketch saved to:** `{{sketch_path}}` -**Next steps:** -- Review the updated specification -- Generate updated prototype (if needed) -- Continue to next page or scenario - Would you like to: [A] Generate HTML prototype [B] Add another page @@ -303,11 +213,6 @@ Based on user choice: - Preserves existing work - No data loss -### ✅ **Change Confidence** -- Shows confidence level per change -- Lets user verify before processing -- Reduces errors - ### ✅ **Flexible Control** - Update all or select specific - See detailed comparison @@ -315,7 +220,7 @@ Based on user choice: --- -## INTEGRATION WITH EXISTING SYSTEM +## INTEGRATION This workshop uses: - **4b-sketch-analysis.md** - For actual section analysis @@ -323,11 +228,8 @@ This workshop uses: - **page-specification.template.md** - For document structure - **object-types/*.md** - For component specifications -**It's a smart router that preserves your existing workflows!** - --- -**Created:** December 28, 2025 -**For:** Iterative page specification workflow +**Created:** December 28, 2025 +**For:** Iterative page specification workflow **Status:** Ready to test with WDS Presentation page - diff --git a/src/workflows/6-design-deliveries/steps/step-6.4-handoff-dialog.md b/src/workflows/6-design-deliveries/steps/step-6.4-handoff-dialog.md index 13f239447..a3ef3d8bb 100644 --- a/src/workflows/6-design-deliveries/steps/step-6.4-handoff-dialog.md +++ b/src/workflows/6-design-deliveries/steps/step-6.4-handoff-dialog.md @@ -24,370 +24,35 @@ Initiate a structured handoff conversation with the BMad Architect to transfer d **Duration:** 20-30 minutes **Participants:** - - WDS UX Expert (you) - BMad Architect --- -## Handoff Dialog Structure - -### Phase 1: Introduction (2 min) - -**You say:** - -``` -"Hey Architect! I've completed the design for [Flow Name]. - I'd like to walk you through Design Delivery DD-XXX. - - This delivery includes: - - [Number] scenarios - - [Number] components - - Complete test scenarios - - Ready for the walkthrough?" -``` - -**Architect responds:** - -``` -"Absolutely! Let's go through it." -``` - ---- - -### Phase 2: User Value (3 min) - -**Explain the user value:** - -``` -"First, let me explain what problem we're solving: - -Problem: -[Describe the user problem] - -Solution: -[Describe how this flow solves it] - -Success Criteria: -- [Metric 1] -- [Metric 2] -- [Metric 3] - -This is critical because [business value]." -``` - -**Questions to answer:** - -- Why does this flow matter? -- What business value does it deliver? -- How will we measure success? - ---- - -### Phase 3: Scenario Walkthrough (8 min) - -**Walk through each scenario:** - -``` -"Let me walk you through the user flow: - -Scenario 1: [Name] -- User starts at: [Entry point] -- User action: [What they do] -- System response: [What happens] -- User sees: [What's displayed] -- Design reference: C-Scenarios/XX-name/ - -[Repeat for each scenario] - -The complete flow is: -[Entry point] → [Step 1] → [Step 2] → [Exit point]" -``` - -**Show:** - -- Excalidraw sketches (if available) -- Scenario specifications -- User flow diagrams - -**Architect may ask:** - -- "What happens if [edge case]?" -- "How does this integrate with [existing feature]?" -- "What's the data flow here?" - -**Answer clearly and reference specifications!** - ---- - -### Phase 4: Technical Requirements (4 min) - -**Review technical requirements:** - -``` -"Technical requirements: - -Platform: -- Frontend: [Framework + version] -- Backend: [Framework + version] -- Database: [Database + version] - -Integrations: -- [Integration 1]: [Purpose] -- [Integration 2]: [Purpose] - -Data Models: -- [Model 1]: [Fields] -- [Model 2]: [Fields] - -Performance: -- [Requirement 1] -- [Requirement 2] - -Security: -- [Requirement 1] -- [Requirement 2]" -``` - -**Architect may ask:** - -- "Why this tech stack?" -- "Are there any constraints?" -- "What about [technical concern]?" - -**Answer:** Reference `platform-requirements.yaml` if needed! - ---- - -### Phase 5: Design System Components (3 min) - -**Review components:** - -``` -"Design system components used: - -Button: -- Primary variant: [Usage] -- Secondary variant: [Usage] -- Specs: D-Design-System/.../Buttons/ - -Input: -- Text variant: [Usage] -- Email variant: [Usage] -- Password variant: [Usage] -- Specs: D-Design-System/.../Inputs/ - -[List all components] - -All components follow our design tokens: -- Colors: tokens/colors.json -- Typography: tokens/typography.json -- Spacing: tokens/spacing.json" -``` - -**Architect may ask:** - -- "Do these components already exist?" -- "Any new components needed?" -- "What about [specific state]?" - -**Answer:** Reference component specifications! - ---- - -### Phase 6: Acceptance Criteria (3 min) - -**Review acceptance criteria:** - -``` -"Acceptance criteria: - -Functional: -- [Criterion 1] -- [Criterion 2] -- [Criterion 3] - -Non-Functional: -- [Criterion 1] -- [Criterion 2] - -Edge Cases: -- [Case 1] -- [Case 2] - -All criteria are testable and defined in TS-XXX.yaml" -``` - ---- - -### Phase 7: Testing Approach (2 min) - -**Explain testing:** - -``` -"Testing approach: - -I've created test scenario TS-XXX which includes: -- Happy path tests ([number] tests) -- Error state tests ([number] tests) -- Edge case tests ([number] tests) -- Design system validation -- Accessibility tests - -When you're done implementing, I'll: -1. Run these test scenarios -2. Create issues if problems found -3. Iterate with you until approved -4. Sign off when quality meets standards" -``` - ---- - -### Phase 8: Complexity Estimate (2 min) - -**Discuss complexity:** - -``` -"My complexity estimate: - -Size: [Small/Medium/Large] -Effort: [Time estimate] -Risk: [Low/Medium/High] - -Dependencies: -- [Dependency 1] -- [Dependency 2] - -Assumptions: -- [Assumption 1] -- [Assumption 2] - -Does this align with your technical assessment?" -``` - -**Architect responds with their estimate:** - -``` -"I'll break this into [number] epics: -- Epic 1: [Name] ([time]) -- Epic 2: [Name] ([time]) -- Epic 3: [Name] ([time]) - -Total: [time estimate]" -``` - -**Discuss any discrepancies!** - ---- - -### Phase 9: Special Considerations (2 min) - -**Highlight anything special:** - -``` -"Special considerations: - -- [Important note 1] -- [Important note 2] -- [Potential gotcha] -- [Critical requirement] - -Questions or concerns?" -``` - -**Architect may raise:** - -- Technical challenges -- Integration concerns -- Timeline issues -- Resource needs - -**Discuss and resolve!** - ---- - -### Phase 10: Confirmation & Next Steps (1 min) - -**Confirm handoff:** - -``` -You: "So to confirm: -- You have DD-XXX.yaml (Design Delivery) -- You have TS-XXX.yaml (Test Scenario) -- You have all scenario specs in C-Scenarios/ -- You have all component specs in D-Design-System/ -- You'll break this into [number] epics -- Estimated [time] to implement -- You'll notify me when ready for validation - -Anything else you need?" - -Architect: "All set! I'll start architecture design and - break this down into epics. I'll notify you - when implementation is complete and ready - for your validation." - -You: "Perfect! I'll start designing the next flow while - you build this one. Thanks!" -``` +## Handoff Dialog Structure (10 Phases) + +**See:** [substeps/handoff-dialog-scripts.md](substeps/handoff-dialog-scripts.md) for detailed conversation scripts + +| Phase | Duration | Focus | +|-------|----------|-------| +| 1. Introduction | 2 min | Greet, state delivery ID, overview | +| 2. User Value | 3 min | Problem, solution, success criteria | +| 3. Scenario Walkthrough | 8 min | User flow, screens, specifications | +| 4. Technical Requirements | 4 min | Platform, integrations, data models | +| 5. Design System Components | 3 min | Components used, design tokens | +| 6. Acceptance Criteria | 3 min | Functional, non-functional, edge cases | +| 7. Testing Approach | 2 min | Test scenarios, validation process | +| 8. Complexity Estimate | 2 min | Size, effort, risk, dependencies | +| 9. Special Considerations | 2 min | Important notes, potential gotchas | +| 10. Confirmation | 1 min | Confirm understanding, next steps | --- ## Document the Handoff -**Create handoff log:** `deliveries/DD-XXX-handoff-log.md` +After the dialog, create handoff log using template in substeps file. -```markdown -# Handoff Log: DD-XXX - -**Date:** 2024-12-09 -**Duration:** 25 minutes -**Participants:** - -- WDS UX Expert: [Your name] -- BMad Architect: Winston - -## Key Points Discussed - -- User value and success criteria -- Complete scenario walkthrough -- Technical requirements confirmed -- Design system components reviewed -- Acceptance criteria agreed -- Testing approach explained -- Complexity estimate aligned - -## Epic Breakdown Agreed - -1. Epic 1: Authentication & Session Management (1 week) -2. Epic 2: Onboarding UI & Flow (1 week) -3. Epic 3: Family Setup & Data Models (0.5 week) -4. Epic 4: Error Handling & Edge Cases (0.5 week) - -**Total:** 3 weeks - -## Questions & Answers - -Q: "How do we handle session persistence?" -A: "Use Supabase Auth SDK, 30-day expiration" - -Q: "What if user closes app mid-onboarding?" -A: "Save progress, resume at last incomplete step" - -## Action Items - -- [ ] Architect: Create architecture document -- [ ] Architect: Break down into dev stories -- [ ] Architect: Notify designer when ready for validation -- [ ] Designer: Start designing next flow (DD-002) - -## Status - -**Handoff:** Complete ✅ -**Delivery Status:** in_development -**Next Touch Point:** Designer validation (Phase 7) -``` +**File:** `deliveries/DD-XXX-handoff-log.md` --- diff --git a/src/workflows/6-design-deliveries/steps/step-6.5-hand-off.md b/src/workflows/6-design-deliveries/steps/step-6.5-hand-off.md index 9925240a8..b5aa777c4 100644 --- a/src/workflows/6-design-deliveries/steps/step-6.5-hand-off.md +++ b/src/workflows/6-design-deliveries/steps/step-6.5-hand-off.md @@ -21,32 +21,27 @@ Officially hand off the Design Delivery to BMad and confirm they have everything ### Verify BMad Has All Artifacts **Design Delivery:** - - [ ] File exists: `deliveries/DD-XXX-name.yaml` - [ ] Status: "in_development" - [ ] Handed off timestamp recorded - [ ] Assigned to BMad Architect **Test Scenario:** - - [ ] File exists: `test-scenarios/TS-XXX-name.yaml` - [ ] All tests defined - [ ] Sign-off criteria clear **Scenario Specifications:** - - [ ] All scenarios in `C-Scenarios/` are complete - [ ] All specifications are up-to-date - [ ] All design references are valid **Design System:** - - [ ] All components in `D-Design-System/` are defined - [ ] Design tokens are documented - [ ] Component specifications are complete **Handoff Log:** - - [ ] File exists: `deliveries/DD-XXX-handoff-log.md` - [ ] All key points documented - [ ] Epic breakdown recorded @@ -56,109 +51,15 @@ Officially hand off the Design Delivery to BMad and confirm they have everything ## Notify BMad -**Send official handoff notification:** +**Send official handoff notification using template:** -``` -WDS UX Expert → BMad Architect - -Subject: Design Delivery DD-XXX Ready for Implementation - -Hi Architect! - -Design Delivery DD-XXX ([Flow Name]) is officially handed off -and ready for implementation. - -📦 Artifacts: -- Design Delivery: deliveries/DD-XXX-name.yaml -- Test Scenario: test-scenarios/TS-XXX-name.yaml -- Scenarios: C-Scenarios/ ([number] scenarios) -- Components: D-Design-System/ ([number] components) -- Handoff Log: deliveries/DD-XXX-handoff-log.md - -✅ What we agreed: -- Epic breakdown: [number] epics -- Estimated effort: [time] -- Implementation approach: [summary] - -📋 Next steps: -1. You: Create architecture document -2. You: Break down into dev stories -3. You: Implement features -4. You: Notify me when ready for validation (Touch Point 3) - -🔗 Touch Point 3: -When implementation is complete, notify me and I'll run the -test scenarios to validate. We'll iterate until approved. - -Questions? I'm available! - -Thanks, -[Your name] -WDS UX Expert -``` - ---- - -## BMad Acknowledges - -**BMad Architect responds:** - -``` -BMad Architect → WDS UX Expert - -Subject: Re: Design Delivery DD-XXX Ready for Implementation - -Received! Starting work on DD-XXX. - -📋 My plan: -1. Create architecture document (this week) -2. Break down into [number] dev stories -3. Implement over [time period] -4. Notify you when ready for validation - -📦 Confirmed I have: -✅ Design Delivery (DD-XXX.yaml) -✅ Test Scenario (TS-XXX.yaml) -✅ All scenario specs -✅ All component specs -✅ Handoff log - -I'll keep you updated on progress. Thanks for the thorough -handoff! - -Winston -BMad Architect -``` +**See:** [substeps/delivery-templates.md](substeps/delivery-templates.md) for notification template --- ## Update Project Status -**Update project tracking (if you have one):** - -```markdown -# Project Status - -## In Progress - -### DD-XXX: [Flow Name] - -- Status: In Development -- Assigned: BMad Architect -- Started: 2024-12-09 -- Estimated completion: 2024-12-30 -- Epics: [number] -- Designer: Available for questions - -## Next Up - -### DD-XXX+1: [Next Flow Name] - -- Status: In Design -- Phase: 4-5 (UX Design & Design System) -- Designer: Working on scenarios -- Estimated handoff: 2024-12-16 -``` +**Update project tracking using status tracker template in substeps.** --- @@ -166,87 +67,29 @@ BMad Architect **Track progress:** -**Weekly check-ins:** +- Schedule weekly check-ins with BMad Architect +- Set up communication channel (#dd-xxx-implementation) +- Configure milestone notifications -- Schedule brief sync with BMad Architect -- Review progress -- Answer questions -- Unblock issues - -**Communication channel:** - -- Slack/Teams channel: #dd-xxx-implementation -- Quick questions welcome -- Async updates appreciated - -**Milestone notifications:** - -- Epic 1 complete → Notify designer -- Epic 2 complete → Notify designer -- All epics complete → Ready for validation (Touch Point 3) - ---- - -## Designer Availability - -**Make yourself available:** - -``` -"I'm available for questions while you implement: - -Quick questions: -- Slack/Teams: @designer -- Response time: < 2 hours - -Design clarifications: -- Schedule 15-min call -- Review specifications together -- Update specs if needed - -Blockers: -- Immediate response -- Unblock ASAP -- Adjust design if necessary - -I want this to succeed!" -``` +**Designer availability:** +- Quick questions: < 2 hours response +- Design clarifications: Schedule 15-min call +- Blockers: Immediate response --- ## What Happens Next -### BMad's Work (Phases 3-4) - -**Phase 3: Architecture** - +### BMad's Work - Create architecture document -- Define technical approach -- Identify dependencies -- Plan implementation - -**Phase 4: Implementation** - - Break down into dev stories - Implement features -- Write tests -- Build the flow - -**Timeline:** [Agreed time estimate] - ---- +- Notify you when ready for validation ### Your Work (Phase 6.6) - **While BMad builds this flow, you design the next one!** -**Return to Phase 4-5:** - -- Design next complete testable flow -- Create specifications -- Define components -- Prepare for next handoff - -**Parallel work = faster delivery!** +Return to Phase 4-5 for parallel work. --- @@ -283,45 +126,4 @@ After confirming handoff: --- -## Communication Tips - -### DO ✅ - -**Be available:** - -- Answer questions promptly -- Unblock issues quickly -- Provide clarifications - -**Be collaborative:** - -- "How can I help?" -- "Let's figure this out together" -- "I'm here if you need me" - -**Be flexible:** - -- Adjust design if technical constraints arise -- Find creative solutions -- Focus on user value, not ego - -### DON'T ❌ - -**Don't disappear:** - -- "I handed it off, not my problem anymore" ❌ -- Stay engaged throughout implementation - -**Don't be rigid:** - -- "It must be exactly like this" ❌ -- Be open to technical suggestions - -**Don't ignore questions:** - -- Respond within 24 hours -- If you don't know, say so and find out - ---- - **Remember:** Handoff is not the end - it's the beginning of collaboration! Stay engaged! diff --git a/src/workflows/6-design-deliveries/steps/step-6.6-continue.md b/src/workflows/6-design-deliveries/steps/step-6.6-continue.md index cfe8552bc..37c56e721 100644 --- a/src/workflows/6-design-deliveries/steps/step-6.6-continue.md +++ b/src/workflows/6-design-deliveries/steps/step-6.6-continue.md @@ -8,21 +8,9 @@ While BMad builds the current flow, start designing the next complete testable f ## Parallel Work Strategy -**The key to fast delivery:** +**See:** [substeps/delivery-templates.md](substeps/delivery-templates.md) for parallel work schedule and iteration cadence -``` -Week 1: Design Flow 1 -Week 2: Handoff Flow 1 → BMad builds Flow 1 - Design Flow 2 -Week 3: Handoff Flow 2 → BMad builds Flow 2 - Test Flow 1 (Phase 7) - Design Flow 3 -Week 4: Handoff Flow 3 → BMad builds Flow 3 - Test Flow 2 (Phase 7) - Design Flow 4 -``` - -**You're never waiting! Always working!** +**The key to fast delivery:** You're never waiting! Always working! --- @@ -30,8 +18,6 @@ Week 4: Handoff Flow 3 → BMad builds Flow 3 ### Identify Next Flow -**What's the next most valuable flow to design?** - **Prioritization criteria:** 1. **User value:** What solves the biggest user problem? @@ -39,277 +25,65 @@ Week 4: Handoff Flow 3 → BMad builds Flow 3 3. **Dependencies:** What needs to be built next? 4. **Risk:** What's the riskiest to validate early? -**Example prioritization:** - -``` -✅ Flow 1: Login & Onboarding (DONE - in development) -→ Flow 2: Morning Dog Care (NEXT - highest user value) - Flow 3: Calendar View (Later - lower priority) - Flow 4: Family Chat (Later - nice to have) -``` - ---- - ### Phase 4: UX Design -**Design scenarios for the next flow:** - -1. **Identify trigger moment** - - What brings user to this flow? - - What are they trying to accomplish? - -2. **Design scenarios** - - Entry point - - User actions - - System responses - - Exit point - -3. **Create specifications** - - `C-Scenarios/XX-scenario-name/` - - Frontend specifications - - Backend specifications - - Data specifications - -4. **Document user flows** - - Happy path - - Error states - - Edge cases - -**Goal:** Complete testable flow that delivers value - ---- +Design scenarios for the next flow: +1. Identify trigger moment +2. Design scenarios (entry, actions, responses, exit) +3. Create specifications in `C-Scenarios/XX-scenario-name/` +4. Document user flows (happy path, errors, edge cases) ### Phase 5: Design System -**Define components for this flow:** - -1. **Identify needed components** - - What UI elements are needed? - - Can we reuse existing components? - - What new components are needed? - -2. **Define new components** - - `D-Design-System/03-Atomic-Components/` - - Component specifications - - States and variants - - Usage guidelines - -3. **Update design tokens** - - Colors - - Typography - - Spacing - - Any new tokens needed - -**Goal:** All components defined and ready +Define components for this flow: +1. Identify needed components (reuse vs new) +2. Define new components in `D-Design-System/03-Atomic-Components/` +3. Update design tokens if needed --- ## When to Return to Phase 6 -**Return to Phase 6 when:** +**Return when:** - ✅ All scenarios for next flow are specified - ✅ All components for next flow are defined - ✅ Flow is testable end-to-end -- ✅ Flow delivers business value -- ✅ Flow delivers user value +- ✅ Flow delivers business and user value - ✅ No blockers or dependencies -**Then repeat Phase 6:** - -- 6.1: Detect completion -- 6.2: Create Design Delivery -- 6.3: Create Test Scenario -- 6.4: Handoff Dialog -- 6.5: Hand Off to BMad -- 6.6: Continue (you are here!) +**Then repeat Phase 6 cycle (6.1 → 6.6)** --- ## Managing Multiple Flows -### Track Your Work +**Track your work using tracker template in substeps.** -**Create a simple tracker:** - -```markdown -# Design Deliveries Tracker - -## DD-001: Login & Onboarding - -- Status: In Development (BMad) -- Handed off: 2024-12-09 -- Expected completion: 2024-12-30 -- Next: Validation (Phase 7) - -## DD-002: Morning Dog Care - -- Status: In Design (WDS) -- Phase: 4 (UX Design) -- Progress: 3/5 scenarios complete -- Expected handoff: 2024-12-16 - -## DD-003: Calendar View - -- Status: Not Started -- Priority: Medium -- Planned start: 2024-12-20 - -## DD-004: Family Chat - -- Status: Not Started -- Priority: Low -- Planned start: TBD -``` - ---- - -### Communication with BMad - -**Keep BMad informed:** - -``` -Weekly Update to BMad Architect: - -"Hey Architect! - -Progress update: - -DD-001 (Login & Onboarding): -- You're building this -- I'm available for questions -- On track for validation 2024-12-30? - -DD-002 (Morning Dog Care): -- I'm designing this now -- 3/5 scenarios complete -- Expected handoff: 2024-12-16 -- 2 weeks after DD-001 handoff - -DD-003 (Calendar View): -- Next in queue -- Will start after DD-002 handoff - -Questions or blockers on DD-001?" -``` +**Communication:** Keep BMad informed with weekly updates (template in substeps). --- ## Balancing Design and Validation -**As flows complete, you'll be doing both:** +As flows complete, you'll be doing both: -### Week 3 Example - -**Monday-Tuesday:** - -- Test DD-001 (Phase 7) -- Create issues if needed - -**Wednesday-Friday:** - -- Design DD-003 scenarios -- Define DD-003 components +- **Early week:** Test completed flows (Phase 7) +- **Late week:** Design new scenarios **This is the steady state!** --- -## Continuous Improvement - -**Learn from each cycle:** - -### After Each Handoff - -**Reflect:** - -- What went well? -- What was unclear? -- What questions did BMad ask? -- How can I improve next delivery? - -**Update templates:** - -- Add missing fields -- Clarify confusing sections -- Improve examples - -**Update process:** - -- Streamline handoff dialog -- Better test scenarios -- Clearer specifications - ---- - -## Iteration Cadence - -**Typical cadence:** - -``` -Week 1-2: Design DD-001 -Week 2: Handoff DD-001 -Week 2-4: BMad builds DD-001 -Week 3-4: Design DD-002 -Week 4: Handoff DD-002 -Week 4-6: BMad builds DD-002 -Week 5: Test DD-001 (Phase 7) -Week 5-6: Design DD-003 -Week 6: Handoff DD-003 -Week 6-8: BMad builds DD-003 -Week 7: Test DD-002 (Phase 7) -Week 7-8: Design DD-004 -``` - -**Continuous flow!** - ---- - ## When to Pause -**You might pause designing if:** +**Pause designing if:** -### BMad is Blocked +- BMad is blocked and needs design clarification +- Too many flows in progress (overwhelming the team) +- Validation backlog building up -``` -BMad: "I'm blocked on DD-001. Need design clarification." - -You: "Let me help! Pausing DD-002 design to unblock you." -``` - -**Priority: Unblock BMad first!** - ---- - -### Too Many Flows in Progress - -``` -In Progress: -- DD-001: In development -- DD-002: In development -- DD-003: In development -- DD-004: Ready for handoff - -You: "Let me pause and let BMad catch up. I'll focus on - validation instead of new design." -``` - -**Don't overwhelm the team!** - ---- - -### Validation Backlog - -``` -Waiting for Validation: -- DD-001: Complete, needs testing -- DD-002: Complete, needs testing -- DD-003: Complete, needs testing - -You: "Pause new design. Focus on validation backlog." -``` - -**Validation is critical!** +**Priority:** Unblock BMad and clear validation backlog first! --- @@ -335,24 +109,6 @@ You: "Pause new design. Focus on validation backlog." --- -## The Rhythm - -**Once you find your rhythm:** - -``` -Design → Handoff → Build → Test → Ship - ↓ -Design → Handoff → Build → Test → Ship - ↓ -Design → Handoff → Build → Test → Ship - ↓ -(Repeat until product is complete) -``` - -**This is the WDS ↔ BMad workflow in action!** - ---- - ## Completion **Phase 6 is complete when:** @@ -367,48 +123,14 @@ Design → Handoff → Build → Test → Ship ## Next Steps -**You have three paths:** - -### Path 1: Continue Designing (Most Common) - -``` -[D] Return to Phase 4-5 to design next flow -``` - ---- - -### Path 2: Validation Needed +**Three paths:** ``` +[D] Return to Phase 4-5 to design next flow (Most Common) [V] Go to Phase 7 if a flow is ready for validation +[C] All flows designed and handed off! Wait for validations. ``` --- -### Path 3: All Flows Complete - -``` -[C] All flows designed and handed off! - Wait for validations, then ship! 🚀 -``` - ---- - -## The Big Picture - -**You've completed the Phase 6 cycle!** - -``` -Phase 6.1: Detect Completion ✅ -Phase 6.2: Create Delivery ✅ -Phase 6.3: Create Test Scenario ✅ -Phase 6.4: Handoff Dialog ✅ -Phase 6.5: Hand Off to BMad ✅ -Phase 6.6: Continue ✅ (you are here!) - -→ Return to Phase 4-5 and repeat! -``` - ---- - -**Keep the momentum going! Design → Handoff → Build → Test → Ship!** 🚀✨ +**Keep the momentum going! Design → Handoff → Build → Test → Ship!** 🚀 diff --git a/src/workflows/6-design-deliveries/steps/substeps/delivery-templates.md b/src/workflows/6-design-deliveries/steps/substeps/delivery-templates.md new file mode 100644 index 000000000..ee034e61b --- /dev/null +++ b/src/workflows/6-design-deliveries/steps/substeps/delivery-templates.md @@ -0,0 +1,188 @@ +# Design Delivery Templates + +Templates for handoff communication and tracking. + +--- + +## Handoff Notification Template + +``` +WDS UX Expert → BMad Architect + +Subject: Design Delivery DD-XXX Ready for Implementation + +Hi Architect! + +Design Delivery DD-XXX ([Flow Name]) is officially handed off +and ready for implementation. + +📦 Artifacts: +- Design Delivery: deliveries/DD-XXX-name.yaml +- Test Scenario: test-scenarios/TS-XXX-name.yaml +- Scenarios: C-Scenarios/ ([number] scenarios) +- Components: D-Design-System/ ([number] components) +- Handoff Log: deliveries/DD-XXX-handoff-log.md + +✅ What we agreed: +- Epic breakdown: [number] epics +- Estimated effort: [time] +- Implementation approach: [summary] + +📋 Next steps: +1. You: Create architecture document +2. You: Break down into dev stories +3. You: Implement features +4. You: Notify me when ready for validation (Touch Point 3) + +🔗 Touch Point 3: +When implementation is complete, notify me and I'll run the +test scenarios to validate. We'll iterate until approved. + +Questions? I'm available! + +Thanks, +[Your name] +WDS UX Expert +``` + +--- + +## Project Status Tracker Template + +```markdown +# Project Status + +## In Progress + +### DD-XXX: [Flow Name] + +- Status: In Development +- Assigned: BMad Architect +- Started: [Date] +- Estimated completion: [Date] +- Epics: [number] +- Designer: Available for questions + +## Next Up + +### DD-XXX+1: [Next Flow Name] + +- Status: In Design +- Phase: 4-5 (UX Design & Design System) +- Designer: Working on scenarios +- Estimated handoff: [Date] +``` + +--- + +## Design Deliveries Tracker Template + +```markdown +# Design Deliveries Tracker + +## DD-001: [Flow Name] + +- Status: In Development (BMad) +- Handed off: [Date] +- Expected completion: [Date] +- Next: Validation (Phase 7) + +## DD-002: [Flow Name] + +- Status: In Design (WDS) +- Phase: 4 (UX Design) +- Progress: X/Y scenarios complete +- Expected handoff: [Date] + +## DD-003: [Flow Name] + +- Status: Not Started +- Priority: [High/Medium/Low] +- Planned start: [Date] +``` + +--- + +## Weekly Update Template + +``` +Weekly Update to BMad Architect: + +"Hey Architect! + +Progress update: + +DD-001 ([Flow Name]): +- You're building this +- I'm available for questions +- On track for validation [Date]? + +DD-002 ([Flow Name]): +- I'm designing this now +- X/Y scenarios complete +- Expected handoff: [Date] + +DD-003 ([Flow Name]): +- Next in queue +- Will start after DD-002 handoff + +Questions or blockers on DD-001?" +``` + +--- + +## Parallel Work Strategy + +``` +Week 1: Design Flow 1 +Week 2: Handoff Flow 1 → BMad builds Flow 1 + Design Flow 2 +Week 3: Handoff Flow 2 → BMad builds Flow 2 + Test Flow 1 (Phase 7) + Design Flow 3 +Week 4: Handoff Flow 3 → BMad builds Flow 3 + Test Flow 2 (Phase 7) + Design Flow 4 +``` + +**You're never waiting! Always working!** + +--- + +## Iteration Cadence + +``` +Week 1-2: Design DD-001 +Week 2: Handoff DD-001 +Week 2-4: BMad builds DD-001 +Week 3-4: Design DD-002 +Week 4: Handoff DD-002 +Week 4-6: BMad builds DD-002 +Week 5: Test DD-001 (Phase 7) +Week 5-6: Design DD-003 +Week 6: Handoff DD-003 +Week 6-8: BMad builds DD-003 +Week 7: Test DD-002 (Phase 7) +Week 7-8: Design DD-004 +``` + +**Continuous flow!** + +--- + +## Communication Tips + +### DO ✅ + +- Answer questions promptly +- Unblock issues quickly +- Provide clarifications +- "How can I help?" +- "Let's figure this out together" +- Be flexible - adjust design if technical constraints arise + +### DON'T ❌ + +- Don't disappear after handoff +- Don't be rigid - be open to technical suggestions +- Don't ignore questions - respond within 24 hours diff --git a/src/workflows/6-design-deliveries/steps/substeps/handoff-dialog-scripts.md b/src/workflows/6-design-deliveries/steps/substeps/handoff-dialog-scripts.md new file mode 100644 index 000000000..6965e02be --- /dev/null +++ b/src/workflows/6-design-deliveries/steps/substeps/handoff-dialog-scripts.md @@ -0,0 +1,276 @@ +# Handoff Dialog Scripts + +Detailed conversation scripts for each phase of the handoff dialog. + +--- + +## Phase 1: Introduction (2 min) + +**You say:** +``` +"Hey Architect! I've completed the design for [Flow Name]. + I'd like to walk you through Design Delivery DD-XXX. + + This delivery includes: + - [Number] scenarios + - [Number] components + - Complete test scenarios + + Ready for the walkthrough?" +``` + +--- + +## Phase 2: User Value (3 min) + +**You say:** +``` +"First, let me explain what problem we're solving: + +Problem: +[Describe the user problem] + +Solution: +[Describe how this flow solves it] + +Success Criteria: +- [Metric 1] +- [Metric 2] +- [Metric 3] + +This is critical because [business value]." +``` + +--- + +## Phase 3: Scenario Walkthrough (8 min) + +**You say:** +``` +"Let me walk you through the user flow: + +Scenario 1: [Name] +- User starts at: [Entry point] +- User action: [What they do] +- System response: [What happens] +- User sees: [What's displayed] +- Design reference: C-Scenarios/XX-name/ + +[Repeat for each scenario] + +The complete flow is: +[Entry point] → [Step 1] → [Step 2] → [Exit point]" +``` + +**Show:** Excalidraw sketches, Scenario specifications, User flow diagrams + +--- + +## Phase 4: Technical Requirements (4 min) + +**You say:** +``` +"Technical requirements: + +Platform: +- Frontend: [Framework + version] +- Backend: [Framework + version] +- Database: [Database + version] + +Integrations: +- [Integration 1]: [Purpose] +- [Integration 2]: [Purpose] + +Data Models: +- [Model 1]: [Fields] +- [Model 2]: [Fields] + +Performance: +- [Requirement 1] +- [Requirement 2] + +Security: +- [Requirement 1] +- [Requirement 2]" +``` + +--- + +## Phase 5: Design System Components (3 min) + +**You say:** +``` +"Design system components used: + +Button: +- Primary variant: [Usage] +- Secondary variant: [Usage] +- Specs: D-Design-System/.../Buttons/ + +Input: +- Text variant: [Usage] +- Email variant: [Usage] +- Password variant: [Usage] +- Specs: D-Design-System/.../Inputs/ + +[List all components] + +All components follow our design tokens: +- Colors: tokens/colors.json +- Typography: tokens/typography.json +- Spacing: tokens/spacing.json" +``` + +--- + +## Phase 6: Acceptance Criteria (3 min) + +**You say:** +``` +"Acceptance criteria: + +Functional: +- [Criterion 1] +- [Criterion 2] +- [Criterion 3] + +Non-Functional: +- [Criterion 1] +- [Criterion 2] + +Edge Cases: +- [Case 1] +- [Case 2] + +All criteria are testable and defined in TS-XXX.yaml" +``` + +--- + +## Phase 7: Testing Approach (2 min) + +**You say:** +``` +"Testing approach: + +I've created test scenario TS-XXX which includes: +- Happy path tests ([number] tests) +- Error state tests ([number] tests) +- Edge case tests ([number] tests) +- Design system validation +- Accessibility tests + +When you're done implementing, I'll: +1. Run these test scenarios +2. Create issues if problems found +3. Iterate with you until approved +4. Sign off when quality meets standards" +``` + +--- + +## Phase 8: Complexity Estimate (2 min) + +**You say:** +``` +"My complexity estimate: + +Size: [Small/Medium/Large] +Effort: [Time estimate] +Risk: [Low/Medium/High] + +Dependencies: +- [Dependency 1] +- [Dependency 2] + +Assumptions: +- [Assumption 1] +- [Assumption 2] + +Does this align with your technical assessment?" +``` + +--- + +## Phase 9: Special Considerations (2 min) + +**You say:** +``` +"Special considerations: + +- [Important note 1] +- [Important note 2] +- [Potential gotcha] +- [Critical requirement] + +Questions or concerns?" +``` + +--- + +## Phase 10: Confirmation & Next Steps (1 min) + +**You say:** +``` +"So to confirm: +- You have DD-XXX.yaml (Design Delivery) +- You have TS-XXX.yaml (Test Scenario) +- You have all scenario specs in C-Scenarios/ +- You have all component specs in D-Design-System/ +- You'll break this into [number] epics +- Estimated [time] to implement +- You'll notify me when ready for validation + +Anything else you need?" +``` + +--- + +## Handoff Log Template + +File: `deliveries/DD-XXX-handoff-log.md` + +```markdown +# Handoff Log: DD-XXX + +**Date:** [Date] +**Duration:** [Duration] minutes +**Participants:** +- WDS UX Expert: [Your name] +- BMad Architect: [Architect name] + +## Key Points Discussed + +- User value and success criteria +- Complete scenario walkthrough +- Technical requirements confirmed +- Design system components reviewed +- Acceptance criteria agreed +- Testing approach explained +- Complexity estimate aligned + +## Epic Breakdown Agreed + +1. Epic 1: [Name] ([time]) +2. Epic 2: [Name] ([time]) + +**Total:** [time estimate] + +## Questions & Answers + +Q: "[Question]" +A: "[Answer]" + +## Action Items + +- [ ] Architect: Create architecture document +- [ ] Architect: Break down into dev stories +- [ ] Architect: Notify designer when ready for validation +- [ ] Designer: Start designing next flow + +## Status + +**Handoff:** Complete ✅ +**Delivery Status:** in_development +**Next Touch Point:** Designer validation (Phase 7) +``` diff --git a/src/workflows/7-testing/steps/step-7.3-run-tests.md b/src/workflows/7-testing/steps/step-7.3-run-tests.md index 4c1e8da58..be741ac37 100644 --- a/src/workflows/7-testing/steps/step-7.3-run-tests.md +++ b/src/workflows/7-testing/steps/step-7.3-run-tests.md @@ -27,622 +27,96 @@ Execute all test scenarios defined in the test scenario file and document result 4. **Design System Validation** 5. **Accessibility Tests** -**Why this order?** +**Why this order?** Happy path must work first. Errors and edge cases build on happy path. Design system and accessibility are final polish. -- Happy path must work first -- Errors and edge cases build on happy path -- Design system and accessibility are final polish +--- + +## Test Result Templates + +**See:** [substeps/test-result-templates.md](substeps/test-result-templates.md) for all documentation templates --- ## 1. Happy Path Tests -### For Each Happy Path Test +**For each test in TS-XXX.yaml `happy_path` section:** -**Load test from TS-XXX.yaml:** - -```yaml -happy_path: - - id: 'HP-001' - name: 'New User Complete Onboarding' - steps: - - action: 'Open app' - expected: 'Welcome screen appears' - design_ref: 'C-Scenarios/01-welcome/Frontend/specifications.md' -``` - ---- - -### Execute Test Steps - -**For each step:** - -1. **Start screen recording** (for full flow) - -2. **Perform the action** - - Follow exactly as written - - Use prepared test data - - Note any deviations - -3. **Observe the result** - - What actually happened? - - Does it match expected result? - - Any delays or glitches? - -4. **Compare to design reference** - - Open design specification - - Check every detail - - Note any differences - -5. **Mark as Pass or Fail** - - ``` - ✓ PASS: Matches expected result - ✗ FAIL: Doesn't match expected result - ``` - -6. **Take screenshot if FAIL** - - Capture the issue - - Annotate if needed - - Save with clear name: `HP-001-step-3-FAIL.png` - -7. **Document in notes** - - ```markdown - ## HP-001: New User Complete Onboarding - - ### Step 1: Open app - - - Action: Opened app - - Expected: Welcome screen appears - - Actual: Welcome screen appears ✓ - - Result: PASS - - ### Step 2: Tap "Get Started" - - - Action: Tapped "Get Started" button - - Expected: Login/Signup choice appears - - Actual: Login/Signup choice appears ✓ - - Result: PASS - - ### Step 3: Tap "Create Account" - - - Action: Tapped "Create Account" - - Expected: Signup form with smooth 300ms transition - - Actual: Signup form appears instantly (no transition) - - Result: FAIL ✗ - - Issue: Transition too fast, feels jarring - - Screenshot: HP-001-step-3-FAIL.png - ``` - ---- - -### Record Results - -**Create results summary:** - -```markdown -# Happy Path Test Results - -## HP-001: New User Complete Onboarding - -- Status: FAIL -- Steps: 9 total -- Passed: 8/9 (89%) -- Failed: 1/9 (11%) -- Issues: 1 (transition animation missing) -- Duration: 2 minutes 15 seconds -- Recording: happy-path-HP-001.mov - -## HP-002: Returning User Login - -- Status: PASS -- Steps: 5 total -- Passed: 5/5 (100%) -- Failed: 0/5 (0%) -- Issues: 0 -- Duration: 45 seconds -- Recording: happy-path-HP-002.mov - -## Summary - -- Total Tests: 2 -- Passed: 1/2 (50%) -- Failed: 1/2 (50%) -- Total Issues: 1 -``` +1. Start screen recording +2. Perform action exactly as written +3. Observe result, compare to expected +4. Compare to design reference +5. Mark PASS or FAIL +6. Take screenshot if FAIL (naming: `HP-XXX-step-X-FAIL.png`) +7. Document using template --- ## 2. Error State Tests -### For Each Error State Test +**For each test in TS-XXX.yaml `error_states` section:** -**Load test from TS-XXX.yaml:** - -```yaml -error_states: - - id: 'ES-001' - name: 'Email Already Exists' - steps: - - action: 'Enter existing email' - - action: "Tap 'Create Account'" - - expected: "Error message: 'This email is already registered...'" -``` - ---- - -### Execute Error Tests - -**For each error test:** - -1. **Set up error condition** - - Use prepared test data - - Example: Use `existing@example.com` - -2. **Trigger the error** - - Perform action that causes error - - Example: Try to create account with existing email - -3. **Verify error handling** - - Is error message shown? - - Is error message clear and helpful? - - Is error styling correct? - - Can user recover? - -4. **Check against design spec** - - Open error state specification - - Verify exact error message - - Verify error styling - - Verify recovery options - -5. **Document results** - - ```markdown - ## ES-001: Email Already Exists - - - Setup: Used test2@example.com (existing account) - - Action: Entered email, tapped "Create Account" - - Expected: Error: "This email is already registered. Try logging in instead." - - Actual: Error: "Email exists" (too brief) - - Result: FAIL ✗ - - Issue: Error message not helpful enough - - Screenshot: ES-001-error-message-FAIL.png - ``` - ---- - -### Record Error Test Results - -```markdown -# Error State Test Results - -## ES-001: Email Already Exists - -- Status: FAIL -- Issue: Error message too brief -- Severity: Medium - -## ES-002: Invalid Email Format - -- Status: PASS -- Real-time validation works correctly - -## ES-003: Weak Password - -- Status: PASS -- Password strength indicator works - -## ES-004: Network Timeout - -- Status: FAIL -- Issue: No timeout handling, app hangs -- Severity: High - -## Summary - -- Total Tests: 4 -- Passed: 2/4 (50%) -- Failed: 2/4 (50%) -- Total Issues: 2 -``` +1. Set up error condition using test data +2. Trigger the error +3. Verify error handling (message, styling, recovery) +4. Check against design spec +5. Document results using template --- ## 3. Edge Case Tests -### For Each Edge Case Test +**For each test in TS-XXX.yaml `edge_cases` section:** -**Load test from TS-XXX.yaml:** - -```yaml -edge_cases: - - id: 'EC-001' - name: 'User Closes App Mid-Onboarding' - steps: - - action: 'Start onboarding, complete signup' - - action: 'Close app (force quit)' - - action: 'Reopen app' - - expected: 'Resume at Family Setup' -``` - ---- - -### Execute Edge Case Tests - -**For each edge case:** - -1. **Set up unusual scenario** - - Follow setup instructions - - Create edge condition - -2. **Perform edge case action** - - Example: Force quit app - - Example: Enter 100-character name - - Example: Navigate back - -3. **Verify graceful handling** - - Does app crash? ✗ - - Does app handle gracefully? ✓ - - Is user experience smooth? - -4. **Document results** - - ```markdown - ## EC-001: User Closes App Mid-Onboarding - - - Setup: Completed signup, at Family Setup screen - - Action: Force quit app, reopened - - Expected: Resume at Family Setup (progress saved) - - Actual: Started at Welcome screen (progress lost) - - Result: FAIL ✗ - - Issue: Progress not saved - - Severity: High - - Screenshot: EC-001-progress-lost-FAIL.png - ``` - ---- - -### Record Edge Case Results - -```markdown -# Edge Case Test Results - -## EC-001: User Closes App Mid-Onboarding - -- Status: FAIL -- Issue: Progress not saved -- Severity: High - -## EC-002: User Navigates Back - -- Status: PASS -- Confirmation dialog works correctly - -## EC-003: Very Long Family Name - -- Status: PASS -- Field truncates at 50 characters - -## Summary - -- Total Tests: 3 -- Passed: 2/3 (67%) -- Failed: 1/3 (33%) -- Total Issues: 1 -``` +1. Set up unusual scenario +2. Perform edge case action +3. Verify graceful handling (no crash, smooth UX) +4. Document results using template --- ## 4. Design System Validation -### For Each Component +**For each component in TS-XXX.yaml `design_system_checks` section:** -**Load design system checks from TS-XXX.yaml:** - -```yaml -design_system_checks: - - id: 'DS-001' - name: 'Button Components' - checks: - - component: 'Primary Button' - instances: ['Get Started', 'Create Account'] - verify: - - 'Height: 48px' - - 'Background: #2563EB' - - 'Text: #FFFFFF' - - 'Typography: 16px, semibold' -``` - ---- - -### Validate Component Usage - -**For each component instance:** - -1. **Locate component** - - Find all instances in the flow - - Example: "Get Started" button, "Create Account" button - -2. **Measure dimensions** - - Use browser dev tools or design tools - - Check height, width, padding - -3. **Check colors** - - Use color picker tool - - Compare to design tokens - - Check hex values exactly - -4. **Check typography** - - Font size - - Font weight - - Line height - - Letter spacing - -5. **Check spacing** - - Padding inside component - - Margin around component - - Spacing between elements - -6. **Check states** - - Default state - - Hover state (if applicable) - - Active/pressed state - - Disabled state - - Focus state - -7. **Document results** - - ```markdown - ## DS-001: Button Components - - ### Primary Button: "Get Started" - - - Height: 48px ✓ - - Background: #3B82F6 ✗ (Expected: #2563EB) - - Text: #FFFFFF ✓ - - Typography: 16px, semibold ✓ - - Border radius: 8px ✓ - - Padding: 12px 24px ✓ - - Result: FAIL (wrong background color) - - Screenshot: DS-001-button-color-FAIL.png - - ### Primary Button: "Create Account" - - - Height: 48px ✓ - - Background: #3B82F6 ✗ (Expected: #2563EB) - - Text: #FFFFFF ✓ - - Typography: 16px, semibold ✓ - - Result: FAIL (same color issue) - ``` - ---- - -### Record Design System Results - -```markdown -# Design System Validation Results - -## DS-001: Button Components - -- Status: FAIL -- Issue: Primary button color incorrect (#3B82F6 vs #2563EB) -- Instances: All primary buttons affected -- Severity: High - -## DS-002: Input Components - -- Status: PASS -- All input fields match specifications - -## DS-003: Spacing and Layout - -- Status: PASS -- Screen padding: 20px ✓ -- Element spacing: 16px ✓ - -## Summary - -- Total Components: 3 types -- Compliant: 2/3 (67%) -- Non-compliant: 1/3 (33%) -- Target: >95% compliance -- Result: FAIL (below threshold) -``` +1. Locate all component instances +2. Measure dimensions (height, width, padding) +3. Check colors against design tokens +4. Check typography (size, weight, line height) +5. Check spacing +6. Check all states (default, hover, active, disabled, focus) +7. Document results using template --- ## 5. Accessibility Tests ### Screen Reader Testing - -**Enable screen reader:** - -- iOS: VoiceOver (Settings → Accessibility) -- Android: TalkBack (Settings → Accessibility) - -**Test navigation:** - -1. **Navigate through flow using only screen reader** - - Can you complete the flow? - - Are all elements announced? - - Is navigation order logical? - -2. **Check button labels** - - Are buttons descriptive? - - "Button" vs "Get Started button" - -3. **Check form field labels** - - Are fields announced with purpose? - - "Text field" vs "Email address text field" - -4. **Check error announcements** - - Are errors announced? - - Are they clear? - -5. **Document results** - - ```markdown - ## A11Y-001: Screen Reader Navigation - - - Setup: Enabled VoiceOver on iOS - - Test: Navigated through onboarding - - Result: PARTIAL PASS - - Issues: - - - "Get Started" button announced as just "Button" ✗ - - Email field announced correctly ✓ - - Password field announced correctly ✓ - - Error messages not announced ✗ - - Severity: Medium - ``` - ---- +- Enable VoiceOver (iOS) or TalkBack (Android) +- Navigate through flow using only screen reader +- Check button labels, form field labels, error announcements ### Color Contrast Testing - -**Use contrast checker tool:** - -1. **Check text on background** - - Body text: 4.5:1 minimum (WCAG AA) - - Large text: 3:1 minimum - -2. **Check button text** - - Button text on button background: 4.5:1 minimum - -3. **Check error text** - - Error text on background: 4.5:1 minimum - -4. **Document results** - - ```markdown - ## A11Y-002: Color Contrast - - - Body text on white: 7.2:1 ✓ (PASS) - - Button text on primary: 5.1:1 ✓ (PASS) - - Error text on white: 4.8:1 ✓ (PASS) - - Link text on white: 3.9:1 ✗ (FAIL - below 4.5:1) - - Result: FAIL (link contrast too low) - ``` - ---- +- Use contrast checker tool +- Body text: 4.5:1 minimum (WCAG AA) +- Large text: 3:1 minimum ### Touch Target Testing - -**Measure interactive elements:** - -1. **Check all buttons** - - Minimum: 44×44px - - Measure actual size - -2. **Check all input fields** - - Minimum height: 44px - - Measure actual height - -3. **Check spacing** - - Minimum 8px between targets - - Measure actual spacing - -4. **Document results** - - ```markdown - ## A11Y-003: Touch Targets - - - Primary buttons: 48×120px ✓ (PASS) - - Input fields: 48px height ✓ (PASS) - - Text links: 32px height ✗ (FAIL - below 44px) - - Spacing between buttons: 16px ✓ (PASS) - - Result: FAIL (text links too small) - ``` +- Measure all interactive elements +- Minimum: 44×44px +- Minimum 8px spacing between targets --- -### Record Accessibility Results +## Compile Overall Summary -```markdown -# Accessibility Test Results +After all tests complete, create overall test summary using template in substeps. -## A11Y-001: Screen Reader Navigation - -- Status: PARTIAL PASS -- Issues: 2 (button labels, error announcements) -- Severity: Medium - -## A11Y-002: Color Contrast - -- Status: FAIL -- Issue: Link contrast too low (3.9:1) -- Severity: Medium - -## A11Y-003: Touch Targets - -- Status: FAIL -- Issue: Text links too small (32px) -- Severity: Low - -## Summary - -- Total Tests: 3 -- Passed: 0/3 (0%) -- Partial: 1/3 (33%) -- Failed: 2/3 (67%) -- Total Issues: 4 -``` - ---- - -## Overall Test Summary - -**Compile all results:** - -```markdown -# Test Summary: DD-XXX [Flow Name] - -**Date:** 2024-12-09 -**Tester:** [Your name] -**Build:** v0.1.0-beta.1 -**Device:** iPhone 14 Pro (iOS 17) - -## Overall Result - -**Status:** FAIL (8 issues found, 3 high severity) - -## Test Coverage - -- Happy Path: 8/9 passed (89%) -- Error States: 2/4 passed (50%) -- Edge Cases: 2/3 passed (67%) -- Design System: 2/3 compliant (67%) -- Accessibility: 0/3 passed (0%) - -## Issues Summary - -**Total Issues:** 8 - -**By Severity:** - -- Critical: 0 -- High: 3 -- Medium: 3 -- Low: 2 - -**By Category:** - -- Functionality: 3 -- Design System: 1 -- Accessibility: 4 - -## Next Steps - -1. Create issue tickets for all 8 issues -2. Create detailed test report -3. Send to BMad for fixes -4. Schedule retest after fixes -``` +Include: +- Overall result (PASS/FAIL) +- Test coverage percentages +- Issues by severity +- Issues by category +- Next steps --- diff --git a/src/workflows/7-testing/steps/step-7.4-create-issues.md b/src/workflows/7-testing/steps/step-7.4-create-issues.md index 4d0d56e16..54bd57b71 100644 --- a/src/workflows/7-testing/steps/step-7.4-create-issues.md +++ b/src/workflows/7-testing/steps/step-7.4-create-issues.md @@ -23,424 +23,66 @@ Document all problems found during testing as issue tickets that BMad can fix. **Create issue file:** `issues/ISS-XXX-description.md` -**Numbering:** +**Numbering:** Start at ISS-001, increment for each issue, use leading zeros. -- Start at ISS-001 -- Increment for each issue -- Use leading zeros - ---- - -## Issue Template - -````markdown -# Issue: [Short Description] - -**ID:** ISS-XXX -**Severity:** [Critical | High | Medium | Low] -**Status:** Open -**Delivery:** DD-XXX -**Test:** TS-XXX, Check: [Test ID] -**Created:** 2024-12-09 -**Assigned:** BMad Developer - -## Description - -[Clear description of the problem] - -## Expected - -[What should happen according to design] - -## Actual - -[What actually happens] - -## Impact - -[Why this matters - user impact, business impact] - -## Design Reference - -- Design Spec: [Path to specification] -- Design Token: [Path to token if applicable] -- Component Spec: [Path to component spec if applicable] - -## Steps to Reproduce - -1. [Step 1] -2. [Step 2] -3. [Step 3] - -## Screenshot/Video - -![Issue screenshot](../testing/DD-XXX/screenshots/ISS-XXX.png) - -## Recommendation - -[How to fix this - be specific] - -```code -[Code example if applicable] -``` -```` - -## Related Issues - -- [Link to related issues if any] - ---- - -**Priority for fix:** [Next release | This release | Future] - -```` +**See:** [substeps/issue-templates.md](substeps/issue-templates.md) for complete issue template --- ## Severity Levels -### Critical -**Definition:** Blocks usage, prevents core functionality - -**Examples:** -- App crashes -- Cannot complete core flow -- Data loss -- Security vulnerability - -**Action:** Must fix immediately before any release +| Severity | Description | Fix Timeline | +|----------|-------------|--------------| +| **Critical** | App crashes, data loss, security | Immediate | +| **High** | Major functionality broken | This release | +| **Medium** | Feature wrong, confusing UX | This release | +| **Low** | Minor polish, nice to have | Future release | --- -### High -**Definition:** Major issue, significantly impacts UX +## Issue Writing Best Practices -**Examples:** -- Wrong button color (brand inconsistency) -- Missing error handling -- Progress not saved -- Accessibility blocker +**Be specific:** +- ❌ "Button looks wrong" +- ✅ "Primary button background #3B82F6, should be #2563EB per tokens/colors.json" -**Action:** Must fix before release +**Be actionable:** +- ❌ "Fix the transition" +- ✅ "Add 300ms fade transition per specifications.md line 45" + +**Be visual:** +- Include screenshots +- Annotate key areas +- Show expected vs actual --- -### Medium -**Definition:** Noticeable issue, impacts UX but has workaround +## Create Issues Summary -**Examples:** -- Error message not helpful enough -- Transition animation missing -- Screen reader labels incomplete -- Minor design system deviation - -**Action:** Fix soon, can ship with workaround - ---- - -### Low -**Definition:** Minor issue, cosmetic or edge case - -**Examples:** -- Text link touch target slightly small -- Minor spacing inconsistency -- Rare edge case not handled - -**Action:** Fix when possible, can ship as-is - ---- - -## Example Issues - -### Example 1: Functionality Issue +After creating all issues: ```markdown -# Issue: Transition Animation Missing +# Issues Summary: DD-XXX -**ID:** ISS-001 -**Severity:** Medium -**Status:** Open -**Delivery:** DD-001 -**Test:** TS-001, Check: HP-001-step-3 +**Total Issues:** X -## Description +| ID | Severity | Description | Status | +|----|----------|-------------|--------| +| ISS-001 | High | [Description] | Open | +| ISS-002 | Medium | [Description] | Open | -Transition from Login/Signup choice to Signup form is instant instead of smooth animated transition. - -## Expected - -Smooth 300ms fade transition when tapping "Create Account" button, as specified in design. - -## Actual - -Signup form appears instantly with no transition. Feels jarring and abrupt. - -## Impact - -- User experience feels less polished -- Doesn't match design specifications -- Reduces perceived quality - -## Design Reference - -- Design Spec: C-Scenarios/03-signup/Frontend/specifications.md#transitions -- Specification states: "300ms ease-in-out fade transition" - -## Steps to Reproduce - -1. Open app -2. Tap "Get Started" -3. Tap "Create Account" -4. Observe instant transition (no animation) - -## Screenshot - -![Instant transition](../testing/DD-001/screenshots/ISS-001-transition.png) - -## Recommendation - -Add transition animation to navigation: - -```tsx -// React Native - -```` - ---- - -**Priority for fix:** This release - -```` - ---- - -### Example 2: Design System Issue - -```markdown -# Issue: Button Color Incorrect - -**ID:** ISS-002 -**Severity:** High -**Status:** Open -**Delivery:** DD-001 -**Test:** TS-001, Check: DS-001 - -## Description - -Primary button background color doesn't match design system specification. Using lighter blue instead of brand primary. - -## Expected - -Primary button background: #2563EB (brand primary color) - -## Actual - -Primary button background: #3B82F6 (lighter blue, not brand color) - -## Impact - -- Brand inconsistency across app -- Doesn't match design system -- All primary buttons affected -- Reduces brand recognition - -## Design Reference - -- Design System: D-Design-System/03-Atomic-Components/Buttons/Button-Primary.md -- Design Token: D-Design-System/02-Foundation/Colors/tokens.json -- Token path: `button.primary.background` → `#2563EB` - -## Steps to Reproduce - -1. Open any screen with primary button -2. Observe button color -3. Compare to design token - -## Screenshot - -![Button color comparison](../testing/DD-001/screenshots/ISS-002-button-color.png) - -## Recommendation - -Update button component to use design token: - -```tsx -// Before -backgroundColor: '#3B82F6' - -// After -backgroundColor: tokens.button.primary.background // #2563EB -```` - -Affected components: - -- "Get Started" button -- "Create Account" button -- "Continue" button -- All primary buttons - ---- - -**Priority for fix:** This release (High severity) - -```` - ---- - -### Example 3: Accessibility Issue - -```markdown -# Issue: Button Labels Not Descriptive for Screen Reader - -**ID:** ISS-003 -**Severity:** Medium -**Status:** Open -**Delivery:** DD-001 -**Test:** TS-001, Check: A11Y-001 - -## Description - -Buttons are announced as just "Button" by screen reader instead of descriptive labels. - -## Expected - -Buttons should have descriptive accessibility labels: -- "Get Started button" -- "Create Account button" -- "Log In button" - -## Actual - -VoiceOver announces all buttons as just "Button" with no context. - -## Impact - -- Screen reader users cannot understand button purpose -- Fails WCAG 2.1 AA accessibility standards -- Blocks visually impaired users - -## Design Reference - -- Accessibility requirement: All interactive elements must have descriptive labels -- WCAG 2.1: 2.4.6 Headings and Labels (Level AA) - -## Steps to Reproduce - -1. Enable VoiceOver (iOS) or TalkBack (Android) -2. Navigate to Welcome screen -3. Focus on "Get Started" button -4. Observe announcement: "Button" (not descriptive) - -## Screenshot - -![VoiceOver announcement](../testing/DD-001/screenshots/ISS-003-voiceover.png) - -## Recommendation - -Add accessibility labels to all buttons: - -```tsx -