@shaykec/bridge 0.4.25 → 0.4.26

package/modules/writing-prds/quiz.md

@@ -0,0 +1,103 @@
+# Writing PRDs — Quiz
+
+## Question 1
+
+Which of these is a problem statement rather than a solution?
+
+A) Users need a dark mode toggle
+B) Users report eye strain when using the app in low-light for 30+ minutes, reducing engagement
+C) We should add a settings page for appearance options
+D) The design team wants to support dark mode
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: A problem statement focuses on user pain (eye strain, reduced engagement) without prescribing a fix. A, C, and D either describe solutions (toggle, settings page) or stakeholders, not the underlying problem. -->
+
+## Question 2
+
+What does the JTBD framework help you capture?
+
+A) Technical implementation details
+B) The user's situation, motivation, and desired outcome
+C) Competitor feature comparisons
+D) Engineering estimates
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Jobs To Be Done captures: When [situation], I want to [motivation], so I can [outcome]. It's about user context and value, not technical specs, competitors, or estimates. -->
+
+## Question 3
+
+Why are non-goals important in a PRD?
+
+A) They make the document longer and more impressive
+B) They prevent scope creep by explicitly stating what's out of scope
+C) They replace the need for success metrics
+D) They are required for legal compliance
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Non-goals explicitly state what you're NOT building. Stakeholders often assume "everything related" is in scope; non-goals deflect those assumptions and keep the team focused. -->
+
+## Question 4
+
+Which success metric is MOST actionable?
+
+A) Improve user satisfaction
+B) Increase NPS from 42 to 50 by end of Q3
+C) Make the product better
+D) Users should like it more
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: A good success metric has a specific measure (NPS), a baseline (42), a target (50), and a timeframe (Q3). A, C, and D are vague and impossible to track or act on. -->
+
+## Question 5
+
+What is the main anti-pattern of "solution-first thinking"?
+
+A) Writing too many user stories
+B) Defining the solution before understanding the problem
+C) Including too many success metrics
+D) Skipping the non-goals section
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Solution-first thinking jumps to features (e.g., "we need X") before validating the problem. The PRD should start with the pain and outcome, not the proposed fix. -->
+
+## Question 6
+
+In the PRD lifecycle (Problem → Research → PRD → Review → Build), what role does Research play?
+
+A) It's optional—you can skip it for small features
+B) It validates the problem and informs the PRD with data and user input
+C) It happens only after the PRD is approved
+D) It replaces the need for a PRD
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Research (interviews, data, competitive analysis) validates the problem and provides evidence that informs the PRD. Without research, the PRD is guesswork. Research comes before the PRD, not after. -->
+
+## Question 7
+
+<!-- VISUAL: quiz-drag-order -->
+
+Put these PRD sections in the recommended order for the document:
+
+A) Success metrics
+B) Problem statement
+C) Solution and requirements
+D) Non-goals
+E) User stories / JTBD
+
+<!-- ANSWER: B,E,A,C,D -->
+<!-- EXPLANATION: Start with the problem statement, then user stories or JTBD to capture value. Define success metrics before solution details. Describe the solution and requirements, and close with non-goals to prevent scope creep. -->
+
+## Question 8
+
+<!-- VISUAL: quiz-drag-order -->
+
+Put these problem-to-spec steps in the correct flow:
+
+A) Write PRD
+B) Validate problem (research, data)
+C) Identify problem and outcome
+D) Review with stakeholders
+E) Build and iterate
+
+<!-- ANSWER: C,B,A,D,E -->
+<!-- EXPLANATION: Identify the problem and desired outcome first. Validate with research and data. Write the PRD. Review with stakeholders for alignment. Then build and iterate based on feedback. -->

package/modules/writing-prds/resources.md

@@ -0,0 +1,30 @@
+# Writing PRDs — Resources
+
+## Videos
+
+- [How to Write a PRD (Product Requirements Document)](https://www.youtube.com/watch?v=UQ5t-3r_Mjc) — Product School, ~15 min. Covers PRD structure and common mistakes.
+- [Product Requirements Document Workshop](https://www.youtube.com/watch?v=udGyb3_IJ2o) — Marty Cagan, SVPG, ~45 min. Deep dive on problem-first product specs.
+
+## Articles and Readings
+
+- [Examples and templates of 1-Pagers and PRDs](https://www.lennysnewsletter.com/p/prds-1-pagers-examples) — Lenny Rachitsky. Curated examples from top companies; great for stealing formats.
+- [Revisiting the Product Spec](https://www.svpg.com/revisiting-the-product-spec/) — Marty Cagan, SVPG. Why high-fidelity prototypes can replace lengthy PRDs; when specs still matter.
+- [Requirements Are Not](https://www.svpg.com/requirements-are-not/) — SVPG. Distinguishes hypotheses, assumptions, and true requirements.
+- [The Product Requirements Document (PRD) Guide](https://www.productplan.com/glossary/product-requirements-document/) — ProductPlan. Structured overview with templates.
+- [How to Write a Product Requirements Document](https://www.atlassian.com/agile/project-management/requirements) — Atlassian. Agile-friendly PRD practices.
+
+## Books
+
+- **Inspired** by Marty Cagan — Foundational PM read on discovery, opportunity assessment, and specs.
+- **The Lean Startup** by Eric Ries — Problem-solution fit, validated learning, and iterating on assumptions.
+
+## Podcasts
+
+- [Lenny's Podcast: How to write a PRD](https://www.lennyspodcast.com/) — Lenny Rachitsky. Episodes on product strategy and documentation; search for "PRD" or "spec."
+- [Product Talk: Building in Public](https://www.producttalk.org/) — Teresa Torres. Jobs-to-be-done and opportunity solution trees.
+
+## Tools
+
+- [Notion PRD Template](https://www.notion.so/templates/product-requirements-document) — Collaborative PRD templates.
+- [Confluence Product Spec Template](https://www.atlassian.com/software/confluence/templates/product-requirements) — Team-oriented spec format.
+- [Coda PRD Doc](https://coda.io/templates) — Search "PRD" for product doc templates.

package/modules/writing-prds/walkthrough.md

@@ -0,0 +1,87 @@
+# Writing PRDs Walkthrough — Learn by Doing
+
+## Before We Begin
+
+**Diagnostic:** When someone asks for a feature, are they describing the *problem* or the *solution*? If a stakeholder says "We need a dark mode button," what problem might they actually be trying to solve? How would you find out?
+
+**Checkpoint:** You can restate a feature request as a problem (a user need or pain) without mentioning the proposed fix.
+
+---
+
+## Step 1: Problem or Solution?
+
+Before writing anything, distinguish problem from solution.
+
+**Task:** Choose a real or hypothetical product area (e.g., "onboarding," "search," "notifications"). Write one sentence that describes a *problem* a user has, and one sentence that describes a *solution*. Make sure the problem stands alone—it should make sense even if the solution never existed.
+
+**Question:** If you showed your problem statement to someone who had never seen your solution, would they understand the pain? Or would they only understand it in terms of your proposed fix?
+
+**Checkpoint:** The user can articulate a problem without mentioning any feature or UI.
+
+---
+
+## Step 2: Write a Problem Statement
+
+**Task:** Expand your one-sentence problem into a 2–3 sentence problem statement. Include: who has the problem, what the pain is, and why it matters (impact). Avoid any mention of solutions.
+
+**Question:** What happens if you flip your statement and ask "So what?" repeatedly? Does each "so what?" lead to a clearer, more concrete outcome?
+
+**Checkpoint:** The problem statement is user-centered and avoids solution language.
+
+---
+
+## Step 3: Apply JTBD
+
+<!-- hint:card type="concept" title="Jobs To Be Done: When [situation], I want to [motivation], so I can [outcome]" -->
+
+**Task:** Restate your problem using the Jobs To Be Done format: *When [situation], I want to [motivation], so I can [outcome].* Write 2–3 variations with different situations or outcomes.
+
+**Question:** Does the JTBD wording reveal any assumptions you had about *who* the user is or *when* they experience this? Could there be different "jobs" for different segments?
+
+**Checkpoint:** The user produces at least one valid JTBD statement that maps to their problem.
+
+---
+
+## Step 4: Define Success Metrics
+
+**Task:** For your problem, define 1–2 success metrics. For each: name the metric, state the current baseline (or "unknown" if you don't have data), and set a target with a timeframe.
+
+**Question:** If you hit your target, would that *prove* you solved the problem? Or could the metric improve for unrelated reasons?
+
+**Checkpoint:** Metrics are specific, measurable, and tied to the problem.
+
+---
+
+## Step 5: Add Non-Goals
+
+<!-- hint:buttons type="single" prompt="A stakeholder asks to add 'export to PDF' to scope. How do you respond?" options="Add it; they know best,Add to next release; document as deferred,Negotiate: what problem does it solve?,Say no; out of scope" -->
+
+**Task:** List 2–3 things that are explicitly **out of scope** for this initiative. These are things stakeholders might assume are included but you're intentionally excluding.
+
+**Question:** Why is it as important to define what you're *not* doing as what you are? What happens when non-goals are missing?
+
+**Checkpoint:** Non-goals are concrete and would prevent common scope-creep scenarios.
+
+---
+
+## Step 6: Draft a Minimal PRD
+
+<!-- hint:list style="checklist" -->
+
+**Task:** Combine your problem statement, JTBD, success metrics, and non-goals into a minimal PRD. Add a "User Stories" section with 2–3 stories that support the goals.
+
+**Question:** If an engineer read this PRD tomorrow, what would they still need to ask you? What's missing?
+
+**Checkpoint:** The PRD has clear sections and could be shared for feedback.
+
+---
+
+## Step 7: Review for Anti-Patterns
+
+<!-- hint:celebrate -->
+
+**Task:** Re-read your PRD. Check for: solution-first language, vague metrics, missing non-goals, and hidden assumptions. Revise at least one section.
+
+**Question:** Which anti-pattern are you most likely to slip into in your own work? How could you catch it next time?
+
+**Checkpoint:** The user identifies and fixes at least one anti-pattern in their draft.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaykec/bridge",
-  "version": "0.4.25",
+  "version": "0.4.26",
   "type": "module",
   "description": "Communication hub — HTTP + WebSocket + SSE server with template engine",
   "main": "src/server.js",