@shaykec/bridge 0.4.25 → 0.4.27

package/modules/typescript-fundamentals/quiz.md

@@ -0,0 +1,104 @@
+# TypeScript Quiz
+
+## Question 1
+
+What is the primary benefit of TypeScript over JavaScript?
+
+A) Faster runtime performance
+B) Catch type errors at compile time
+C) Smaller bundle size
+D) Built-in testing framework
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: TypeScript's main value is static type checking — it catches type mismatches, typos, and incorrect API usage before the code runs, reducing runtime bugs. -->
+
+## Question 2
+
+What does `interface User { name: string; email?: string }` mean for `email`?
+
+A) email must be present
+B) email is optional — may be omitted
+C) email can be string or undefined
+D) email has a default value
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: The ? makes the property optional. Objects of type User can omit email. If present, it must be a string. -->
+
+## Question 3
+
+How do you narrow a union type `string | number` to use string methods?
+
+A) Use `as string` to cast
+B) Use `typeof value === 'string'` in a conditional
+C) Use `value.toString()` always
+D) TypeScript automatically narrows
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: typeof value === 'string' is a type guard. In the true branch, TypeScript narrows value to string, allowing .toUpperCase() etc. Casting with 'as' bypasses checking. -->
+
+## Question 4
+
+What does `T extends keyof U` mean in a generic?
+
+A) T must be a subtype of U
+B) T must be one of the keys of U
+C) U must have property T
+D) T and U are the same type
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: keyof U produces a union of U's keys. extends here means T is constrained to be one of those keys, enabling safe property access. -->
+
+## Question 5
+
+What does `Partial<User>` do?
+
+A) Makes User extend another type
+B) Makes all properties of User optional
+C) Makes User immutable
+D) Picks the first property of User
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Partial<T> is a utility type that makes every property of T optional. Useful for update payloads where you might only change some fields. -->
+
+## Question 6
+
+When would a JavaScript error occur that TypeScript would have caught?
+
+A) Never — TS prevents all JS errors
+B) When using `any` or type assertions to bypass checks
+C) Only in Node.js
+D) When the compiler is disabled
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: TypeScript can be bypassed with any, type assertions (as), or @ts-ignore. In those cases, invalid code can reach runtime. -->
+
+## Question 7
+
+<!-- VISUAL: fill-blank -->
+
+Complete the type annotation for a function that returns a Promise of User:
+
+```typescript
+async function fetchUser(id: string): ___0___<User> {
+  const res = await fetch(`/users/${id}`);
+  return res.json();
+}
+```
+
+<!-- ANSWER: Promise -->
+<!-- EXPLANATION: Async functions return a Promise. The return type should be Promise<User> to reflect that the function returns a Promise that resolves to a User. -->
+
+## Question 8
+
+<!-- VISUAL: fill-blank -->
+
+Complete the generic function that picks a property from an object:
+
+```typescript
+function getProp<T, K ___0___ keyof T>(obj: T, key: K): T[K] {
+  return obj[key];
+}
+```
+
+<!-- ANSWER: extends -->
+<!-- EXPLANATION: K extends keyof T constrains the generic K to be one of the keys of T. This ensures key is a valid property name and the return type T[K] is correctly inferred. -->

package/modules/typescript-fundamentals/resources.md

@@ -0,0 +1,42 @@
+# TypeScript — Resources
+
+## Videos
+
+- [TypeScript in 100 Seconds](https://www.youtube.com/watch?v=zQnBQ4tB3ZA) — Fireship. Quick overview.
+- [TypeScript Course](https://www.youtube.com/watch?v=30LWjhZzg50) — freeCodeCamp. Full beginner course.
+- [TypeScript Generics](https://www.youtube.com/watch?v=nViEqpgwxHE) — Fireship. Generics deep dive.
+
+## Articles and Readings
+
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html) — Official handbook. Start here.
+- [TypeScript Deep Dive](https://basarat.gitbook.io/typescript/) — Free online book. Comprehensive.
+- [Total TypeScript](https://www.totaltypescript.com/) — Matt Pocock. Advanced patterns and tips.
+
+## Books
+
+- **Effective TypeScript** by Dan Vanderkam — 62 specific ways to improve your TS code.
+- **Programming TypeScript** by Boris Cherny — From basics to advanced.
+
+## Tools and Playgrounds
+
+- [TypeScript Playground](https://www.typescriptlang.org/play) — Try TS in the browser, no setup.
+- [TypeScript Error Translator](https://ts-error-translator.vercel.app/) — Decode cryptic TS errors.
+- [ts-toolbelt](https://github.com/millsp/ts-toolbelt) — Advanced utility types library.
+
+## Podcasts
+
+- [Syntax.fm — TypeScript Episodes](https://syntax.fm/) — Wes Bos & Scott Tolinski cover TS tips, tricks, and migrations.
+- [JS Party — TypeScript](https://changelog.com/jsparty) — Panel discussions on TypeScript adoption and ecosystem.
+- [PodRocket — TypeScript](https://podrocket.logrocket.com/) — LogRocket's podcast with frequent TS-focused episodes.
+
+## Interactive and Visual
+
+- [Type Challenges](https://github.com/type-challenges/type-challenges) — Collection of TypeScript type-level puzzles from easy to extreme. Practice advanced types.
+- [TypeHero](https://typehero.dev/) — Interactive TypeScript challenges in the browser with instant feedback.
+- [Total TypeScript — Tips](https://www.totaltypescript.com/tips) — Matt Pocock's visual TypeScript tips and patterns.
+
+## Courses
+
+- [Total TypeScript (free workshops)](https://www.totaltypescript.com/) — Matt Pocock. Free beginner and type transformation workshops.
+- [freeCodeCamp — TypeScript Course](https://www.freecodecamp.org/news/learn-typescript-beginners-guide/) — Free comprehensive introduction.
+- [Execute Program — TypeScript](https://www.executeprogram.com/courses/typescript) — Spaced-repetition-based TypeScript course with interactive exercises.

package/modules/typescript-fundamentals/walkthrough.md

@@ -0,0 +1,71 @@
+# TypeScript Walkthrough — Learn by Doing
+
+## Step 1: Your First Types
+
+Let's add types to a simple function.
+
+<!-- hint:code language="typescript" highlight="1,3" -->
+
+**Embed:** https://www.typescriptlang.org/play
+
+**Task:** Write a function `add(a, b)` that adds two numbers. Add explicit parameter and return types. Call it with numbers and observe the output.
+
+**Question:** What happens if you try to call `add("1", "2")`? What does the compiler tell you, and what would JavaScript do at runtime?
+
+**Checkpoint:** The user understands that TypeScript rejects invalid argument types at compile time.
+
+---
+
+## Step 2: Interfaces
+
+<!-- hint:code language="typescript" highlight="1,4" -->
+
+**Task:** Define an interface `Product` with `id`, `name`, and `price`. Create a function `formatProduct(p: Product)` that returns a string like "Product: name ($price)".
+
+**Question:** What happens if you pass an object that has extra properties? What about one missing `price`?
+
+**Checkpoint:** The user can define and use interfaces, and understands excess property checks and required vs optional fields.
+
+---
+
+## Step 3: Unions and Narrowing
+
+**Task:** Write a function `double(x: string | number)` that returns the string repeated twice if it's a string, or the number multiplied by 2 if it's a number. Use `typeof` to narrow.
+
+**Question:** Why do we need the `typeof` check? What would TypeScript infer about `x` without it?
+
+**Checkpoint:** The user can narrow union types and explain why it's necessary.
+
+---
+
+## Step 4: Generics
+
+<!-- hint:card type="concept" title="Generics let TypeScript infer types from usage — T is resolved when you call the function" -->
+
+**Task:** Write a generic function `first<T>(arr: T[]): T | undefined` that returns the first element of an array. Test it with number and string arrays.
+
+**Question:** How does TypeScript know the return type when you call `first([1, 2, 3])`? Where does `T` get its value?
+
+**Checkpoint:** The user understands generic type inference from usage.
+
+---
+
+## Step 5: Generic Constraints
+
+**Task:** Write `getProperty<T, K extends keyof T>(obj: T, key: K): T[K]` that safely gets a property. The compiler should ensure `key` is a valid key of `obj`.
+
+**Question:** What does `K extends keyof T` mean? Why can't we just use `string` for the key?
+
+**Checkpoint:** The user can use `keyof` and constrained generics.
+
+---
+
+## Step 6: Utility Types
+
+<!-- hint:celebrate -->
+
+**Task:** Given a `User` interface, create a type `UserUpdate` where all fields are optional (using `Partial`). Create a function that accepts `UserUpdate` and merges it into an existing user.
+
+**Question:** When would you use `Partial` vs defining a separate interface with optional fields?
+
+**Checkpoint:** The user can apply utility types for common patterns.

package/modules/typescript-fundamentals/workshop.yaml

@@ -0,0 +1,146 @@
+# TypeScript Fundamentals — Interactive Workshop Scenarios
+# Each scenario has setup, files, task, validations, and Socratic agent prompts.
+
+scenarios:
+  - id: type-annotations
+    title: "Add Type Annotations to Functions"
+    difficulty: beginner
+    xp: 20
+    setup:
+      - "mkdir -p type-annotations && cd type-annotations"
+    files:
+      - name: greet.ts
+        content: |
+          function greet(name) {
+            return "Hello " + name;
+          }
+          console.log(greet("world"));
+        language: typescript
+        readonly: false
+    task: "Add proper TypeScript type annotations to the greet function so that name is a string and the return type is explicitly string. Then run the file with npx ts-node greet.ts (or tsc && node greet.js) and verify there are no type errors."
+    validations:
+      - label: "File contains type annotations"
+        check: file-changed
+        pattern: "name: string|: string"
+      - label: "No type errors when compiled/run"
+        check: output-contains
+        pattern: "Hello world"
+    hints:
+      - "TypeScript uses colon syntax for types — try adding : string after the parameter name."
+      - "You can also add a return type: function greet(name: string): string"
+      - "Run npx ts-node greet.ts to verify — if there are type errors, they will appear before execution."
+    agent_prompts:
+      on_start: "What do you think happens if someone passes a number to greet? How might types help catch that before the code runs?"
+
+  - id: interfaces
+    title: "Define and Use Interfaces"
+    difficulty: beginner
+    xp: 25
+    setup:
+      - "mkdir -p interfaces && cd interfaces"
+    files:
+      - name: user.ts
+        content: |
+          const user = {
+            id: 1,
+            name: "Alice",
+            email: "alice@example.com",
+            active: true,
+          };
+          console.log(user.name);
+        language: typescript
+        readonly: false
+      - name: task.ts
+        content: |
+          function formatUser(u) {
+            return u.name + " <" + u.email + ">";
+          }
+          const u = { id: 1, name: "Bob", email: "bob@example.com" };
+          console.log(formatUser(u));
+        language: typescript
+        readonly: false
+    task: "Create a User interface in user.ts with id (number), name (string), email (string), and active (boolean). Apply the interface to the user object. Then update task.ts to use the User interface for the formatUser parameter and ensure both files type-check correctly."
+    validations:
+      - label: "User interface defined and used"
+        check: file-changed
+        pattern: "interface User"
+    hints:
+      - "Interfaces describe the shape of an object. Start with: interface User { id: number; name: string; ... }"
+      - "Use the interface as a type: const user: User = { ... }"
+      - "For formatUser, type the parameter: function formatUser(u: User) { ... }"
+    agent_prompts:
+      on_start: "Without types, what could go wrong if formatUser receives an object missing the email field? How would an interface help?"
+
+  - id: generics
+    title: "Refactor to Generic Functions"
+    difficulty: intermediate
+    xp: 35
+    setup:
+      - "mkdir -p generics && cd generics"
+    files:
+      - name: utils.ts
+        content: |
+          function firstString(arr: string[]): string | undefined {
+            return arr[0];
+          }
+          function firstNumber(arr: number[]): number | undefined {
+            return arr[0];
+          }
+          function firstBool(arr: boolean[]): boolean | undefined {
+            return arr[0];
+          }
+          console.log(firstString(["a", "b"]));
+          console.log(firstNumber([1, 2, 3]));
+        language: typescript
+        readonly: false
+    task: "Refactor these three nearly-identical functions into a single generic function first<T> that works for any array type. Ensure the file compiles without errors and produces the same output."
+    validations:
+      - label: "Generic function replaces duplicates"
+        check: file-changed
+        pattern: "<T>|generic"
+      - label: "No compilation errors"
+        check: output-contains
+        pattern: "a|1"
+    hints:
+      - "Generics use angle brackets: function first<T>(arr: T[]): T | undefined"
+      - "The type parameter T lets TypeScript infer the return type from the input."
+      - "Run npx tsc --noEmit to check for type errors without emitting files."
+    agent_prompts:
+      on_start: "What do these three functions have in common? What varies? How might you write one function that handles all cases?"
+
+  - id: type-narrowing
+    title: "Use Type Guards and Narrowing"
+    difficulty: intermediate
+    xp: 35
+    setup:
+      - "mkdir -p type-narrowing && cd type-narrowing"
+    files:
+      - name: shapes.ts
+        content: |
+          type Circle = { kind: "circle"; radius: number };
+          type Rectangle = { kind: "rectangle"; width: number; height: number };
+          type Shape = Circle | Rectangle;
+
+          function area(shape: Shape): number {
+            if (shape.kind === "circle") {
+              return Math.PI * shape.radius * shape.radius;
+            }
+            return shape.width * shape.height;
+          }
+
+          const c: Circle = { kind: "circle", radius: 5 };
+          const r: Rectangle = { kind: "rectangle", width: 4, height: 6 };
+          console.log(area(c), area(r));
+        language: typescript
+        readonly: false
+    task: "The area function already narrows on the kind discriminant. Add a type guard function isCircle(shape: Shape): shape is Circle and use it in a new function describe(shape: Shape) that returns a string like 'Circle with radius 5' or 'Rectangle 4x6'. Ensure no type errors."
+    validations:
+      - label: "Type guard and describe function added"
+        check: file-changed
+        pattern: "is Circle|describe"
+    hints:
+      - "Type guard syntax: function isCircle(shape: Shape): shape is Circle { return shape.kind === 'circle'; }"
+      - "Use the guard: if (isCircle(shape)) { /* shape is Circle here */ }"
+      - "The describe function can use the guard or a switch on shape.kind."
+    agent_prompts:
+      on_start: "Inside the first branch, TypeScript knows shape is Circle. How does it know? What would happen if we added a new shape type?"

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

@@ -0,0 +1,123 @@
+# User Story Mapping — From User Goals to Interface
+
+<!-- hint:slides topic="User story mapping: backbone and body, walking skeleton, release slicing, and workshop facilitation" slides="5" -->
+
+## What Is Story Mapping?
+
+User story mapping is a collaborative technique for organizing user stories into a visual map that reflects the user's journey. It helps teams see the big picture, prioritize work, and slice releases that deliver value incrementally. Jeff Patton popularized the method in *User Story Mapping*.
+
+## Why It Works
+
+- **User-centered** — The map is organized by user activities, not features or technical components.
+- **Visual** — A 2D map (backbone + body) makes scope and sequence obvious.
+- **Release-ready** — Horizontal slices create coherent releases; vertical slices create thin end-to-end flows.
+- **Conversation starter** — The map fuels discussion about goals, constraints, and tradeoffs.
+
+## The Backbone vs The Body
+
+The map has two main parts:
+
+| Part | What It Is | Example (E‑commerce) |
+|------|------------|----------------------|
+| **Backbone** | High-level user activities (left-to-right, top row) | Browse → Add to cart → Check out → Track order |
+| **Body** | User tasks under each activity (stacked below) | Under "Check out": Enter shipping, Choose payment, Review order, Confirm |
+
+```mermaid
+flowchart LR
+    subgraph Backbone
+        A[Browse] --> B[Add to Cart]
+        B --> C[Check Out]
+        C --> D[Track Order]
+    end
+    subgraph Body["Body (tasks under each activity)"]
+        E[Search / Filter]
+        F[View product]
+        G[Add to cart]
+        H[Enter shipping]
+        I[Choose payment]
+        J[Confirm]
+    end
+```
+
+## Walking the User's Journey
+
+To build the map:
+
+1. **Identify the user** — Who is this map for? (e.g., new shopper, returning customer)
+2. **List activities** — What do they do at a high level? (Use verbs: browse, compare, buy)
+3. **Add tasks** — Under each activity, break it into specific tasks. "Check out" → Enter address, Select shipping, Enter payment, Review, Confirm.
+4. **Order left-to-right** — Activities and tasks follow the natural sequence of the user's journey.
+5. **Walk the map** — Read it like a story. Does it make sense? What's missing?
+
+## Slicing Releases: Walking Skeleton
+
+A **walking skeleton** is the thinnest end-to-end path that delivers value. You slice horizontally:
+
+- **Release 1 (MVP)** — One path through the map: minimal tasks to complete the journey.
+- **Release 2** — Add the next most important tasks or variations.
+- **Release 3+** — Expand functionality, edge cases, optimizations.
+
+```mermaid
+flowchart TD
+    subgraph Map["Story Map"]
+        B1[Browse - basic]
+        B2[Add to cart]
+        C1[Check out - minimal]
+        C2[Payment - one option]
+    end
+    subgraph R1["Release 1: Walking Skeleton"]
+        R1A[Browse] --> R1B[Add]
+        R1B --> R1C[Checkout]
+    end
+    subgraph R2["Release 2"]
+        R2A[More browse]
+        R2B[Multiple payment]
+    end
+```
+
+## From Map to MVP
+
+1. **Identify the outcome** — What does the user accomplish? (e.g., "Purchase a product")
+2. **Find the critical path** — The minimum tasks needed to reach that outcome.
+3. **Slice Release 1** — Those tasks become your MVP. Everything else is "later."
+4. **Write acceptance criteria** — For each story in the slice, define "done."
+
+## Story Mapping Workshops
+
+**How to run one:**
+
+1. **Prep** — Define the user and outcome. Bring sticky notes (digital or physical).
+2. **Activities** — As a group, brainstorm activities. Place them left-to-right.
+3. **Tasks** — Under each activity, add tasks. Encourage "that's too big—break it down."
+4. **Prioritize** — Vote or discuss. Move the most important tasks to the top of each column.
+5. **Slice** — Draw a line: above = Release 1, below = later.
+6. **Commit** — Capture the map and release boundaries. Treat it as a living artifact.
+
+**Tip:** Include developers, designers, and product. The conversation matters more than the map.
+
+## Connecting Stories to Acceptance Criteria
+
+Each task on the map can become one or more user stories:
+
+```
+As a [user], I want to [task] so that [outcome].
+```
+
+Acceptance criteria answer: "How do we know it's done?"
+
+- **Given** [context], **When** [action], **Then** [expected result]
+- Or: a short checklist of conditions that must be true
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| **Too granular too early** | Start with activities and a few tasks. Add detail when slicing. |
+| **Forgetting the user goal** | Always tie the map to a specific user and outcome. |
+| **Activities = features** | Activities are user actions (e.g., "Compare products"), not system features. |
+| **Skipping the walk** | Read the map as a story. Gaps and odd ordering will appear. |
+| **One map for everyone** | Different users have different journeys. Create separate maps if needed. |
+
+## Summary
+
+User story mapping turns user goals into a visual journey: backbone (activities) + body (tasks). Slice horizontally for releases; start with a walking skeleton. Run workshops, walk the map, and connect tasks to user stories with acceptance criteria. The map is a living artifact—update it as you learn.

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

@@ -0,0 +1,87 @@
+# User Story Mapping Exercises
+
+## Exercise 1: Build a Map from Scratch
+
+**Task:** Create a complete story map for "Plan a weekend trip" (user: leisure traveler). Include: backbone (4–5 activities), body (2–4 tasks per activity), and a walking skeleton release line.
+
+**Validation:**
+- [ ] Activities are user actions (verbs), not features
+- [ ] Tasks are specific enough to implement
+- [ ] Left-to-right order reflects the natural journey
+- [ ] Walking skeleton includes the minimum path to "trip planned"
+
+**Hints:**
+1. Example activities: Discover destinations → Compare options → Book → Prepare
+2. "Book" might include: Choose dates, Select accommodation, Enter payment, Confirm
+3. Walking skeleton = one path through; variations and extras go below the line
+
+---
+
+## Exercise 2: Slice Multiple Releases
+
+**Task:** Using your "Plan a weekend trip" map (or any map you've built), define three releases: MVP, Release 2, Release 3. For each, list the new tasks and the user outcome that release enables.
+
+**Validation:**
+- [ ] Each release has a clear outcome (e.g., "MVP: Book a basic trip")
+- [ ] Release 2 builds on Release 1; Release 3 builds on Release 2
+- [ ] No release includes tasks that depend on later releases
+- [ ] You can explain why each task landed in its release
+
+**Hints:**
+1. MVP = core happy path only
+2. Release 2 might add: multiple payment options, cancellation, itinerary export
+3. Release 3 might add: recommendations, social sharing, loyalty rewards
+
+---
+
+## Exercise 3: Convert Map to User Stories
+
+**Task:** Take the Release 1 slice from Exercise 1. Write user stories for each task. Add acceptance criteria using "Given / When / Then" or a checklist format.
+
+**Validation:**
+- [ ] Each task maps to at least one user story
+- [ ] Stories follow "As a [user], I want to [action] so that [outcome]"
+- [ ] Acceptance criteria are testable
+- [ ] Stories are ordered by journey sequence
+
+**Hints:**
+1. One task can become multiple stories if it's complex
+2. Acceptance criteria: "Given I'm on the booking page, When I enter valid card details, Then the booking confirms"
+3. Keep criteria focused—3–5 per story max
+
+---
+
+## Exercise 4: Spot the Mistakes
+
+**Task:** Review this map and identify at least three problems:
+
+> Activities: Login, Dashboard, Settings, API Integration, Database optimization
+
+> Tasks under "Login": Build OAuth, Hash passwords, Cache sessions, Add 2FA
+
+**Validation:**
+- [ ] At least three issues identified
+- [ ] Each issue has a suggested fix
+- [ ] The corrected map would better reflect a user journey
+
+**Hints:**
+1. "API Integration" and "Database optimization" are technical, not user activities
+2. Tasks should be user-facing; "Hash passwords" is implementation
+3. "Dashboard" might be a place, not an activity—what does the user *do* there?
+
+---
+
+## Exercise 5: Facilitate a Remote Workshop
+
+**Task:** Run a 20-minute remote story mapping session using a tool (Miro, FigJam, or Google Slides). Invite 2 colleagues. Build a map for a feature you're considering. Record the session or take screenshots.
+
+**Validation:**
+- [ ] Map is collaboratively built (not pre-made)
+- [ ] Backbone and body are present
+- [ ] At least one release slice is drawn
+- [ ] Participants contributed to the structure
+
+**Hints:**
+1. Share the user and outcome upfront
+2. Use sticky-note equivalents; color-code activities vs. tasks
+3. Use a timer to keep the session focused

package/modules/user-story-mapping/module.yaml

@@ -0,0 +1,41 @@
+slug: user-story-mapping
+title: "User Story Mapping -- From User Goals to Interface"
+version: 1.0.0
+description: "Transform user goals into a visual map and prioritized releases."
+category: ux-design
+tags: [user-stories, story-mapping, ux, user-flows, product-design, agile]
+difficulty: intermediate
+
+xp:
+  read: 15
+  walkthrough: 40
+  exercise: 25
+  quiz: 20
+  quiz-perfect-bonus: 10
+
+time:
+  quick: 5
+  read: 20
+  guided: 50
+
+prerequisites: []
+related: [writing-prds, design-critique, accessibility-fundamentals]
+
+triggers:
+  - "What is user story mapping?"
+  - "How do I map user journeys?"
+  - "How do I break features into user stories?"
+  - "How do I prioritize user stories?"
+
+visuals:
+  diagrams: [diagram-mermaid, diagram-flow]
+  quiz-types: [quiz-drag-order, quiz-matching]
+  slides: true
+
+sources:
+  - url: "https://www.oreilly.com/library/view/user-story-mapping/9781491904909/"
+    label: "User Story Mapping by Jeff Patton"
+    type: book
+  - url: "https://www.nngroup.com"
+    label: "Nielsen Norman Group"
+    type: docs

package/modules/user-story-mapping/quick-ref.md

@@ -0,0 +1,64 @@
+# User Story Mapping — Quick Reference
+
+## Backbone vs Body
+
+| Part | What It Is | Example |
+|------|------------|---------|
+| **Backbone** | High-level activities, left-to-right (top row) | Browse → Add to cart → Check out → Track |
+| **Body** | Tasks under each activity (stacked below) | Under "Check out": Enter shipping, Choose payment, Confirm |
+
+## Building the Map
+
+1. **Identify user** — Who is this for?
+2. **List activities** — Verbs, left-to-right
+3. **Add tasks** — Under each activity
+4. **Order** — Natural user journey sequence
+5. **Walk the map** — Read as a story; find gaps
+
+## Slice Releases
+
+| Slice | What It Means |
+|-------|---------------|
+| **Release 1** | Above the line—walking skeleton (MVP) |
+| **Release 2+** | Below the line—later iterations |
+
+**Rule:** Slice horizontally. Most important tasks at top of each column.
+
+## Walking Skeleton
+
+The thinnest end-to-end path that delivers user value. Minimum tasks to complete the journey.
+
+## User Story Format
+
+```
+As a [user], I want to [task] so that [outcome].
+```
+
+## Acceptance Criteria (Given/When/Then)
+
+```
+Given [context], When [action], Then [expected result]
+```
+
+## Workshop Checklist
+
+- [ ] Define user and outcome upfront
+- [ ] Activities = user actions (not features or screens)
+- [ ] Include developers, designers, product
+- [ ] Walk the map to validate
+- [ ] Vote or discuss to prioritize tasks
+- [ ] Draw the line: above = Release 1
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Too granular too early | Start with activities + few tasks; add detail when slicing |
+| Forgetting user goal | Tie map to specific user and outcome |
+| Activities = features | Activities are user actions (e.g., "Compare products") |
+| Skipping the walk | Read map left-to-right; gaps will appear |
+| One map for everyone | Different users → different maps |
+
+## Map → Stories
+
+Each task can become one or more user stories. Add acceptance criteria. Treat the map as a living artifact—update as you learn.