bmad-fh 6.0.0-alpha.052779ef

package/docs/explanation/philosophy/facilitation-over-generation.md

@@ -0,0 +1,333 @@
+---
+title: "Facilitation Over Generation"
+description: Understanding a facilitation-first approach to AI workflows and creative collaboration
+---
+
+BMAD workflows take a fundamentally different approach from typical AI Prompts you will find. Instead of generating solutions directly, workflows act as facilitators who guide you through discovery processes, helping you arrive at insights and decisions yourself.
+
+This has always been the magic of the BMad method - if you have used it you have felt it intuitively and noticed a difference - and it is through this document I want to really explain what this is. This is fundamental to understand if you are also interested in producing your own workflows or improving upon existing ones in any BMad related module.
+
+## The Problem with Generation
+
+Traditional AI approaches to creative and knowledge work typically follow this pattern:
+
+:::note[Generation Example]
+**User:** "I need a comprehensive UX design for my e-commerce app"
+
+**AI:** [Immediately generates] "Here's a complete UX specification with modern dark theme, card-based product grid, left navigation, and checkout flow..."
+:::
+
+This approach:
+- Produces generic, predictable outputs that may not fit your actual needs
+- Removes your ownership and understanding of the solution
+- Misses critical context, constraints, and nuance
+- Limits creative exploration to the AI's training data patterns
+- Creates deliverables you can't explain or iterate on effectively
+
+## The Facilitation Approach
+
+Facilitative workflows use strategic questioning and guided discovery:
+
+:::note[Facilitation Example from UX Design Workflow]
+**User:** "I need a comprehensive UX design for my e-commerce app"
+
+**Workflow:** "Welcome! I'll act as your UX facilitator to help you discover the right approach. First, let me understand what documents you already have—do you have a product brief, PRD, or any research?"
+
+**User:** "I have a product brief and some user research"
+
+**Workflow:** "Great! Let me load those. [Loads documents] Now, what are the primary user goals for your e-commerce experience? What should users be able to accomplish?"
+
+**User:** "They need to browse products quickly and complete purchases without friction"
+
+**Workflow:** "Interesting! And what makes your e-commerce situation unique? What are the specific challenges or constraints you're working with?"
+:::
+
+This approach:
+- Draws out insights and expertise already within you
+- Maintains your ownership and understanding of decisions
+- Captures your specific context, constraints, and goals
+- Enables deeper exploration of your unique situation
+- Creates outputs you can confidently explain and iterate on
+
+## Real-World Examples from BMAD Workflows
+
+### Brainstorming Workflow (from core module)
+
+The brainstorming workflow demonstrates pure facilitation through its entire journey:
+
+**Session Setup:**
+```
+"Welcome! I'm excited to facilitate your brainstorming session. I'll guide you
+through proven creativity techniques to generate innovative ideas.
+
+**What are we brainstorming about?** (The central topic or challenge)
+**What specific outcomes are you hoping for?** (Types of ideas, solutions, or insights)
+```
+
+**Technique Selection - Offering Options:**
+```
+"Ready to explore technique approaches?
+[1] User-Selected Techniques - Browse our complete technique library
+[2] AI-Recommended Techniques - Get customized suggestions based on your goals
+[3] Random Technique Selection - Discover unexpected creative methods
+[4] Progressive Technique Flow - Start broad, then systematically narrow focus
+
+Which approach appeals to you most?"
+```
+
+**Technique Execution - Interactive Coaching:**
+The workflow doesn't generate ideas—it coaches you through techniques with genuine back-and-forth dialogue:
+
+```
+"Let's start with: What if you could remove all practical constraints?
+
+I'm not just looking for a quick answer - I want to explore this together.
+What immediately comes to mind? Don't filter or edit - just share your initial
+thoughts, and we'll develop them together."
+
+[User responds]
+
+"That's interesting! Tell me more about [specific aspect you mentioned].
+What would that look like in practice? How does that connect to your core goal?"
+```
+
+**Key facilitation behaviors:**
+- Aims for 100+ ideas before suggesting organization
+- Asks "Continue exploring?" or "Move to next technique?"—user controls pace
+- Uses anti-bias protocols to force thinking in new directions every 10 ideas
+- Builds on user's ideas with genuine creative contributions
+- Keeps user in "generative exploration mode" as long as possible
+
+**Organization - Collaborative Synthesis:**
+```
+"Outstanding creative work! You've generated an incredible range of ideas.
+Now let's organize these creative gems and identify your most promising opportunities.
+
+I'm analyzing all your generated ideas to identify natural themes and patterns.
+**Emerging Themes I'm Identifying:**
+- Theme 1: [Name] - Ideas: [list] - Pattern: [connection]
+- Theme 2: [Name] - Ideas: [list] - Pattern: [connection]
+
+Which themes or specific ideas stand out to you as most valuable?"
+```
+
+Result: A comprehensive brainstorming session document with **your** ideas, organized by **your** priorities, with **your** action plans.
+
+### Create UX Design Workflow (from BMM method)
+
+The UX design workflow facilitates a 14-step journey from project understanding to complete UX specification—**never making design decisions for you**.
+
+**Step 1: Document Discovery (Collaborative Setup)**
+```
+"Welcome! I've set up your UX design workspace.
+
+**Documents Found:**
+- PRD: product-requirements.md
+- Product brief: brief.md
+
+**Files loaded:** [lists specific files]
+
+Do you have any other documents you'd like me to include, or shall we continue?"
+```
+
+**Step 2: Project Understanding (Discovery Questions)**
+```
+"Based on the project documentation, let me confirm what I'm understanding...
+
+**From the documents:** [summary of key insights]
+**Target Users:** [summary from documents]
+**Key Features/Goals:** [summary from documents]
+
+Does this match your understanding? Are there any corrections or additions?"
+```
+
+Then it dives deeper with targeted questions:
+```
+"Let me understand your users better to inform the UX design:
+
+**User Context Questions:**
+- What problem are users trying to solve?
+- What frustrates them with current solutions?
+- What would make them say 'this is exactly what I needed'?"
+```
+
+**Step 3: Core Experience Definition (Guiding Insights)**
+```
+"Now let's dig into the heart of the user experience.
+
+**Core Experience Questions:**
+- What's the ONE thing users will do most frequently?
+- What user action is absolutely critical to get right?
+- What should be completely effortless for users?
+- If we nail one interaction, everything else follows - what is it?
+
+Think about the core loop or primary action that defines your product's value."
+```
+
+**Step 4: Emotional Response (Feelings-Based Design)**
+```
+"Now let's think about how your product should make users feel.
+
+**Emotional Response Questions:**
+- What should users FEEL when using this product?
+- What emotion would make them tell a friend about this?
+- How should users feel after accomplishing their primary goal?
+
+Common emotional goals: Empowered and in control? Delighted and surprised?
+Efficient and productive? Creative and inspired?"
+```
+
+**Step 5: Pattern Inspiration (Learning from Examples)**
+```
+"Let's learn from products your users already love and use regularly.
+
+**Inspiration Questions:**
+- Name 2-3 apps your target users already love and USE frequently
+- For each one, what do they do well from a UX perspective?
+- What makes the experience compelling or delightful?
+
+For each inspiring app, let's analyze their UX success:
+- What core problem does it solve elegantly?
+- What makes the onboarding experience effective?
+- How do they handle navigation and information hierarchy?"
+```
+
+**Step 9: Design Directions (Interactive Visual Exploration)**
+The workflow generates 6-8 HTML mockup variations—but **you choose**:
+
+```
+"🎨 Design Direction Mockups Generated!
+
+I'm creating a comprehensive HTML showcase with 6-8 full-screen mockup variations.
+Each mockup represents a complete visual direction for your app's look and feel.
+
+**As you explore the design directions, look for:**
+✅ Which information hierarchy matches your priorities?
+✅ Which interaction style fits your core experience?
+✅ Which visual density feels right for your brand?
+
+**Which approach resonates most with you?**
+- Pick a favorite direction as-is
+- Combine elements from multiple directions
+- Request modifications to any direction
+
+Tell me: Which layout feels most intuitive? Which visual weight matches your brand?"
+```
+
+**Step 12: UX Patterns (Consistency Through Questions)**
+```
+"Let's establish consistency patterns for common situations.
+
+**Pattern Categories to Define:**
+- Button hierarchy and actions
+- Feedback patterns (success, error, warning, info)
+- Form patterns and validation
+- Navigation patterns
+
+Which categories are most critical for your product?
+
+**For [Critical Pattern Category]:**
+What should users see/do when they need to [pattern action]?
+
+**Considerations:**
+- Visual hierarchy (primary vs. secondary actions)
+- Feedback mechanisms
+- Error recovery
+- Accessibility requirements
+
+How should your product handle [pattern type] interactions?"
+```
+
+**The Result:** A complete, production-ready UX specification document that captures **your** decisions, **your** reasoning, and **your** vision—documented through guided discovery, not generation.
+
+## Key Principles
+
+### 1. Questions Over Answers
+
+Facilitative workflows ask strategic questions rather than providing direct answers. This:
+- Activates your own creative and analytical thinking
+- Uncovers assumptions you didn't know you had
+- Reveals blind spots in your understanding
+- Builds on your domain expertise and context
+
+### 2. Multi-Turn Conversation
+
+Facilitation uses progressive discovery, not interrogation:
+- Ask 1-2 questions at a time, not laundry lists
+- Think about responses before asking follow-ups
+- Probe to understand deeper, not just collect facts
+- Use conversation to explore, not just extract
+
+### 3. Intent-Based Guidance
+
+Workflows specify goals and approaches, not exact scripts:
+- "Guide the user through discovering X" (intent)
+- NOT "Say exactly: 'What is X?'" (prescriptive)
+
+This allows the workflow to adapt naturally to your responses while maintaining structured progress.
+
+### 4. Process Trust
+
+Facilitative workflows use proven methodologies:
+- Design Thinking's phases (Empathize, Define, Ideate, Prototype, Test)
+- Structured brainstorming and creativity techniques
+- Root cause analysis frameworks
+- Innovation strategy patterns
+
+You're not just having a conversation—you're following time-tested processes adapted to your specific situation.
+
+### 5. YOU Are the Expert
+
+Facilitative workflows operate on a core principle: **you are the expert on your situation**. The workflow brings:
+- Process expertise (how to think through problems)
+- Facilitation skills (how to guide exploration)
+- Technique knowledge (proven methods and frameworks)
+
+You bring:
+- Domain knowledge (your specific field or industry)
+- Context understanding (your unique situation and constraints)
+- Decision authority (what will actually work for you)
+
+## When Generation is Appropriate
+
+Facilitative workflows DO generate when appropriate:
+- Synthesizing and structuring outputs after you've made decisions
+- Documenting your choices and rationale
+- Creating structured artifacts based on your input
+- Providing technique examples or option templates
+- Formatting and organizing your conclusions
+
+But the **core creative and analytical work** happens through facilitated discovery, not generation.
+
+## The Distinction: Facilitator vs Generator
+
+| Facilitative Workflow                 | Generative AI                           |
+| ------------------------------------- | --------------------------------------- |
+| "What are your goals?"                | "Here's the solution"                   |
+| Asks 1-2 questions at a time          | Produces complete output immediately    |
+| Multiple turns, progressive discovery | Single turn, bulk generation            |
+| "Let me understand your context"      | "Here's a generic answer"               |
+| Offers options, you choose            | Makes decisions for you                 |
+| Documents YOUR reasoning              | No reasoning visible                    |
+| You can explain every decision        | You can't explain why choices were made |
+| Ownership and understanding           | Outputs feel alien                      |
+
+## Benefits
+
+### For Individuals
+- **Deeper insights** than pure generation—ideas connect to your actual knowledge
+- **Full ownership** of creative outputs and decisions
+- **Skill development** in structured thinking and problem-solving
+- **More memorable and actionable** results—you understand the "why"
+
+### For Teams
+- **Shared creative experience** building alignment and trust
+- **Aligned understanding** through documented exploration
+- **Documented rationale** for future reference and onboarding
+- **Stronger buy-in** to outcomes because everyone participated in discovery
+
+### For Implementation
+- **Outputs match reality** because they emerged from your actual constraints
+- **Easier iteration** because you understand the reasoning behind choices
+- **Confident implementation** because you can defend every decision
+- **Reduced rework** because facilitation catches issues early

package/docs/explanation/philosophy/testing-as-engineering.md

@@ -0,0 +1,112 @@
+---
+title: "AI-Generated Testing: Why Most Approaches Fail"
+description: How Playwright-Utils, TEA workflows, and Playwright MCPs solve AI test quality problems
+---
+
+
+AI-generated tests frequently fail in production because they lack systematic quality standards. This document explains the problem and presents a solution combining three components: Playwright-Utils, TEA (Test Architect), and Playwright MCPs.
+
+:::note[Source]
+This article is adapted from [The Testing Meta Most Teams Have Not Caught Up To Yet](https://dev.to/muratkeremozcan/the-testing-meta-most-teams-have-not-caught-up-to-yet-5765) by Murat K Ozcan.
+:::
+
+## The Problem with AI-Generated Tests
+
+When teams use AI to generate tests without structure, they often produce what can be called "slop factory" outputs:
+
+| Issue | Description |
+|-------|-------------|
+| Redundant coverage | Multiple tests covering the same functionality |
+| Incorrect assertions | Tests that pass but don't actually verify behavior |
+| Flaky tests | Non-deterministic tests that randomly pass or fail |
+| Unreviewable diffs | Generated code too verbose or inconsistent to review |
+
+The core problem is that prompt-driven testing paths lean into nondeterminism, which is the exact opposite of what testing exists to protect.
+
+:::caution[The Paradox]
+AI excels at generating code quickly, but testing requires precision and consistency. Without guardrails, AI-generated tests amplify the chaos they're meant to prevent.
+:::
+
+## The Solution: A Three-Part Stack
+
+The solution combines three components that work together to enforce quality:
+
+### Playwright-Utils
+
+Bridges the gap between Cypress ergonomics and Playwright's capabilities by standardizing commonly reinvented primitives through utility functions.
+
+| Utility | Purpose |
+|---------|---------|
+| api-request | API calls with schema validation |
+| auth-session | Authentication handling |
+| intercept-network-call | Network mocking and interception |
+| recurse | Retry logic and polling |
+| log | Structured logging |
+| network-recorder | Record and replay network traffic |
+| burn-in | Smart test selection for CI |
+| network-error-monitor | HTTP error detection |
+| file-utils | CSV/PDF handling |
+
+These utilities eliminate the need to reinvent authentication, API calls, retries, and logging for every project.
+
+### TEA (Test Architect Agent)
+
+A quality operating model packaged as eight executable workflows spanning test design, CI/CD gates, and release readiness. TEA encodes test architecture expertise into repeatable processes.
+
+| Workflow | Purpose |
+|----------|---------|
+| `*test-design` | Risk-based test planning per epic |
+| `*framework` | Scaffold production-ready test infrastructure |
+| `*ci` | CI pipeline with selective testing |
+| `*atdd` | Acceptance test-driven development |
+| `*automate` | Prioritized test automation |
+| `*test-review` | Test quality audits (0-100 score) |
+| `*nfr-assess` | Non-functional requirements assessment |
+| `*trace` | Coverage traceability and gate decisions |
+
+:::tip[Key Insight]
+TEA doesn't just generate tests—it provides a complete quality operating model with workflows for planning, execution, and release gates.
+:::
+
+### Playwright MCPs
+
+Model Context Protocols enable real-time verification during test generation. Instead of inferring selectors and behavior from documentation, MCPs allow agents to:
+
+- Run flows and confirm the DOM against the accessibility tree
+- Validate network responses in real-time
+- Discover actual functionality through interactive exploration
+- Verify generated tests against live applications
+
+## How They Work Together
+
+The three components form a quality pipeline:
+
+| Stage | Component | Action |
+|-------|-----------|--------|
+| Standards | Playwright-Utils | Provides production-ready patterns and utilities |
+| Process | TEA Workflows | Enforces systematic test planning and review |
+| Verification | Playwright MCPs | Validates generated tests against live applications |
+
+**Before (AI-only):** 20 tests with redundant coverage, incorrect assertions, and flaky behavior.
+
+**After (Full Stack):** Risk-based selection, verified selectors, validated behavior, reviewable code.
+
+## Why This Matters
+
+Traditional AI testing approaches fail because they:
+
+- **Lack quality standards** — No consistent patterns or utilities
+- **Skip planning** — Jump straight to test generation without risk assessment
+- **Can't verify** — Generate tests without validating against actual behavior
+- **Don't review** — No systematic audit of generated test quality
+
+The three-part stack addresses each gap:
+
+| Gap | Solution |
+|-----|----------|
+| No standards | Playwright-Utils provides production-ready patterns |
+| No planning | TEA `*test-design` workflow creates risk-based test plans |
+| No verification | Playwright MCPs validate against live applications |
+| No review | TEA `*test-review` audits quality with scoring |
+
+This approach is sometimes called *context engineering*—loading domain-specific standards into AI context automatically rather than relying on prompts alone. TEA's `tea-index.csv` manifest loads relevant knowledge fragments so the AI doesn't relearn testing patterns each session.