# Why-Based Specifications

**The critical difference between prompt-and-run vs. thoughtful specification**

---

## The Trigger Map: The Ultimate Why-Machine

**Before any specification, the Trigger Map establishes WHY:**

### Example: Transparent Pricing Feature

**Trigger Map Reasoning:**
```
TARGET GROUP: Budget-conscious customers
FEAR: Surprises and hidden costs
TRIGGER: Anxiety about final price
OUTCOME: Easier commitment to purchase
SOLUTION: Transparent price model explanation
```

**This WHY flows into specifications:**
```markdown
## Transparent Pricing Component

**WHY This Exists:**
Our main target group is afraid of surprises and hidden costs. 
By explaining our transparent price model, the customer has an 
easier time committing to the purchase.

**WHY Upfront (Not at Checkout):**
Anxiety happens early. Showing pricing transparency upfront 
reduces fear before it builds.

**WHY Detailed Breakdown (Not Just Total):**
"No hidden costs" needs proof. Itemized breakdown shows 
there's nothing hidden.

**WHAT NOT TO DO:**
- ❌ Don't hide pricing until checkout (increases anxiety)
- ❌ Don't show just total (doesn't prove transparency)
- ❌ Don't use fine print (contradicts "transparent")
```

**The Trigger Map WHY becomes the specification WHY.**

---

## The Problem with v4 WPS2C (Whiteport Sketch-to-Code)

**What happened:**
```
Designer: "Create a calendar for booking dog walks"
AI: *Runs with it*
Result: Generic calendar, missing the point
```

**What was missing:**
- No questioning to elevate thinking
- No capture of WHY decisions were made
- No understanding of business context
- AI "helped" by making assumptions

**Result:** Fast, but wrong. Better, but not right.

---

## The AI Habit Problem

**AI's default behavior:**
```
"I'll make this faster!"
"I'll make this better!"
"I'll add helpful features!"
```

**What AI misses:**
- WHY does this need to exist?
- WHO is this actually for?
- WHAT problem does this solve?
- WHAT should we NOT do?

**AI optimizes for implementation, not intention.**

---

## The Solution: Why-Based Specifications

### Traditional Specification (WHAT)

```markdown
## Calendar Component

**Features:**
- Week view
- Booking slots
- Color-coded states
- Countdown timers

**Visual:**
- 7 columns (days)
- 6 color states
- Timer in orange state
```

**Problem:** AI will implement this literally, but might:
- Add daily/monthly views ("better!")
- Add notifications ("helpful!")
- Make it generic ("reusable!")
- Miss the cultural context

---

### Why-Based Specification (WHY + WHAT)

```markdown
## Calendar Component

**WHY This Exists:**
Families struggle to coordinate dog care. Kids forget, parents nag, 
dogs suffer. This calendar reduces conflict by making responsibility 
visible and accountability fun.

**WHY Week View (Not Daily/Monthly):**
Swedish families think in weeks ("Vecka 40"). This matches their 
mental model. Daily view is too granular, monthly too abstract.
→ AI: Don't add daily/monthly views, even if you think it's "better"

**WHY 6 Color States:**
Visual, instant understanding for kids. No reading required.
- WHITE: Empty (neutral, inviting)
- GRAY: Booked (committed, not yet active)
- ORANGE: Countdown (urgent, act now)
- BLUE: Active (in progress, can't book another)
- GREEN: Completed (success, positive reinforcement)
- RED: Missed (accountability, not punishment)

→ AI: Don't simplify to 3 states, each serves a purpose

**WHY Countdown Timer (Not Notifications):**
Gentle urgency without nagging. Visible when user checks app.
Notifications would break the "fun, not punishing" tone.
→ AI: Don't add push notifications, even if you think it's "helpful"

**WHY Leaderboard Integration:**
Makes accountability a game, not a chore. Encourages participation.
→ AI: This is core to the experience, don't make it optional

**WHAT NOT TO DO:**
- ❌ Don't add daily/monthly views (wrong mental model)
- ❌ Don't add notifications (wrong tone)
- ❌ Don't make it generic (Swedish culture specific)
- ❌ Don't simplify states (each serves a purpose)
```

---

## What This Enables

### 1. AI Follows Instructions Correctly

**Without WHY:**
```
AI: "I added daily view for flexibility!"
Designer: "No, that breaks the mental model..."
```

**With WHY:**
```
Spec: "Week view matches Swedish 'Vecka 40' culture. Don't add daily view."
AI: *Implements week view only*
Designer: ✅ Perfect
```

---

### 2. AI Knows What to Skip

**Without WHY:**
```
AI: "I added push notifications for reminders!"
Designer: "No, that's nagging, not gentle urgency..."
```

**With WHY:**
```
Spec: "Countdown timer = gentle urgency. Notifications = nagging. Don't add notifications."
AI: *Skips notifications*
Designer: ✅ Exactly right
```

---

### 3. AI Preserves Intent During Changes

**Without WHY:**
```
Designer: "Make the countdown more prominent"
AI: *Makes it bigger, adds sound, adds vibration*
Designer: "No, that's too aggressive..."
```

**With WHY:**
```
Spec: "Countdown = gentle urgency, not aggressive nagging"
Designer: "Make countdown more prominent"
AI: *Makes it bigger, keeps gentle tone*
Designer: ✅ Got it
```

---

### 4. Future Developers Understand Context

**Without WHY:**
```
Developer: "Why can't users book multiple walks at once?"
*Removes blocking logic*
*Breaks the accountability system*
```

**With WHY:**
```
Spec: "One active walk per dog = accountability. Kids can't game the system 
       by booking everything then completing nothing."
Developer: "Oh, that's a business rule. I'll keep it."
```

---

## The Socratic Questioning Connection

**Agent asks WHY questions:**
```
Agent: "Why week view instead of daily?"
Designer: "Swedish families think in weeks..."
Agent: "Got it! Documenting:
        WHY: Matches Swedish 'Vecka 40' mental model
        WHAT NOT TO DO: Don't add daily/monthly views"
```

**This creates specifications that:**
- Capture reasoning, not just decisions
- Guide AI implementation correctly
- Prevent "helpful" mistakes
- Preserve intent over time

---

## Structure of Why-Based Specs

### For Each Component/Feature:

**1. WHY This Exists**
- What problem does it solve?
- What behavior change does it create?
- What value does it deliver?

**2. WHY These Specific Choices**
- Why this approach vs alternatives?
- What user need does this serve?
- What business goal does this support?

**3. WHAT NOT TO DO**
- What "improvements" would break the intent?
- What features should NOT be added?
- What assumptions should AI NOT make?

**4. WHAT (Traditional Specs)**
- Visual design
- Interactions
- Technical requirements

---

## Example: Dog Week "Book Walk" Button

### Traditional Spec (WHAT Only)

```markdown
## Book Walk Button

**Visual:**
- Blue background (#3B82F6)
- White text
- 48px height
- Rounded corners (8px)

**Action:**
- Click → Open booking modal
```

**AI might "improve" by:**
- Adding "Quick Book" shortcut
- Adding "Book for Week" bulk action
- Making it more prominent
- Adding animation

---

### Why-Based Spec

```markdown
## Book Walk Button

**WHY This Exists:**
Kids need a simple way to commit to walking the dog. 
"Booking" creates accountability - it's a promise, not just a plan.

**WHY "Book Walk" (Not "Add Walk"):**
"Book" = Future commitment (proactive)
"Add" = Past logging (retroactive)
We need both, they serve different purposes.

**WHY Simple Click (Not Quick Actions):**
Kids should think before booking. One deliberate action = one commitment.
Quick actions would encourage gaming the system (book everything, complete nothing).

**WHY This Visual Treatment:**
- Blue = Action color (consistent with design system)
- 48px = Touch-friendly for kids
- Not oversized = Important but not aggressive

**WHAT NOT TO DO:**
- ❌ Don't add "Quick Book" shortcuts (encourages gaming)
- ❌ Don't add "Book for Week" bulk action (defeats accountability)
- ❌ Don't make it more prominent (not the only action)
- ❌ Don't add animation (not a game, it's responsibility)

**WHAT (Implementation):**
- Background: Blue (#3B82F6)
- Text: White, 16px Medium
- Height: 48px
- Border radius: 8px
- Action: Click → Open booking modal
```

**Now AI knows:**
- What to implement
- What NOT to add
- WHY each decision was made
- How to handle future changes

---

## The Transformation

### v4 WPS2C (Prompt-and-Run)
```
Designer: "Create a booking calendar"
AI: *Generates generic calendar*
Designer: "No, that's not right..."
AI: *Tries again, still generic*
Designer: *Gives up or over-specifies every detail*
```

### v6 WDS (Why-Based Specifications)
```
Designer: "I need a booking calendar"
Agent: "Help me understand - why week view instead of daily?"
Designer: "Swedish families think in weeks..."
Agent: "Got it. Why 6 color states instead of simpler?"
Designer: "Each state serves a purpose for kids..."
Agent: "Perfect. Why countdown instead of notifications?"
Designer: "Gentle urgency, not nagging..."

Agent: "Documenting all the WHYs. This will help AI implement 
        correctly and prevent 'helpful' mistakes."

*Generates why-based specification*

AI: *Implements exactly right, skips "improvements" that would break intent*
Designer: ✅ Perfect first time
```

---

## The Meta-Benefit

**Why-based specifications are:**

✅ **Better for AI implementation**
- AI knows what NOT to do
- AI preserves intent during changes
- AI doesn't "help" incorrectly

✅ **Better for human developers**
- Understand context, not just requirements
- Make correct decisions when specs are unclear
- Maintain intent over time

✅ **Better for future designers**
- Understand why decisions were made
- Don't repeat solved problems
- Build on reasoning, not just patterns

✅ **Better for the designer**
- Socratic questioning elevates thinking
- Articulating WHY clarifies decisions
- Creates reusable design knowledge

---

## The Bottom Line

**Traditional specs answer: "What should we build?"**

**Why-based specs answer:**
- What should we build?
- Why should we build it this way?
- What should we NOT build?
- How should AI help (and not help)?

**Result:**
- AI implements correctly first time
- AI skips "improvements" that break intent
- Specifications become design knowledge
- Designer thinking is preserved and amplified

**This is the difference between:**
- Prompt-and-run (fast but wrong)
- Why-based specification (thoughtful and right)

---

## The BMad Method Flow

**The complete WHY chain:**

```
1. TRIGGER MAP (Phase 1: Business Model)
   ↓
   Establishes: WHO, WHAT TRIGGERS THEM, WHAT OUTCOME
   
2. SCENARIOS (Phase 1: Business Model)
   ↓
   Defines: User journeys, contexts, goals
   
3. INFORMATION ARCHITECTURE (Phase 2)
   ↓
   Structures: Content hierarchy, navigation
   
4. INTERACTION DESIGN (Phase 3)
   ↓
   Sketches: User flows, state transitions
   
5. UX SPECIFICATIONS (Phase 4)
   ↓
   Documents: WHY + WHAT + WHAT NOT TO DO
   
6. AI IMPLEMENTATION
   ↓
   Builds: Correctly, preserving intent
```

**Each phase carries WHY forward:**

- **Trigger Map** → WHY the business exists
- **Scenarios** → WHY users need this
- **IA** → WHY this structure
- **Interaction** → WHY this flow
- **UX Specs** → WHY these specific choices
- **AI** → Implements with full context

**Without Trigger Map, specifications lose their foundation.**

**With Trigger Map, every decision traces back to user needs and business goals.**

---

## The Bottom Line

**Traditional specs answer: "What should we build?"**

**Why-based specs answer:**
- What should we build?
- Why should we build it this way?
- What should we NOT build?
- How should AI help (and not help)?

**Trigger Map provides the ultimate WHY:**
- WHO is this for?
- WHAT triggers their need?
- WHAT outcome do they want?
- WHY will this solution work?

**Result:**
- AI implements correctly first time
- AI skips "improvements" that break intent
- Specifications become design knowledge
- Designer thinking is preserved and amplified

**This is the difference between:**
- Prompt-and-run (fast but wrong)
- Why-based specification (thoughtful and right)

---

**Trigger Map establishes WHY.**

**Socratic questioning reveals WHY.**

**Why-based specifications capture WHY.**

**AI implementation preserves WHY.**

**Designer thinking flows through the entire process.**

---

[← Back to Workflows](README.md)