whiteport-design-studio 0.2.2 → 0.3.0

package/docs/learn/module-18-product-evolution/lesson-02-update-spec-project-code.md

@@ -0,0 +1,229 @@
+# Module 18: Product Evolution
+
+## Lesson 2: Update the Spec — Project the Code
+
+**The specification changes first. The code follows.**
+
+---
+
+## Spec First, Always
+
+In greenfield, the specification is the blueprint. You write it, then you build from it.
+
+In brownfield, the specification is also the record. It describes what exists today. When you change the product, you change the spec first — then project that change into the code.
+
+This is the single most important discipline in product evolution. Skip it, and specs drift from reality. Within months, nobody knows what's current. The spec says one thing, the product does another, and every future change becomes guesswork.
+
+---
+
+## Reading the Current Spec
+
+Before you change anything, read what's there.
+
+**You say to the agent:**
+> "Read the current specification for the signup form — P02-signup-form.md."
+
+**The agent reads and summarizes:**
+> "Current password field spec:
+> - Label: 'Password'
+> - Helper text: 'At least 8 characters'
+> - Validation: On blur — 8+ chars, 1 number, 1 letter
+> - Error message: 'Password must be at least 8 characters with a number and letter'
+> - Strength indicator: Appears on typing"
+
+Now you know exactly what exists. You know the designed intent, the states, the validation rules. You're not guessing from looking at the live product — you're reading the source of truth.
+
+### What if the spec doesn't match reality?
+
+This happens. Code changes sneak in without spec updates. A developer fixes something in production. A quick patch that was never documented.
+
+When you find drift:
+
+1. **Note it** — Document the discrepancy in the Design Log
+2. **Decide** — Does reality match the original intent, or has it drifted in a useful direction?
+3. **Update the spec** — Make the spec match what should be true, whether that's the current state or the intended change
+4. **Then proceed** — Now you're working from an accurate baseline
+
+Don't pretend drift doesn't exist. Acknowledge it, fix the spec, and move forward.
+
+---
+
+## Making the Spec Change
+
+The change you're making gets written into the specification before a single line of code changes.
+
+### What to update
+
+**The element itself** — New values, new behavior, new states.
+
+```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 + message
+- Strength indicator: Appears on typing
+```
+
+**The changelog** — What changed, why, and where it connects to strategy.
+
+```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 version number** — Increment it. Every change gets a version. This creates a trail you can follow backward through the product's history.
+
+### What to preserve
+
+Mark unchanged elements explicitly. This prevents the agent — or a future reader — from wondering whether something was intentionally kept or accidentally missed.
+
+```markdown
+- Validation: On blur (unchanged)
+- Strength indicator: Appears on typing (unchanged)
+- Email field: Not affected by this change
+```
+
+The word "unchanged" is documentation. It says: we looked at this, we decided to keep it.
+
+---
+
+## Projecting into Code
+
+With the spec updated, the agent builds from it. This is the same agentic development loop from Module 14 — but the starting point is an existing codebase, not a blank project.
+
+### The agent reads the updated spec
+
+**You say:**
+> "Implement the spec change for the password field. The updated spec is P02-signup-form.md v1.2."
+
+The agent reads the spec, finds the changed elements, and identifies what code to modify.
+
+### The agent finds the current implementation
+
+> "Found password field component at src/components/SignupForm/PasswordField.tsx"
+> "Current helper text: 'At least 8 characters'"
+> "Requirements display: Conditional — only shown on validation error"
+
+### The agent makes the change
+
+> "Updating helper text to '8+ characters, including a number and letter'"
+> "Changing requirements display from conditional to always visible"
+> "Preserving: validation logic, strength indicator, error styling"
+
+### The agent verifies with Puppeteer
+
+> "Opening localhost:3000/signup..."
+> "Helper text: '8+ characters, including a number and letter' — matches spec v1.2. ✓"
+> "Requirements visible before typing — confirmed. ✓"
+> "Blur validation still triggers. ✓"
+> "Strength indicator still works. ✓"
+> "Email field unchanged. ✓"
+
+The updated spec is the acceptance criteria. The agent checks each element against what the spec now says. Pass or fail — no ambiguity.
+
+---
+
+## The Scope Boundary
+
+The Design Log defines what changes and what doesn't. The spec update makes this concrete.
+
+When the agent is working, it has a clear boundary:
+
+- **Changed elements** — Implement exactly as the updated spec describes
+- **Unchanged elements** — Verify they still work, but don't modify them
+- **Out of scope** — Don't touch. Don't even look at.
+
+This is how you prevent a small change from snowballing. The password field helper text changes. The email field doesn't. The form layout doesn't. The submission flow doesn't.
+
+If the agent discovers something out of scope that needs attention — a bug, a related improvement, an inconsistency — it logs it in the Design Log for a future cycle. It doesn't fix it now.
+
+```markdown
+## Notes
+- Noticed: Submit button text could be clearer ("Create Account" vs "Sign Up")
+- Not in scope for this dialog — log for future evaluation
+```
+
+Discipline means doing one thing well, not three things halfway.
+
+---
+
+## Version History as Product Memory
+
+Over time, your specifications accumulate changelogs. This is your product's memory.
+
+```markdown
+### Changelog
+#### v1.3 (2026-04-20)
+- Added: Password visibility toggle
+- Reason: Accessibility audit finding
+- Connection: All personas — universal usability
+
+#### v1.2 (2026-03-15)
+- Changed: Password helper text shows full requirements upfront
+- Reason: Usability testing — 3/5 users confused
+- Connection: Felix — efficiency driving force
+
+#### v1.1 (2026-02-01)
+- Added: Password strength indicator
+- Reason: Security requirement from domain expert review
+- Connection: Business — reduce weak password incidents
+
+#### v1.0 (2026-01-15)
+- Initial specification
+```
+
+Every entry answers three questions:
+1. **What** changed?
+2. **Why** did it change?
+3. **Who** does it serve?
+
+When a new team member asks "why does the password field work this way?" — the answer is in the changelog. When someone proposes a change that was already tried and reverted — the history shows it. When you need to understand how a feature evolved — you read the versions, not the git log.
+
+The spec changelog is the design decision record. Git tracks what code changed. The spec tracks why.
+
+---
+
+## When to Write a New Spec vs. Update an Existing One
+
+### Update the existing spec when:
+
+- You're modifying an element that's already specified
+- The change affects behavior, content, or appearance of a documented component
+- The page or flow already has a specification
+
+This is most evolution work. You're changing what's there.
+
+### Create a new spec when:
+
+- You're adding a completely new page or flow
+- The new feature has no existing specification to extend
+- The scope is large enough that adding to an existing spec would make it unwieldy
+
+New specs follow the same format from Module 11. They just happen to live alongside existing ones.
+
+### Never skip the spec
+
+Even for a "quick fix." Even for "just a text change." If it changes what the user sees or experiences, it belongs in a specification.
+
+The cost of updating a spec is minutes. The cost of spec drift is hours — spent later, by someone who doesn't remember why things are the way they are.
+
+---
+
+## What's Next
+
+In the tutorial, you'll run a complete evolution cycle — from receiving feedback to closing the Design Log with a verified change.
+
+---
+
+**[Continue to Tutorial: Evolve Your Product →](tutorial-18.md)**
+
+---
+
+[← Back to Lesson 1](lesson-01-continuous-improvement.md) | [Module Overview](module-18-product-evolution-overview.md)
+
+*Part of Module 18: Product Evolution*

package/docs/learn/module-18-product-evolution/module-18-product-evolution-overview.md

@@ -0,0 +1,253 @@
+# Module 18: Product Evolution
+
+**Time: 30 min | Agent: Freya | Phase: Continuous**
+
+---
+
+## Greenfield and Brownfield
+
+In software development, there are two starting points:
+
+**Greenfield** — Building something from scratch. No existing code, no existing users, no constraints from previous decisions. You start with a blank page. This is what the course has been about so far.
+
+**Brownfield** — Working with something that already exists. There's a live product, real users, existing code, accumulated design decisions, and technical debt. You're not starting from zero — you're improving what's there.
+
+Most of your career will be brownfield. Products don't end at launch. They evolve.
+
+---
+
+## This Is Where You Start
+
+If you already have a product in production and want to improve it, this module is your entry point.
+
+You don't need to rebuild everything from scratch using WDS. You can adopt the methodology incrementally, one change at a time.
+
+Every improvement — a new feature, a redesign, a fix — becomes an opportunity to apply creative discipline. Over time, the product accumulates specifications, traceability, and design system components. The brownfield becomes greener with every iteration.
+
+---
+
+## WDS in Miniature
+
+Here is the key insight: **product evolution follows the exact same WDS process, just compressed.**
+
+Every change you make to a living product walks through the same steps you learned in this course — but smaller, faster, and focused on a single improvement.
+
+Here is the full WDS process and how each module maps to an evolution cycle:
+
+### Strategy (Where does this change come from?)
+
+**Product Brief (Module 4)** — You don't write a new brief for every change. But the original brief still anchors your decisions. When someone requests a feature, check: does it align with the product's purpose? If there is no brief, write one now. It's never too late.
+
+**Trigger Map (Module 6)** — Every change should trace to a persona, a driving force, or a business goal. If it doesn't connect, question whether it should happen. The trigger map is your filter against feature creep.
+
+### Design (What does the change look like?)
+
+**Scenarios (Module 8)** — For larger changes, outline the scenario. What's the user journey? Where does the user start, what do they do, where do they end up?
+
+**Sketching & Storyboarding (Modules 9-10)** — For complex features, sketch the concept before specifying. For smaller changes, you can skip straight to specification.
+
+**Specifications (Module 11)** — Update the existing specification, or create a new one. Every element, every state, every interaction — documented. This is the source of truth.
+
+**Components (Module 12-13)** — Does this change require new components? Can existing ones be reused? The design system grows with the product.
+
+### Build (How do we implement it?)
+
+**Agentic Development (Module 14)** — Start a Design Log. The agent builds the change from the specification while verifying with Puppeteer.
+
+**Visual Design (Module 15)** — Does the change need visual polish? Apply the same design layer process — code first, Figma when needed.
+
+**Design Delivery (Module 16)** — Package the change as a DD. Same format, same handoff process, smaller scope.
+
+### Validate (Does it work?)
+
+**Usability Testing (Module 17)** — Is the change worth testing with users? Apply the Whiteport Rule: if it's not worth showing to 5 users and 1 domain expert, it shouldn't be built. If it is worth building, test it.
+
+---
+
+## The Product Evolution Design Log
+
+The Design Log is the container for every change. In greenfield, it organizes a build session. In brownfield, it organizes an evolution cycle.
+
+The structure is identical:
+
+```markdown
+# Design Log: [Change Name]
+
+## Meta
+- Date: 2026-03-15
+- Type: Evolution (feature | modification | fix | optimization)
+- Input: User feedback / analytics / business request
+- Agent: Freya
+- Branch: fix/password-requirements
+- Status: In Progress
+
+## Context
+What exists today and why it needs to change.
+Trigger Map connection: which persona, driving force, business goal.
+
+## Scope
+What we're changing. What we're not touching.
+
+## Tasks
+1. [ ] Review current specification
+2. [ ] Update specification with change
+3. [ ] Implement change
+4. [ ] Agent verifies against updated spec
+5. [ ] Test with users (if applicable)
+6. [ ] Create DD for the change
+7. [ ] Update design system (if applicable)
+
+## Requirements
+- Must not break existing functionality
+- Must maintain design system consistency
+- Must connect to trigger map
+
+## Test Protocol
+- [ ] Changed functionality works as specified
+- [ ] Unchanged functionality still works
+- [ ] All states handled
+- [ ] Accessible
+```
+
+Same structure. Same discipline. The steps are the same — the scope is smaller.
+
+---
+
+## The 6-Activity Kaizen Cycle
+
+Phase 8 is **menu-driven** — each improvement cycle picks the activity it needs:
+
+```
+[A] Analyze Product      — Understand what exists, identify targets
+[S] Scope Improvement    — Define the change, write the scenario
+[D] Design Solution      — Design the change (borrows from Phase 4)
+[I] Implement            — Build the change (borrows from Phase 5)
+[T] Acceptance Test      — Verify against specs (borrows from Phase 5)
+[P] Deploy               — Package and deliver (borrows from Phase 4)
+```
+
+This is a **Kaizen cycle** — continuous, incremental improvement. After deploying one change, you return to [A] Analyze for the next opportunity.
+
+---
+
+## Types of Evolution
+
+### Feature Additions → [A] → [S] → [D] → [I] → [T] → [P]
+
+A new capability that didn't exist before. This is the closest to greenfield within brownfield — you're adding something new to an existing product.
+
+**Full cycle through all 6 activities.**
+
+### Feature Modifications → [A] → [S] → [D] → [I] → [T] → [P]
+
+An existing capability needs to change. User feedback, business pivot, or better idea.
+
+**Same cycle, but [A] Analyze focuses on the existing implementation and [S] Scope defines what changes vs what stays.**
+
+### Bug Fixes → [A] → [I] → [T] → [P]
+
+Something doesn't work as specified.
+
+**Shortened cycle — skip [S] Scope and [D] Design if the spec is correct. Go straight to implementation.**
+
+### Optimizations → [A] → [S] → [I] → [T] → [P]
+
+Same functionality, better experience. Faster, smoother, more accessible.
+
+**Skip [D] Design unless the optimization changes the visual. Focus on implementation and verification.**
+
+---
+
+## The Design System Grows
+
+Every evolution cycle is an opportunity to strengthen the design system.
+
+New component? Add it to the system. New pattern? Document it. Better approach to an existing component? Update the definition.
+
+Over time, the product accumulates:
+
+- Complete specifications for every page and flow
+- A growing component library
+- Documented decisions and rationale
+- Version history showing how the product evolved
+- Test results showing what works and what was changed
+
+The brownfield becomes as well-documented as a greenfield project — one change at a time.
+
+---
+
+## What You'll Learn
+
+### Lesson 1: The Evolution Cycle
+
+How to run a complete evolution cycle using the Product Evolution Design Log — from receiving feedback through implementation and delivery. The same WDS steps, compressed for a single change.
+
+### Lesson 2: Update the Spec — Project the Code
+
+The discipline of changing the specification before touching code. How to read the current spec, make the change, version it, and project it into the codebase through the agent. Preventing spec drift in brownfield development.
+
+---
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Skipping specification updates | Always update specs — even for small changes |
+| No trigger map connection | Every change serves a persona or business goal |
+| Fixing without understanding | Investigate root cause before changing code |
+| Letting specs drift from reality | Spec and implementation stay synchronized |
+| Not testing changes | Apply the Whiteport Rule |
+| Treating evolution as less rigorous | Same discipline, smaller scope |
+
+---
+
+## Lessons
+
+### [Lesson 1: The Evolution Cycle](lesson-01-continuous-improvement.md)
+Running WDS in miniature for every change
+
+### [Lesson 2: Update the Spec — Project the Code](lesson-02-update-spec-project-code.md)
+The specification changes first. The code follows.
+
+---
+
+## Tutorial
+
+### [Tutorial 18: Evolve Your Product](tutorial-18.md)
+Hands-on guide to running a complete evolution cycle
+
+---
+
+## Course Complete
+
+You've learned the full WDS 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 (this module)
+
+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.
+
+---
+
+## 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
+
+**You are the linchpin.**
+
+---
+
+*Part of the WDS Course: From Designer to Linchpin*
+
+**[← Back to Course Overview](../00-course-overview/00-course-overview.md)**
+
+---
+
+*Created by Mårten Angner and the Whiteport team*
+*Part of the BMad Method ecosystem*