@shaykec/bridge 0.4.24 → 0.4.26

package/modules/user-story-mapping/quiz.md

@@ -0,0 +1,73 @@
+# User Story Mapping Quiz
+
+## Question 1
+
+What is the "backbone" in a user story map?
+
+A) The technical architecture that supports the product
+B) The high-level user activities, ordered left-to-right (top row)
+C) The most critical user stories for the release
+D) The dependencies between development teams
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: The backbone is the top row of the map—high-level user activities in sequence (e.g., Browse, Add to cart, Check out). It represents the user's journey at a coarse level. The "body" is the tasks stacked under each activity. -->
+
+## Question 2
+
+What is a "walking skeleton" release?
+
+A) A release that includes all planned features
+B) The thinnest end-to-end path that delivers user value
+C) A prototype with no backend
+D) The first sprint in an agile project
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: A walking skeleton is the minimum set of tasks that lets the user complete the main journey from start to finish. It's a horizontal slice across the map—the smallest viable release. It enables learning and iteration. -->
+
+## Question 3
+
+When building the backbone, activities should be:
+
+A) Technical components (e.g., "API," "Database")
+B) User actions or goals (e.g., "Search," "Book," "Track")
+C) Screens or pages (e.g., "Homepage," "Settings")
+D) Developer tasks (e.g., "Implement auth," "Add tests")
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: The backbone reflects the user's journey. Activities are what the user does—verbs like search, compare, book. Technical components, screens, and dev tasks belong elsewhere; the map stays user-centered. -->
+
+## Question 4
+
+How do you "slice" releases from a story map?
+
+A) Vertically—each column is a release
+B) Horizontally—draw a line; above = Release 1, below = later
+C) Randomly—stories are shuffled into sprints
+D) By team—each team takes a section
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Slicing is horizontal. The most important tasks sit at the top of each activity column. You draw a line: everything above is Release 1 (MVP), the next band is Release 2, etc. This keeps each release a coherent slice of the journey. -->
+
+## Question 5
+
+Which is a common mistake when story mapping?
+
+A) Starting with user activities
+B) Making the map too granular too early—listing every tiny task before understanding the flow
+C) Walking the map to validate the sequence
+D) Including designers and developers in the workshop
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Adding too much detail too early makes the map unwieldy and loses the big picture. Start with activities and a few key tasks. Add granularity when slicing releases. Walking the map (C) and including the team (D) are good practices. -->
+
+## Question 6
+
+What does "walking the map" mean?
+
+A) Physically moving around the room during the workshop
+B) Reading the map left-to-right as a story to validate flow and find gaps
+C) Deleting low-priority tasks
+D) Merging similar activities
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Walking the map means reading it as a narrative: "The user first does X, then Y, then Z." This helps spot missing steps, wrong order, or tasks that don't fit. It's a validation and sense-check step. -->

package/modules/user-story-mapping/resources.md

@@ -0,0 +1,29 @@
+# User Story Mapping — Resources
+
+## Videos
+
+- [User Story Mapping — Jeff Patton](https://www.youtube.com/watch?v=O7wLoFWE5HU) — 15 min, Agile Alliance. Overview of the method and why it works.
+- [Story Mapping in a Nutshell](https://www.youtube.com/watch?v=srQ2sRCNepo) — ~10 min. Quick visual walkthrough of backbone, body, and slicing.
+
+## Articles and Readings
+
+- [User Story Mapping](https://www.nngroup.com/articles/user-story-mapping/) — Nielsen Norman Group. UX perspective on story mapping and journey visualization.
+- [How to Use User Story Mapping](https://www.atlassian.com/agile/project-management/user-stories/user-story-mapping) — Atlassian. Practical guide with examples.
+- [Story Mapping 101](https://www.jpattonassociates.com/user-story-mapping/) — Jeff Patton's site. Core concepts and links to the book.
+- [Building a Story Map](https://www.smashingmagazine.com/2017/08/story-mapping-agile/) — Smashing Magazine. Step-by-step workshop facilitation.
+
+## Books
+
+- **User Story Mapping** by Jeff Patton — Definitive book on the method. O'Reilly. Covers backbone, body, slicing, workshops, and connecting to agile.
+
+## Tools
+
+- [Miro](https://miro.com) — Collaborative boards with story mapping templates.
+- [Trello](https://trello.com) — Use boards and lists to model backbone + body; swimlanes for releases.
+- [Figma](https://www.figma.com) — Design tools with FigJam for remote mapping workshops.
+- [Storiesonboard](https://storiesonboard.com) — Purpose-built story mapping tool with release slicing.
+
+## Templates
+
+- [Story Map Template (Miro)](https://miro.com/templates/user-story-mapping/) — Pre-built structure for mapping.
+- [Jeff Patton's Map Outline](https://www.jpattonassociates.com/the-new-backlog/) — Backlog vs. story map relationship.

package/modules/user-story-mapping/walkthrough.md

@@ -0,0 +1,86 @@
+# User Story Mapping Walkthrough — Learn by Doing
+
+## Before We Begin
+
+**Diagnostic:** Whose story is it? When you plan a feature, do you start from the user's journey or from the features you want to build? What's the difference—and why does it matter for prioritization?
+
+**Checkpoint:** You can articulate why "user does X, then Y" leads to different decisions than "we need screens A, B, C."
+
+---
+
+## Step 1: Identify the User and Outcome
+
+You're planning a feature: "Users can manage their saved payment methods." Before building a map, you need a clear user and outcome.
+
+**Task:** Write down (a) who this map is for (be specific: new shopper, returning customer, B2B admin?), and (b) one sentence describing the outcome they accomplish.
+
+**Question:** Why does defining the user matter? What if you had two different users—how might their maps differ?
+
+**Checkpoint:** You have a named user and a clear outcome. You understand that different users have different journeys.
+
+---
+
+## Step 2: Build the Backbone (Activities)
+
+For your chosen user and outcome, list the high-level activities they perform. Use verbs: browse, compare, add, checkout, track.
+
+<!-- hint:diagram mermaid-type="flowchart" topic="Story map structure: backbone (activities) on top, body (tasks) below" -->
+<!-- hint:list style="cards" -->
+
+**Task:** Write 4–6 activities in left-to-right order (the natural sequence of the user's journey). Don't add tasks yet—just the backbone.
+
+**Question:** How do you know when an activity is "right-sized"? What makes an activity too big or too small?
+
+**Checkpoint:** You have a backbone row: activities in sequence. Each activity is a user action, not a technical component or screen name.
+
+---
+
+## Step 3: Add the Body (Tasks)
+
+Under each activity, add 2–4 specific tasks. "Check out" might have: Enter shipping address, Choose payment method, Review order, Confirm.
+
+**Task:** Add tasks under each backbone activity. Keep them user-centric (what the user does, not how the system does it).
+
+**Question:** Where do you draw the line between "task" and "too granular"? When would you stop breaking down?
+
+**Checkpoint:** You have a 2D map: backbone on top, body stacked below. Tasks are concrete but not atomically tiny.
+
+---
+
+## Step 4: Walk the Map
+
+Read the map left-to-right as a story. "The user first does X, then Y, then Z..."
+
+**Task:** Walk your map aloud (or in your head). Note: gaps, wrong order, missing steps, tasks that don't fit.
+
+**Question:** What would you do if you found a task that belongs under a different activity? Or an activity that seems out of order?
+
+**Checkpoint:** You've validated the flow. You've identified at least one gap or ordering issue and know how to fix it.
+
+---
+
+## Step 5: Slice Release 1 (Walking Skeleton)
+
+The walking skeleton is the thinnest path that delivers value. Draw a horizontal line: above = Release 1.
+
+<!-- hint:buttons type="single" prompt="How do you decide what goes above the Release 1 line?" options="Everything users might want,Minimum to complete the outcome,Whatever fits the timeline,Whatever engineers can build" -->
+
+**Task:** For your map, identify the minimum tasks needed to complete the outcome. Draw your Release 1 line. What's in? What's "later"?
+
+**Question:** How do you decide what stays above the line vs below? What's the risk of putting too much in Release 1?
+
+**Checkpoint:** Release 1 is a coherent, minimal slice. You can articulate what the user gets and what's deferred.
+
+---
+
+## Step 6: Run a Mini-Workshop
+
+Imagine you're facilitating a 30-minute story-mapping workshop with two developers and one designer.
+
+<!-- hint:card type="concept" title="Story maps keep the workshop user-centered, not feature- or architecture-focused" -->
+
+**Task:** Write a brief agenda: (a) how you'd introduce the user and outcome, (b) how you'd get the backbone and body on the board (who speaks, what order), and (c) how you'd handle the "slice" discussion.
+
+**Question:** What could go wrong in the workshop? How would you keep it from becoming a feature list or technical architecture discussion?
+
+**Checkpoint:** You have a facilitation plan. You know how to keep the map user-centered and the conversation productive.

package/modules/writing-prds/content.md

@@ -0,0 +1,133 @@
+# Writing PRDs — From Problem to Spec
+
+<!-- hint:slides topic="PRD writing: problem-first thinking, JTBD, PRD structure, stakeholder alignment, and common anti-patterns" slides="5" -->
+
+## What Is a PRD?
+
+A **Product Requirements Document (PRD)** is a living document that defines what you're building, why, and for whom. It bridges the gap between strategy and execution—giving engineering, design, and stakeholders a shared understanding before a single line of code is written.
+
+A good PRD answers: *What problem are we solving?* and *How will we know we succeeded?*
+
+## Why PRDs Matter
+
+Without a PRD, teams often:
+
+- Build solutions before validating the problem
+- Scope creep from unclear boundaries
+- Disagree on "done" because success was never defined
+- Waste cycles re-explaining the same context
+
+A well-crafted PRD aligns everyone, reduces ambiguity, and makes prioritization decisions traceable.
+
+## PRD Structure
+
+A typical PRD includes these sections:
+
+| Section | Purpose |
+|---------|---------|
+| **Problem Statement** | Clear description of the user/customer pain |
+| **Goals & Non-Goals** | What we will and won't do (prevents scope creep) |
+| **User Stories / Use Cases** | Who does what and why |
+| **Success Metrics** | Measurable outcomes (quantified) |
+| **Scope** | In/out of scope, phased approach |
+| **Timeline** | High-level milestones |
+| **Open Questions** | Known unknowns, risks, dependencies |
+
+## Writing Effective Problem Statements
+
+A problem statement is **not** a solution in disguise. It focuses on the pain, not the fix.
+
+**Weak:** "Users need a dark mode toggle."
+
+**Strong:** "Users report eye strain when using the app for extended sessions in low-light environments, leading to reduced engagement after 30+ minutes."
+
+The **Jobs To Be Done (JTBD)** framework helps: *When [situation], I want to [motivation], so I can [outcome].*
+
+Example: *When I'm reviewing a long PR diff, I want to quickly spot high-risk changes, so I can focus my review time where it matters.*
+
+## Defining Measurable Success Criteria
+
+Vague metrics ("improve user satisfaction") are hard to act on. Make them **SMART**:
+
+- **Specific:** Which metric (e.g., NPS, retention, task completion)?
+- **Measurable:** Can we track it in our systems?
+- **Achievable:** Is it realistic given scope?
+- **Relevant:** Does it tie to the problem?
+- **Time-bound:** By when?
+
+**Example:** "Reduce time-to-first-value for new users from 14 days to 7 days within Q2, measured by cohort analysis."
+
+## JTBD Framework
+
+Jobs To Be Done reframes features as outcomes:
+
+| Element | Example |
+|---------|---------|
+| **Job** | Get my team aligned on the sprint |
+| **Situation** | End of planning, many opinions |
+| **Motivation** | Capture decisions and next steps |
+| **Outcome** | Everyone leaves with clarity on who does what |
+
+Using JTBD in your PRD keeps the focus on user value, not feature lists.
+
+## Common PRD Anti-Patterns
+
+1. **Solution-first thinking** — Starting with "We need a search bar" instead of "Users can't find what they need."
+2. **Vague success metrics** — "Improve engagement" with no baseline or target.
+3. **Missing non-goals** — Stakeholders assume everything is in scope.
+4. **No open questions** — Pretending uncertainty doesn't exist.
+5. **Waterfall rigidity** — Treating the PRD as unchangeable instead of iterative.
+
+## PRD Lifecycle: Problem → Build
+
+```mermaid
+flowchart LR
+  A[Problem] --> B[Research]
+  B --> C[PRD]
+  C --> D[Review]
+  D --> E[Build]
+  E -.->|feedback| B
+```
+
+1. **Problem** — Identify the pain point or opportunity.
+2. **Research** — User interviews, data, competitive analysis.
+3. **PRD** — Document findings, goals, and scope.
+4. **Review** — Stakeholder alignment, design/engineering input.
+5. **Build** — Execution with feedback loops back to research.
+
+## Templates
+
+Use a consistent template so your PRDs are comparable and complete. A minimal template:
+
+```markdown
+# [Feature Name]
+
+## Problem
+[1–2 paragraphs: who has the problem, what it is, why it matters]
+
+## Goals
+- [Goal 1]
+- [Goal 2]
+
+## Non-Goals
+- [What we're explicitly NOT doing]
+
+## Success Metrics
+- [Metric]: [Baseline] → [Target] by [Date]
+
+## User Stories
+- As a [persona], I want [action], so that [outcome]
+
+## Scope
+- In scope: ...
+- Out of scope: ...
+- Phase 2 considerations: ...
+
+## Open Questions
+- [Question 1]
+- [Question 2]
+```
+
+---
+
+PRDs are communication tools. A great PRD doesn't have to be long—it has to be **clear**. When in doubt, start with the problem statement and success metrics. Everything else supports those two.

package/modules/writing-prds/exercises.md

@@ -0,0 +1,93 @@
+# Writing PRDs — Exercises
+
+## Exercise 1: Problem vs Solution
+
+**Task:** For each statement, label it as a **problem** or **solution**. If it's a solution, rewrite it as a problem statement.
+
+1. "We need a search bar in the header."
+2. "Users spend 5+ minutes trying to find the export option, often giving up."
+3. "Add a dark mode toggle to settings."
+4. "New users abandon the onboarding flow at step 3 at a 40% rate."
+
+**Validation:**
+- [ ] Problems focus on pain, context, and impact
+- [ ] Solutions are rewritten to describe the underlying problem
+- [ ] No solution language in problem statements (no "we need," "add," "implement")
+
+**Hints:**
+1. Problem = who, what pain, why it matters
+2. Solution = the proposed fix (feature, button, page)
+3. "Users can't find X" is problem; "We need search" is solution
+
+---
+
+## Exercise 2: Write a JTBD
+
+**Task:** Pick a feature you know (real or hypothetical). Write a Jobs To Be Done statement using: *When [situation], I want to [motivation], so I can [outcome].*
+
+**Validation:**
+- [ ] Situation is specific (context, circumstance)
+- [ ] Motivation is the goal or need
+- [ ] Outcome is the benefit or result
+- [ ] The statement is about the user, not the system
+
+**Hints:**
+1. Start with "When I..." — the situation grounds the job
+2. "So I can" ties the action to value
+3. Avoid feature names; describe the job in user terms
+
+---
+
+## Exercise 3: Make Metrics SMART
+
+**Task:** These metrics are vague. Rewrite each as a SMART metric (Specific, Measurable, Achievable, Relevant, Time-bound). Include baseline, target, and timeframe where possible.
+
+1. "Improve user satisfaction"
+2. "Reduce time to complete onboarding"
+3. "Increase engagement"
+
+**Validation:**
+- [ ] Each metric names a specific measure
+- [ ] Baseline and target are included (or justified if unknown)
+- [ ] Timeframe is stated
+- [ ] Metric is actionable (you could track it)
+
+**Hints:**
+1. "Improve" → improve what? NPS? CSAT? Task completion?
+2. Add numbers: "from X to Y by [date]"
+3. If baseline is unknown, note "TBD—measure first"
+
+---
+
+## Exercise 4: Write Non-Goals
+
+**Task:** For a feature you're familiar with (e.g., "user profile export"), write 3–5 non-goals. These are things stakeholders might assume are in scope but are explicitly out.
+
+**Validation:**
+- [ ] Non-goals are concrete (not "everything else")
+- [ ] Each is plausible scope creep
+- [ ] Language is clear: "We will NOT..."
+- [ ] At least one addresses "nice to have" vs "must have"
+
+**Hints:**
+1. Think: What would stakeholders ask for? "Can we also...?"
+2. Non-goals prevent "while you're at it" creep
+3. "Phase 2" or "Future consideration" can be non-goals
+
+---
+
+## Exercise 5: Minimal PRD Draft
+
+**Task:** Draft a minimal PRD (1–2 pages) for a small feature. Include: Problem, Goals, Non-Goals, Success Metrics, and 2–3 User Stories. Use the PRD structure from the content.
+
+**Validation:**
+- [ ] Problem statement is problem-focused, not solution-focused
+- [ ] Goals and non-goals are explicit
+- [ ] Success metrics have baseline/target/timeframe (or TBD noted)
+- [ ] User stories follow "As a / I want / So that" format
+- [ ] Document is readable in under 5 minutes
+
+**Hints:**
+1. Start with the problem—everything else supports it
+2. Keep each section concise; 2–3 bullets each
+3. Open questions are fine—list them explicitly

package/modules/writing-prds/game.yaml

@@ -0,0 +1,83 @@
+games:
+  - type: classify
+    title: "Requirement Classifier"
+    categories:
+      - name: "Functional"
+        color: "#58a6ff"
+      - name: "Non-Functional"
+        color: "#3fb950"
+      - name: "Out of Scope"
+        color: "#8b949e"
+    items:
+      - text: "Users can reset their password via email link."
+        category: "Functional"
+      - text: "The app must load the dashboard within 2 seconds on 4G."
+        category: "Non-Functional"
+      - text: "Add dark mode and a mobile app in phase 1."
+        category: "Out of Scope"
+      - text: "Users can filter search results by date range and category."
+        category: "Functional"
+      - text: "The system must support 10,000 concurrent users."
+        category: "Non-Functional"
+      - text: "Integrate with CRM system X and analytics platform Y."
+        category: "Out of Scope"
+      - text: "Admins can bulk-export user data as CSV."
+        category: "Functional"
+      - text: "All user data must be encrypted at rest and in transit."
+        category: "Non-Functional"
+      - text: "Build an AI recommendation engine for the product catalog."
+        category: "Out of Scope"
+      - text: "Users receive an in-app notification when their order ships."
+        category: "Functional"
+
+  - type: speed-round
+    title: "Problem or Solution?"
+    rounds:
+      - question: "Users need a faster way to complete checkout on mobile."
+        options:
+          - "Problem"
+          - "Solution"
+        answer: 0
+        timeLimit: 12
+      - question: "We should add a one-click checkout button to reduce cart abandonment."
+        options:
+          - "Problem"
+          - "Solution"
+        answer: 1
+        timeLimit: 14
+      - question: "Support gets too many tickets about password reset confusion."
+        options:
+          - "Problem"
+          - "Solution"
+        answer: 0
+        timeLimit: 12
+      - question: "We need to build a chatbot to answer common support questions."
+        options:
+          - "Problem"
+          - "Solution"
+        answer: 1
+        timeLimit: 14
+      - question: "New users don't understand how to set up their first project."
+        options:
+          - "Problem"
+          - "Solution"
+        answer: 0
+        timeLimit: 12
+      - question: "Let's add an onboarding wizard with 3 steps."
+        options:
+          - "Problem"
+          - "Solution"
+        answer: 1
+        timeLimit: 14
+      - question: "Admins spend 2 hours weekly manually reconciling reports."
+        options:
+          - "Problem"
+          - "Solution"
+        answer: 0
+        timeLimit: 12
+      - question: "We should use React with a component library for the new dashboard."
+        options:
+          - "Problem"
+          - "Solution"
+        answer: 1
+        timeLimit: 14

package/modules/writing-prds/module.yaml

@@ -0,0 +1,44 @@
+slug: writing-prds
+title: "Writing PRDs — From Problem to Spec"
+version: 1.0.0
+description: "Learn to write product requirements documents that align teams and clarify scope."
+category: product-management
+tags: [prd, product-management, requirements, specification, documentation]
+difficulty: beginner
+
+xp:
+  read: 10
+  walkthrough: 30
+  exercise: 20
+  quiz: 15
+  quiz-perfect-bonus: 10
+  game: 20
+  game-perfect-bonus: 10
+
+time:
+  quick: 5
+  read: 15
+  guided: 45
+
+prerequisites: []
+related: [prioritization-frameworks, user-story-mapping]
+
+triggers:
+  - "How do I write a PRD?"
+  - "What should a product requirements document include?"
+  - "How do I define product requirements?"
+  - "What's the difference between a PRD and a spec?"
+
+visuals:
+  diagrams: [diagram-flow, diagram-mermaid]
+  quiz-types: [quiz-drag-order, quiz-timed-choice]
+  game-types: [classify, speed-round]
+  slides: true
+
+sources:
+  - url: "https://www.lennysnewsletter.com/p/prds-1-pagers-examples"
+    label: "Lenny's Newsletter — PRDs & 1-Pagers"
+    type: article
+  - url: "https://www.svpg.com/revisiting-the-product-spec/"
+    label: "SVPG — Revisiting the Product Spec"
+    type: article

package/modules/writing-prds/quick-ref.md

@@ -0,0 +1,77 @@
+# PRD Quick Reference
+
+## PRD Sections Checklist
+
+| Section | Purpose | Key Questions |
+|---------|---------|---------------|
+| Problem Statement | User pain, not solution | Who? What pain? Why does it matter? |
+| Goals | What we will achieve | What outcomes? For whom? |
+| Non-Goals | What we won't do | What's out of scope? |
+| Success Metrics | Measurable outcomes | Baseline? Target? Timeframe? |
+| User Stories | Use cases | As a / I want / So that |
+| Scope | In/out, phases | What's in v1? What's later? |
+| Open Questions | Known unknowns | What do we still need to learn? |
+
+## Problem vs Solution
+
+| Problem ✓ | Solution ✗ |
+|-----------|-----------|
+| "Users can't find key actions" | "We need a search bar" |
+| "Eye strain in low-light" | "Add dark mode" |
+| "Too many steps to complete task" | "Add a wizard" |
+
+## JTBD Template
+
+```
+When [situation/circumstance],
+I want to [motivation/goal],
+so I can [outcome/benefit].
+```
+
+**Example:** When I'm reviewing a long PR, I want to quickly spot high-risk files, so I can focus my review where it matters.
+
+## Success Metric Template
+
+```
+[Metric name]: [Baseline] → [Target] by [Date]
+```
+
+**Example:** Time-to-first-value: 14 days → 7 days by end of Q2
+
+## Common Anti-Patterns
+
+| Anti-Pattern | Fix |
+|--------------|-----|
+| Solution-first | Start with problem, not feature |
+| Vague metrics | Add baseline, target, timeframe |
+| No non-goals | List 3–5 explicit out-of-scope items |
+| Missing open questions | Capture unknowns and risks |
+| Waterfall rigidity | Treat PRD as living doc, iterate |
+
+## PRD Lifecycle (Mermaid)
+
+```mermaid
+flowchart LR
+  A[Problem] --> B[Research]
+  B --> C[PRD]
+  C --> D[Review]
+  D --> E[Build]
+```
+
+## Minimal PRD Template
+
+```markdown
+# [Feature Name]
+## Problem
+[2–3 sentences: who, what, why]
+## Goals
+- ...
+## Non-Goals
+- ...
+## Success Metrics
+- [Metric]: [Baseline] → [Target] by [Date]
+## User Stories
+- As a [persona], I want [action], so that [outcome]
+## Open Questions
+- ...
+```