@shaykec/bridge 0.4.25 → 0.4.27

package/modules/sql-fundamentals/quick-ref.md

@@ -0,0 +1,53 @@
+# SQL Quick Reference
+
+## Basic Query
+
+```sql
+SELECT col1, col2 FROM table WHERE condition ORDER BY col LIMIT n OFFSET m;
+```
+
+## JOINs
+
+| Join | Result |
+|------|--------|
+| INNER JOIN | Only matches |
+| LEFT JOIN | All left + matches from right |
+| RIGHT JOIN | All right + matches from left |
+| FULL OUTER | All from both |
+
+## Aggregates
+
+| Function | Purpose |
+|----------|---------|
+| COUNT(*) | Number of rows |
+| SUM(col) | Sum of values |
+| AVG(col) | Average |
+| MIN(col), MAX(col) | Min/Max |
+
+## WHERE vs HAVING
+
+| Clause | When |
+|--------|------|
+| WHERE | Before GROUP BY; row-level filter |
+| HAVING | After GROUP BY; group-level filter |
+
+## Normalization
+
+| Form | Rule |
+|------|------|
+| 1NF | Atomic values, no repeating groups |
+| 2NF | 1NF + no partial dependencies |
+| 3NF | 2NF + no transitive dependencies |
+
+## Common Patterns
+
+```sql
+-- Pagination
+SELECT * FROM t ORDER BY id LIMIT 10 OFFSET 20;
+
+-- Exists check
+SELECT * FROM users u WHERE EXISTS (SELECT 1 FROM orders o WHERE o.user_id = u.id);
+
+-- Top N per group (simplified)
+SELECT * FROM (SELECT *, ROW_NUMBER() OVER (PARTITION BY group_col ORDER BY sort_col) rn FROM t) WHERE rn <= 5;
+```

package/modules/sql-fundamentals/quiz.md

@@ -0,0 +1,103 @@
+# SQL Quiz
+
+## Question 1
+
+What does an INNER JOIN return?
+
+A) All rows from both tables
+B) Only rows with matching values in both tables
+C) All rows from the left table
+D) Only the first matching row from each table
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: INNER JOIN returns only rows where the join condition is satisfied in both tables. Rows with no match in the other table are excluded. -->
+
+## Question 2
+
+What is the difference between LEFT JOIN and INNER JOIN?
+
+A) They are the same
+B) LEFT JOIN includes all rows from the left table, even with no match
+C) LEFT JOIN is faster
+D) INNER JOIN includes NULLs
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: LEFT JOIN returns all rows from the left table. Where there's no match in the right table, right-side columns are NULL. INNER JOIN excludes such rows. -->
+
+## Question 3
+
+When do you use HAVING instead of WHERE?
+
+A) HAVING is for strings, WHERE is for numbers
+B) HAVING filters after aggregation; WHERE filters before
+C) HAVING is for JOINs, WHERE is for single tables
+D) They are interchangeable
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: WHERE filters rows before GROUP BY. HAVING filters groups after aggregation. You use HAVING when the condition involves an aggregate (e.g., SUM(amount) > 100). -->
+
+## Question 4
+
+What does 2NF (Second Normal Form) require?
+
+A) No duplicate rows
+B) No partial dependencies — all non-key attributes depend on the whole primary key
+C) No more than 2 columns per table
+D) All tables must have a foreign key
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: 2NF builds on 1NF (atomic values) and requires that no non-key attribute depends on only part of a composite primary key. This eliminates partial dependencies. -->
+
+## Question 5
+
+Which query finds users who have placed no orders? (users.id, orders.user_id)
+
+A) SELECT * FROM users INNER JOIN orders ON users.id = orders.user_id
+B) SELECT * FROM users LEFT JOIN orders ON users.id = orders.user_id WHERE orders.id IS NULL
+C) SELECT * FROM users WHERE orders.user_id IS NULL
+D) SELECT * FROM users RIGHT JOIN orders ON users.id = orders.user_id
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: LEFT JOIN keeps all users. Where there's no order, orders columns are NULL. WHERE orders.id IS NULL filters to users with no matching order. -->
+
+## Question 6
+
+What is the purpose of an index?
+
+A) To store backup data
+B) To speed up queries on indexed columns
+C) To enforce unique values
+D) To reduce storage
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Indexes create a data structure (e.g., B-tree) that speeds up lookups, WHERE, JOIN, and ORDER BY on indexed columns. They trade write speed and storage for read speed. -->
+
+## Question 7
+
+<!-- VISUAL: drag-order -->
+
+Put these SQL clause phases in the order they are logically evaluated during query execution:
+
+A) ORDER BY
+B) WHERE
+C) FROM
+D) GROUP BY / HAVING
+
+<!-- ANSWER: C,B,D,A -->
+<!-- EXPLANATION: SQL evaluates FROM first (identify tables), then WHERE (filter rows), then GROUP BY/HAVING (aggregation), then ORDER BY (sort results). SELECT projects columns throughout but the logical order of row processing is FROM → WHERE → GROUP BY → ORDER BY. -->
+
+## Question 8
+
+<!-- VISUAL: fill-blank -->
+
+Complete the query to find customers who have ordered more than 5 times:
+
+```sql
+SELECT customer_id, COUNT(*) AS order_count
+FROM orders
+GROUP BY customer_id
+___0___ COUNT(*) > 5;
+```
+
+<!-- ANSWER: HAVING -->
+<!-- EXPLANATION: HAVING filters after aggregation. WHERE cannot use aggregate functions like COUNT(*). HAVING applies to grouped rows, so HAVING COUNT(*) > 5 correctly filters to customers with more than 5 orders. -->

package/modules/sql-fundamentals/resources.md

@@ -0,0 +1,42 @@
+# SQL — Resources
+
+## Videos
+
+- [SQL in 100 Seconds](https://www.youtube.com/watch?v=zsjvFFKOm3c) — Fireship. Quick overview.
+- [SQL Tutorial](https://www.youtube.com/watch?v=HXV3zeQKqGY) — freeCodeCamp. Full beginner course.
+- [SQL Joins Explained](https://www.youtube.com/watch?v=9yeOJ0ZMUYw) — Web Dev Simplified. Visual join explanations.
+
+## Articles and Readings
+
+- [SQLBolt](https://sqlbolt.com) — Interactive SQL tutorials. Start here.
+- [PostgreSQL Tutorial](https://www.postgresqltutorial.com/) — PostgreSQL-specific guide.
+- [Use The Index, Luke](https://use-the-index-luke.com/) — SQL indexing deep dive.
+
+## Books
+
+- **SQL in 10 Minutes** by Ben Forta — Quick reference and practice.
+- **Learning SQL** by Alan Beaulieu — Comprehensive introduction.
+
+## Tools and Playgrounds
+
+- [SQL Fiddle](http://sqlfiddle.com) — Run SQL in the browser.
+- [DB Fiddle](https://www.db-fiddle.com/) — PostgreSQL, MySQL, SQLite.
+- [PostgreSQL](https://www.postgresql.org/) — Open-source relational database.
+
+## Podcasts
+
+- [Software Engineering Daily — Database Episodes](https://softwareengineeringdaily.com/category/all-episodes/exclusive-content/databases/) — Technical deep dives on SQL, PostgreSQL, indexing.
+- [Postgres.fm](https://postgres.fm/) — Weekly PostgreSQL podcast covering SQL performance, extensions, and best practices.
+
+## Interactive and Visual
+
+- [SQLBolt](https://sqlbolt.com/) — Step-by-step interactive SQL lessons in the browser.
+- [SQL Murder Mystery](https://mystery.knightlab.com/) — Solve a murder mystery using SQL queries — gamified learning.
+- [VisuAlgo — Databases](https://visualgo.net/) — Animated visualizations of B-trees, hashing, and indexing algorithms.
+- [Explain.dalibo.com](https://explain.dalibo.com/) — Visual PostgreSQL EXPLAIN ANALYZE visualizer — paste a plan and see it as a tree.
+
+## Courses
+
+- [Stanford — Databases (free)](https://online.stanford.edu/courses/soe-ydatabases0005-databases-relational-databases-and-sql) — Jennifer Widom's foundational SQL and relational database course.
+- [freeCodeCamp — SQL and Databases](https://www.freecodecamp.org/learn/relational-database/) — Free interactive curriculum with PostgreSQL projects.
+- [Mode Analytics — SQL Tutorial (free)](https://mode.com/sql-tutorial/) — Practical SQL for analysis with real datasets.

package/modules/sql-fundamentals/walkthrough.md

@@ -0,0 +1,92 @@
+# SQL Walkthrough — Learn by Doing
+
+## Step 1: Your First Query
+
+Assume a `users` table with `id`, `name`, `email`, `created_at`. Write a query to fetch all users.
+
+<!-- hint:terminal -->
+<!-- hint:code language="sql" highlight="1,2" -->
+
+**Embed:** https://www.db-fiddle.com/
+
+**Task:** Write `SELECT * FROM users`. Then write a query that returns only `name` and `email`.
+
+**Question:** When would you use `SELECT *` vs listing specific columns? What are the tradeoffs?
+
+**Checkpoint:** The user can write basic SELECT and understands column selection.
+
+---
+
+## Step 2: Filtering with WHERE
+
+<!-- hint:terminal -->
+
+**Task:** Write queries to:
+- Find users created after 2024-01-01
+- Find users whose email contains "@gmail.com"
+- Find users with a non-null phone number
+
+**Question:** What's the difference between `=` and `LIKE`? When would you use `IN` vs multiple `OR` conditions?
+
+**Checkpoint:** The user can use WHERE with various operators.
+
+---
+
+## Step 3: INNER JOIN
+
+Assume `orders` (id, user_id, amount) and `users` (id, name). Fetch all orders with the user's name.
+
+<!-- hint:diagram mermaid-type="flowchart" topic="INNER JOIN vs LEFT JOIN — matching rows only vs all left rows" -->
+
+**Task:** Write an INNER JOIN that returns `order_id`, `amount`, `user_name`.
+
+**Question:** What happens to orders that have a `user_id` pointing to a deleted user? Would they appear? What about users with no orders?
+
+**Checkpoint:** The user understands INNER JOIN returns only matching rows.
+
+---
+
+## Step 4: LEFT JOIN
+
+<!-- hint:code language="sql" highlight="1,5" -->
+
+**Task:** Write a query that lists **all** users and their order count (0 if none). Use LEFT JOIN and COUNT.
+
+**Question:** Why does a LEFT JOIN from users to orders give us users with zero orders, while INNER JOIN would not?
+
+**Checkpoint:** The user can use LEFT JOIN and understands NULL for non-matching right rows.
+
+---
+
+## Step 5: GROUP BY and Aggregation
+
+**Task:** Write queries to:
+- Count orders per user
+- Sum order amount per user
+- Find users whose total order amount exceeds 500 (use HAVING)
+
+**Question:** What's the difference between WHERE and HAVING? Can you use aggregate functions in WHERE?
+
+**Checkpoint:** The user understands GROUP BY and HAVING.
+
+---
+
+## Step 6: Subqueries
+
+**Task:** Find all users who have placed at least one order over 100. Use a subquery with IN.
+
+**Question:** Could you write this with a JOIN instead? When is a subquery clearer vs when is a JOIN better?
+
+**Checkpoint:** The user can write an IN subquery and compare it to JOINs.
+
+---
+
+## Step 7: Schema Design
+
+<!-- hint:celebrate -->
+
+**Task:** Design tables for a simple blog: authors, posts, comments. Identify primary keys and foreign keys. Sketch the relationships.
+
+**Question:** How do you decide when to normalize (split tables) vs denormalize (keep redundant data)? What problem does normalization solve?
+
+**Checkpoint:** The user can design a minimal normalized schema with PKs and FKs.

package/modules/sql-fundamentals/workshop.yaml

@@ -0,0 +1,109 @@
+# SQL Fundamentals — Interactive Workshop Scenarios
+# Uses SQLite. Setup creates DB files; student writes queries in queries.sql.
+
+scenarios:
+  - id: basic-select
+    title: "SELECT with WHERE"
+    difficulty: beginner
+    xp: 20
+    setup:
+      - "mkdir -p basic-select && cd basic-select"
+      - "sqlite3 workshop.db \"CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT, role TEXT); INSERT INTO users VALUES (1, 'Alice', 'alice@example.com', 'admin'); INSERT INTO users VALUES (2, 'Bob', 'bob@example.com', 'user'); INSERT INTO users VALUES (3, 'Carol', 'carol@example.com', 'user'); INSERT INTO users VALUES (4, 'Dave', 'dave@example.com', 'guest'); INSERT INTO users VALUES (5, 'Eve', 'eve@example.com', 'admin');\""
+    files:
+      - name: queries.sql
+        content: |
+          -- Write a SELECT query that returns users with role = 'admin'
+          -- Run with: sqlite3 workshop.db < queries.sql
+        language: sql
+        readonly: false
+    task: "Write a SELECT query that returns only users whose role is 'admin'. Run it with sqlite3 workshop.db < queries.sql. You should see Alice and Eve."
+    validations:
+      - label: "Query returns admin users"
+        check: output-contains
+        pattern: "Alice|Eve"
+    hints:
+      - "Use SELECT * FROM users WHERE role = 'admin';"
+      - "Remember the semicolon at the end of your query."
+      - "You can also SELECT specific columns: SELECT name, email FROM users WHERE role = 'admin';"
+    agent_prompts:
+      on_start: "You have five users. How would you pick only those with role 'admin'? What part of SQL filters rows?"
+
+  - id: joins
+    title: "JOIN Queries"
+    difficulty: beginner
+    xp: 25
+    setup:
+      - "mkdir -p joins && cd joins"
+      - "sqlite3 workshop.db \"CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT); CREATE TABLE orders (id INTEGER PRIMARY KEY, user_id INTEGER, product TEXT, amount REAL); INSERT INTO users VALUES (1, 'Alice'); INSERT INTO users VALUES (2, 'Bob'); INSERT INTO users VALUES (3, 'Carol'); INSERT INTO orders VALUES (1, 1, 'Widget', 29.99); INSERT INTO orders VALUES (2, 1, 'Gadget', 49.99); INSERT INTO orders VALUES (3, 2, 'Widget', 29.99); INSERT INTO orders VALUES (4, 3, 'Thing', 19.99);\""
+    files:
+      - name: queries.sql
+        content: |
+          -- Write a JOIN query to show each order with the customer's name
+          -- Run with: sqlite3 workshop.db < queries.sql
+        language: sql
+        readonly: false
+    task: "Write an INNER JOIN query that returns each order's id, product, amount, and the user's name. The orders table has user_id linking to users.id. Run with sqlite3 workshop.db < queries.sql."
+    validations:
+      - label: "JOIN returns order and user data"
+        check: output-contains
+        pattern: "Alice|Bob|Carol"
+    hints:
+      - "INNER JOIN connects rows from two tables: SELECT orders.id, orders.product, orders.amount, users.name FROM orders JOIN users ON orders.user_id = users.id;"
+      - "Alias tables for brevity: FROM orders o JOIN users u ON o.user_id = u.id"
+      - "You should see 4 rows — one per order, each with a customer name."
+    agent_prompts:
+      on_start: "Orders have user_id but not the user's name. How can you combine data from two tables in one query?"
+
+  - id: group-by
+    title: "GROUP BY and Aggregation"
+    difficulty: intermediate
+    xp: 30
+    setup:
+      - "mkdir -p group-by && cd group-by"
+      - "sqlite3 workshop.db \"CREATE TABLE sales (id INTEGER PRIMARY KEY, region TEXT, product TEXT, amount REAL); INSERT INTO sales VALUES (1, 'North', 'A', 100); INSERT INTO sales VALUES (2, 'North', 'A', 150); INSERT INTO sales VALUES (3, 'North', 'B', 80); INSERT INTO sales VALUES (4, 'South', 'A', 120); INSERT INTO sales VALUES (5, 'South', 'B', 90); INSERT INTO sales VALUES (6, 'South', 'B', 110);\""
+    files:
+      - name: queries.sql
+        content: |
+          -- Write a query that groups by region and product, sums amount,
+          -- and only includes groups where the sum is >= 200
+          -- Run with: sqlite3 workshop.db < queries.sql
+        language: sql
+        readonly: false
+    task: "Write a GROUP BY query that shows total sales amount per region and product. Add a HAVING clause to show only groups where the total is 200 or more. Run with sqlite3 workshop.db < queries.sql."
+    validations:
+      - label: "GROUP BY with HAVING returns aggregated results"
+        check: output-contains
+        pattern: "North|250|South"
+    hints:
+      - "GROUP BY region, product with SUM(amount)."
+      - "HAVING filters after aggregation: HAVING SUM(amount) >= 200"
+      - "North,A = 250; South,B = 200. Both should appear."
+    agent_prompts:
+      on_start: "You want totals per region and product. What does GROUP BY do? And when would you use HAVING instead of WHERE?"
+
+  - id: subqueries
+    title: "Correlated Subqueries"
+    difficulty: intermediate
+    xp: 35
+    setup:
+      - "mkdir -p subqueries && cd subqueries"
+      - "sqlite3 workshop.db \"CREATE TABLE categories (id INTEGER PRIMARY KEY, name TEXT); CREATE TABLE products (id INTEGER PRIMARY KEY, category_id INTEGER, name TEXT, price REAL); INSERT INTO categories VALUES (1, 'Electronics'); INSERT INTO categories VALUES (2, 'Books'); INSERT INTO products VALUES (1, 1, 'Laptop', 999); INSERT INTO products VALUES (2, 1, 'Phone', 599); INSERT INTO products VALUES (3, 2, 'SQL Book', 39); INSERT INTO products VALUES (4, 2, 'React Book', 49);\""
+    files:
+      - name: queries.sql
+        content: |
+          -- Write a correlated subquery to find products priced above
+          -- their category's average
+          -- Run with: sqlite3 workshop.db < queries.sql
+        language: sql
+        readonly: false
+    task: "Write a correlated subquery that returns products whose price is above the average price for their category. Electronics avg = 799; Books avg = 44. You should get Laptop (999) and React Book (49). Run with sqlite3 workshop.db < queries.sql."
+    validations:
+      - label: "Correlated subquery returns correct products"
+        check: output-contains
+        pattern: "Laptop|React"
+    hints:
+      - "A correlated subquery references the outer query: WHERE price > (SELECT AVG(price) FROM products p2 WHERE p2.category_id = products.category_id)"
+      - "The subquery runs once per row in the outer query."
+      - "Laptop (999) > 799; React Book (49) > 44. Both qualify."
+    agent_prompts:
+      on_start: "How would you find the average price per category? Now, how would you compare each product's price to that average?"

package/modules/stakeholder-communication/content.md

@@ -0,0 +1,186 @@
+# Stakeholder Communication — Status Updates That Actually Help
+
+<!-- hint:slides topic="Stakeholder communication: audience mapping, pyramid principle, RAG status, power-interest grid, and update templates" slides="5" -->
+
+## Know Your Audience
+
+Different stakeholders want different information:
+
+| Audience | Cares Most About |
+|----------|------------------|
+| **Executives** | Outcomes, timeline, risks, decisions needed |
+| **Engineers** | Technical blockers, dependencies, scope |
+| **Product** | Scope, priorities, trade-offs |
+| **Customers** | When, what's new, what's fixed |
+
+Tailor your update to who's reading. An exec doesn't need Jira ticket IDs; an engineer might. One update can have sections for different audiences, or you send different versions.
+
+## The Pyramid Principle
+
+**Lead with the conclusion.** Put the most important point first, then support it.
+
+**Weak:** "We ran tests. We found some issues. We're fixing them. We might slip by a week."
+
+**Strong:** "We're at risk of slipping the release by one week due to integration test failures. We've identified 3 blockers and are addressing them; next update in 48 hours."
+
+Executives and busy stakeholders skim. If they read only the first line, they should get the takeaway.
+
+## RAG Status (Red / Amber / Green)
+
+| Status | Meaning |
+|--------|---------|
+| **Green** | On track. No major issues. |
+| **Amber** | At risk. Issues exist; we're working on them. Needs attention. |
+| **Red** | Off track. Significant problem. Intervention may be needed. |
+
+Use RAG consistently. If everything is always green, you lose credibility. If everything is red, you create alarm fatigue. Amber is your workhorse—"we're managing it."
+
+## Effective Status Update Structure
+
+A good status update answers four questions:
+
+1. **What happened?** — Completed, shipped, decided.
+2. **What's next?** — Planned for this period.
+3. **Blockers** — What's in the way?
+4. **Risks** — What might go wrong? (and what we're doing about it)
+
+Template:
+
+```markdown
+## Status — [Project/Release] | [Date]
+**RAG:** [G/A/R]
+
+### What happened
+- [Completed item 1]
+- [Completed item 2]
+
+### What's next
+- [Planned item 1]
+- [Planned item 2]
+
+### Blockers
+- [Blocker + owner/ETA]
+
+### Risks
+- [Risk + mitigation]
+```
+
+## Communicating Bad News Early
+
+Bad news does not improve with age. Surface delays, risks, and problems as soon as you have reasonable certainty. Early = more options. Late = fewer options and damaged trust.
+
+**How to deliver bad news:**
+1. State the fact clearly: "We're slipping the launch by 2 weeks."
+2. Explain why: "Integration with the payment gateway took longer than estimated."
+3. What you're doing: "We've parallelized the remaining work and added a second developer."
+4. What you need: "We need a go/no-go on scope by Friday."
+
+Don't bury it. Don't wait for the "perfect" moment. Communicate early.
+
+## Managing Expectations
+
+- **Under-promise, over-deliver** — Better to surprise with early delivery than late.
+- **Set checkpoints** — "We'll know by Wednesday whether we're on track."
+- **Be explicit about assumptions** — "This assumes no further API changes from the vendor."
+- **Call out dependencies** — "We're blocked until Legal approves the contract."
+
+When stakeholders have clear expectations, they're less likely to be surprised or frustrated.
+
+## Stakeholder Mapping (Power / Interest Grid)
+
+```mermaid
+quadrantChart
+  title Stakeholder Power-Interest Grid
+  x-axis Low Interest --> High Interest
+  y-axis Low Power --> High Power
+  quadrant-1 Manage closely
+  quadrant-2 Keep informed
+  quadrant-3 Monitor
+  quadrant-4 Keep satisfied
+  "Executive Sponsor": [0.9, 0.9]
+  "Engineering Lead": [0.8, 0.7]
+  "End Users": [0.6, 0.3]
+  "Legal": [0.2, 0.5]
+```
+
+| | Low Interest | High Interest |
+|---|--------------|---------------|
+| **High Power** | Keep satisfied | Manage closely |
+| **Low Power** | Monitor | Keep informed |
+
+- **Manage closely** — Regular, rich updates. Involve in decisions.
+- **Keep informed** — Periodic updates. Don't overwhelm.
+- **Keep satisfied** — Don't annoy; ensure no unpleasant surprises.
+- **Monitor** — Light touch. Watch for changes.
+
+## Meeting Cadence
+
+| Stakeholder Type | Cadence | Format |
+|------------------|---------|--------|
+| Core team | Daily / every other day | Standup, Slack |
+| Product / Eng leads | Weekly | Written + sync |
+| Executives | Bi-weekly / monthly | Written (pyramid); optional 15-min call |
+| Customers | Milestone-based | Release notes, blog, email |
+
+Match cadence to need. More frequent = more overhead. Less frequent = more surprise risk.
+
+## Written vs Verbal
+
+| Written | Verbal |
+|---------|--------|
+| Asynchronous, scalable | Real-time, interactive |
+| Permanent record | Nuance, Q&A |
+| Good for: status, decisions, specs | Good for: alignment, sensitive topics, complex trade-offs |
+
+For status: **written first**. Follow up with a call for anything sensitive or contentious. Written updates create a paper trail and let people read when ready.
+
+## Avoiding Information Overload
+
+- **One page max** for exec summaries.
+- **Bullet points** over paragraphs.
+- **RAG + key points** — Let them drill down if interested.
+- **Link to details** — Don't put everything in the email.
+- **Consistent format** — Same structure every time so people know where to look.
+
+## Status Update Template (Full)
+
+```markdown
+# [Project] — Status | [Week of DATE]
+**RAG:** [G/A/R] | **Next milestone:** [Date]
+
+## TL;DR
+[One sentence: on track / at risk / off track + why]
+
+## Completed
+- [Item 1]
+- [Item 2]
+
+## In Progress
+- [Item + owner]
+- [Item + owner]
+
+## Next
+- [Item 1]
+- [Item 2]
+
+## Blockers
+- [Blocker] — Owner: [Name] — ETA: [Date]
+
+## Risks
+- [Risk] — Mitigation: [What we're doing]
+
+## Decisions needed
+- [Decision] — By: [Date]
+```
+
+## Communicating Delays
+
+When you need to announce a slip:
+
+1. **Lead with it** — "Release delayed by 2 weeks. New date: March 28."
+2. **Cause** — "Integration testing revealed issues we're fixing."
+3. **Impact** — "Q1 target unchanged; we're compressing the next phase."
+4. **Plan** — "Added QA capacity; daily standup with vendor."
+5. **Ask** — "Need approval to descope analytics from this release."
+
+Clear, direct, with a path forward.

package/modules/stakeholder-communication/exercises.md

@@ -0,0 +1,87 @@
+# Stakeholder Communication — Exercises
+
+## Exercise 1: Pyramid Principle Rewrite
+
+**Task:** Take this status: "We've been working on the integration. There were some issues. We're fixing them. We might be a week late." Rewrite it using the pyramid principle. Lead with the conclusion. Max 3 sentences.
+
+**Validation:**
+- [ ] First sentence is the takeaway (delay + cause or implication)
+- [ ] Supporting detail follows
+- [ ] Total ≤ 3 sentences
+- [ ] Reader gets the point from line 1
+
+**Hints:**
+1. Lead: "We're at risk of slipping by one week due to integration issues."
+2. Support: "We've identified and are addressing 3 blockers."
+3. Optional: "Next update in 48 hours."
+
+---
+
+## Exercise 2: RAG Assignment
+
+**Task:** Assign RAG to these: (A) On track, demo next week. (B) Key vendor delayed; we have a fallback. (C) Major bug in prod; fix in progress. (D) Scope increased 30%; no timeline change. For each, write one sentence you'd include in a status.
+
+**Validation:**
+- [ ] A = Green, B = Amber, C = Red or Amber, D = Amber or Red
+- [ ] Each has a status-appropriate sentence
+- [ ] No alarmist language for B; no understatement for C
+
+**Hints:**
+1. A: Green—"On track for demo next week."
+2. B: Amber—"Vendor delay; fallback plan in place; monitoring."
+3. C: Red or Amber—"Critical bug; fix deployed in 4h; root cause analysis underway."
+4. D: Amber—"Scope +30%; reviewing timeline and resources."
+
+---
+
+## Exercise 3: Stakeholder Map
+
+**Task:** For a "password reset" feature: list 4 stakeholders (e.g., Exec, Eng Lead, Support, Security). Plot on power/interest. For the highest-power, highest-interest one: what do they need in a status update?
+
+**Validation:**
+- [ ] 4 stakeholders named
+- [ ] Plotted on grid
+- [ ] "Manage closely" needs described
+- [ ] Needs are specific (not "they need updates")
+
+**Hints:**
+1. Exec: outcomes, timeline, risks, decisions
+2. Eng Lead: technical blockers, dependencies
+3. Support: when it ships, what changes for users
+4. Security: compliance, audit trail
+
+---
+
+## Exercise 4: Delay Communication
+
+**Task:** Your "Search v2" release is slipping 2 weeks. Cause: performance issues under load. Write a 5-sentence message to the Product VP. Include: delay, cause, impact, plan, ask.
+
+**Validation:**
+- [ ] Delay and new date stated up front
+- [ ] Cause is clear
+- [ ] Impact (what it means) stated
+- [ ] Plan (what you're doing) included
+- [ ] Ask or next step present
+
+**Hints:**
+1. "Search v2 delayed 2 weeks. New target: [date]."
+2. "Cause: performance issues under load in testing."
+3. "Impact: Q2 demo still feasible; later phases unchanged."
+4. "Plan: perf sprint this week; load tests in CI."
+5. "Ask: Confirm scope for v2 by Friday."
+
+---
+
+## Exercise 5: Two-Version Status
+
+**Task:** Write one status for a "Payment integration" project. Create (1) Exec summary: 4 bullets, pyramid. (2) Eng Lead version: same content + technical blockers, dependencies, and decisions needed.
+
+**Validation:**
+- [ ] Exec: ≤ 4 bullets, outcome-focused
+- [ ] Eng: includes technical detail
+- [ ] Both share the same RAG and core facts
+- [ ] Eng version is longer but still scannable
+
+**Hints:**
+1. Exec: RAG, TL;DR, key milestone, top risk
+2. Eng: + Stripe API version, test env blocker, auth handoff decision