294 lines
8.8 KiB
Markdown
294 lines
8.8 KiB
Markdown
# Tutorial 18: Evolve Your Product
|
|
|
|
**Hands-on guide to running a complete evolution cycle**
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
This tutorial walks you through a product evolution cycle — from receiving user feedback to closing the Agent Dialog with a verified change.
|
|
|
|
**Time:** 20-30 minutes
|
|
**Prerequisites:** Understanding of WDS workflow (Modules 4-17)
|
|
**Agent:** Idunn
|
|
**What you'll practice:** The complete evolution cycle using the Product Evolution Agent Dialog
|
|
|
|
---
|
|
|
|
## The Change Request
|
|
|
|
You've received this feedback from usability testing (Module 17):
|
|
|
|
> "3 of 5 users hesitated at the password field. They didn't know the full requirements until they submitted and got an error. One user tried three times before getting it right."
|
|
|
|
Your task: fix this using the evolution cycle.
|
|
|
|
---
|
|
|
|
## Step 1: Connect to Strategy (3 min)
|
|
|
|
### Trace the feedback
|
|
|
|
**You say to the agent:**
|
|
> "We have usability feedback about password requirements. Help me connect this to our Trigger Map."
|
|
|
|
**The agent analyzes:**
|
|
> "Looking at your Trigger Map...
|
|
>
|
|
> Persona: Felix — values speed and efficiency
|
|
> Driving force: 'Don't waste my time with unclear processes'
|
|
> Business goal: Reduce signup abandonment (currently 15% drop-off at password step)
|
|
>
|
|
> This directly opposes Felix's core driving force. Proceed."
|
|
|
|
### Apply the Whiteport Rule
|
|
|
|
Is this worth showing to 5 users and 1 domain expert? Yes — the problem was found by testing with users. The fix should be verified the same way.
|
|
|
|
---
|
|
|
|
## Step 2: Create the Evolution Agent Dialog (5 min)
|
|
|
|
**You say:**
|
|
> "Create an Agent Dialog for this evolution. Type: feature modification. Context: password field requirements are hidden until error."
|
|
|
|
**The agent creates:**
|
|
|
|
```markdown
|
|
# Agent Dialog: Password Requirements Clarity
|
|
|
|
## Meta
|
|
- Date: 2026-03-15
|
|
- Type: Feature modification
|
|
- Input: Usability test findings (Round 1)
|
|
- Agent: Idunn
|
|
- Branch: fix/password-requirements
|
|
- Status: In Progress
|
|
|
|
## Context
|
|
Current: Password field shows "At least 8 characters" as helper text.
|
|
Full requirements (8+ chars, 1 number, 1 letter) only appear as error
|
|
messages after submission.
|
|
|
|
Problem: Users don't know requirements until they fail. 3/5 users
|
|
hesitated. 1 user needed 3 attempts.
|
|
|
|
Trigger Map: Felix — efficiency driving force.
|
|
Business: 15% drop-off at password step.
|
|
|
|
## Scope
|
|
Change: Show full requirements upfront before user types.
|
|
Keep: Strength indicator, blur validation, error styling.
|
|
Don't touch: Email field, form layout, submission flow.
|
|
|
|
## Tasks
|
|
1. [ ] Review current spec P02-signup-form.md
|
|
2. [ ] Update spec with new requirements display
|
|
3. [ ] Implement the change
|
|
4. [ ] Verify with Puppeteer
|
|
5. [ ] Verify unchanged functionality
|
|
6. [ ] Quick guerrilla test
|
|
7. [ ] Close dialog
|
|
|
|
## Requirements
|
|
- Must not change form layout or other fields
|
|
- Requirements text must be clear without jargon
|
|
- Must maintain WCAG AA compliance
|
|
- Spec updated before implementation
|
|
|
|
## Test Protocol
|
|
- [ ] Helper text shows full requirements
|
|
- [ ] Requirements visible before user types
|
|
- [ ] Blur validation still triggers correctly
|
|
- [ ] Error messages still appear on invalid input
|
|
- [ ] Strength indicator still works
|
|
- [ ] Email field unchanged
|
|
- [ ] Touch targets maintained
|
|
```
|
|
|
|
**Review the dialog.** Does it cover everything? Adjust before proceeding.
|
|
|
|
---
|
|
|
|
## Step 3: Review and Update Spec (5 min)
|
|
|
|
### Read current specification
|
|
|
|
**The agent reads P02-signup-form.md:**
|
|
> "Current password field spec:
|
|
> - Label: 'Password'
|
|
> - Helper text: 'At least 8 characters'
|
|
> - Validation: On blur — 8+ chars, 1 number, 1 letter
|
|
> - Error: 'Password must be at least 8 characters with a number and letter'
|
|
> - Strength indicator: Appears on typing"
|
|
|
|
### Update the specification
|
|
|
|
**You say:**
|
|
> "Update the spec: helper text should read '8+ characters, including a number and letter'. Requirements visible at all times, not just on error. Add changelog entry."
|
|
|
|
**The agent updates P02-signup-form.md:**
|
|
|
|
```markdown
|
|
#### Password Field (v1.2)
|
|
- Label: "Password"
|
|
- Helper text: "8+ characters, including a number and letter"
|
|
- Requirements: Shown below field at all times
|
|
- Validation: On blur — check 8+ chars, 1 number, 1 letter
|
|
- Error: Red border + "Password must be at least 8 characters
|
|
with a number and letter"
|
|
- Strength indicator: Appears on typing
|
|
```
|
|
|
|
```markdown
|
|
### Changelog
|
|
#### v1.2 (2026-03-15)
|
|
- Changed: Password helper text shows full requirements upfront
|
|
- Reason: Usability testing — 3/5 users confused by hidden requirements
|
|
- Connection: Felix — efficiency driving force
|
|
```
|
|
|
|
**The agent logs:**
|
|
> "Tasks 1 and 2 complete. Spec updated to v1.2."
|
|
|
|
---
|
|
|
|
## Step 4: Implement and Verify (5 min)
|
|
|
|
### Build the change
|
|
|
|
**You say:**
|
|
> "Implement the spec change. Then verify with Puppeteer."
|
|
|
|
**The agent builds:**
|
|
> "Updating password field component..."
|
|
> "Helper text changed from 'At least 8 characters' to '8+ characters, including a number and letter'..."
|
|
> "Requirements now render on page load instead of on error..."
|
|
|
|
### Agent verifies with Puppeteer
|
|
|
|
> "Opening signup form at localhost:3000/signup..."
|
|
> "Helper text: '8+ characters, including a number and letter' — matches spec v1.2. ✓"
|
|
> "Requirements visible before typing — confirmed. ✓"
|
|
> "Entering 'short', blurring... error message appears. ✓"
|
|
> "Entering valid password... strength indicator appears. ✓"
|
|
> "Checking email field... unchanged. ✓"
|
|
> "Touch target on submit button: 48px. ✓"
|
|
> "6 of 6 criteria pass."
|
|
|
|
**You evaluate:** Does it look right? Does the helper text feel clear? Is the visual hierarchy maintained?
|
|
|
|
---
|
|
|
|
## Step 5: Quick Usability Check (5 min)
|
|
|
|
### Guerrilla test
|
|
|
|
Grab someone nearby. Don't explain anything. Just say:
|
|
|
|
> "Can you create an account on this?"
|
|
|
|
Watch what happens at the password field. Do they hesitate? Do they read the requirements? Do they get it right the first time?
|
|
|
|
**Result:**
|
|
> User entered password on first attempt without hesitation. Read the requirements text, typed a valid password. Done.
|
|
|
|
Compare to the original finding: 3 of 5 hesitated, 1 needed 3 attempts.
|
|
|
|
One guerrilla test isn't statistically significant — but combined with the original finding, it confirms the direction is right.
|
|
|
|
---
|
|
|
|
## Step 6: Close the Dialog (3 min)
|
|
|
|
### Commit and document
|
|
|
|
**The agent commits:**
|
|
> "Show password requirements upfront per spec v1.2"
|
|
|
|
**Close the Agent Dialog:**
|
|
|
|
```markdown
|
|
## Meta
|
|
- Status: Complete
|
|
|
|
## Summary
|
|
Updated password field to show requirements upfront.
|
|
Spec updated to v1.2. Puppeteer verified 6/6 criteria.
|
|
Guerrilla test confirmed improvement.
|
|
|
|
## Log
|
|
### Step 1: Review spec (completed)
|
|
- Read P02-signup-form.md v1.1
|
|
- Identified: requirements hidden until error
|
|
|
|
### Step 2: Update spec (completed)
|
|
- Helper text: "8+ characters, including a number and letter"
|
|
- Requirements visible at all times
|
|
- Changelog entry added with reason and connection
|
|
|
|
### Step 3: Implement (completed)
|
|
- Updated helper text component
|
|
- Requirements render on page load
|
|
- Commit: "Show password requirements upfront per spec v1.2"
|
|
|
|
### Step 4: Verify (completed)
|
|
- Puppeteer: 6/6 criteria pass
|
|
- Helper text matches, requirements visible, validation works,
|
|
strength indicator works, email field unchanged
|
|
|
|
### Step 5: Test (completed)
|
|
- Guerrilla test: user completed password on first attempt
|
|
- Original problem: 3/5 hesitated, 1 needed 3 attempts
|
|
```
|
|
|
|
---
|
|
|
|
## What You've Practiced
|
|
|
|
The complete evolution cycle:
|
|
|
|
1. **Connected** feedback to Trigger Map and business goal
|
|
2. **Created** an Evolution Agent Dialog with context
|
|
3. **Updated** the specification before touching code
|
|
4. **Built** from the updated spec
|
|
5. **Verified** with Puppeteer during development
|
|
6. **Tested** with a quick guerrilla session
|
|
7. **Documented** everything in the Agent Dialog
|
|
|
|
Same WDS process. Smaller scope. Full discipline.
|
|
|
|
---
|
|
|
|
## You've Completed the WDS Course!
|
|
|
|
**Congratulations.** You've learned the full methodology:
|
|
|
|
1. **Strategy** — Product Brief, Trigger Map, Platform Requirements
|
|
2. **Design** — Scenarios, Sketches, Storyboards, Specifications, Components, Design System
|
|
3. **Build** — Agentic Development, Visual Design, Design Delivery
|
|
4. **Validate** — Usability Testing
|
|
5. **Evolve** — Product Evolution
|
|
|
|
Whether you're starting from a blank page or improving a live product, the process is the same. The scope changes. The discipline doesn't.
|
|
|
|
**You are the linchpin.**
|
|
|
|
---
|
|
|
|
## What's Next?
|
|
|
|
- **Apply to a real project** — The only way to truly learn is to do
|
|
- **Join the community** — [Discord](https://discord.gg/whiteport)
|
|
- **Contribute** — WDS is open source
|
|
- **Teach others** — Spread creative discipline
|
|
|
|
---
|
|
|
|
**[← Back to Lesson 2](lesson-02-update-spec-project-code.md)** | **[← Back to Module Overview](module-18-product-evolution-overview.md)** | **[Back to Course Overview](../00-course-overview/00-course-overview.md)**
|
|
|
|
---
|
|
|
|
*Created by Mårten Angner and the Whiteport team*
|
|
*Part of Module 18: Product Evolution*
|