@shaykec/bridge 0.4.25 → 0.4.26

package/modules/demo-test/walkthrough.md

@@ -0,0 +1,122 @@
+# Demo Test Walkthrough
+
+## Step 1: Terminal Practice
+
+<!-- hint:terminal -->
+
+**Task:** Create a file called `demo.txt` with the text "Socrates demo" inside it.
+
+**Question:** What command would you use to create a file with specific content from the terminal? Can you think of more than one way?
+
+**Checkpoint:** The user should demonstrate using echo with redirection or a heredoc. Accept any valid approach (echo, printf, cat, etc.).
+
+---
+
+## Step 2: Mermaid Diagram
+
+<!-- hint:diagram mermaid-type="flowchart" topic="Three tiers of Socrates: Full, Canvas, Terminal" -->
+
+**Task:** Look at the diagram showing Socrates's three tiers.
+
+**Question:** Why do you think the system is designed with three tiers instead of just one? What happens if the canvas is unavailable?
+
+**Checkpoint:** The user should understand progressive enhancement — terminal always works, canvas adds visuals, extension adds context awareness.
+
+---
+
+## Step 3: Smart Buttons
+
+<!-- hint:buttons type="single" options="Terminal,Canvas,Full" -->
+
+**Task:** Choose which tier you think is the most important for a teaching platform.
+
+**Question:** If you could only keep one tier, which would it be and why?
+
+**Checkpoint:** Any answer is valid as long as the user reasons about trade-offs. Terminal is the baseline; canvas adds engagement; full adds context.
+
+---
+
+## Step 4: Info Card
+
+<!-- hint:card type="concept" title="Socratic Method" -->
+
+**Task:** Read the concept card about the Socratic method.
+
+**Question:** How is asking questions different from giving direct answers when it comes to learning? Can you think of a time when a question helped you understand something better than an explanation would have?
+
+**Checkpoint:** The user should articulate that questions force active thinking and deeper understanding compared to passive reading.
+
+---
+
+## Step 5: Code Snippet
+
+<!-- hint:code language="javascript" highlight="2,3" -->
+
+**Task:** Look at this code snippet and identify what the highlighted lines do.
+
+**Question:** What pattern does this code follow? Why might the highlighted lines be important?
+
+**Checkpoint:** The user should be able to read highlighted code and explain its purpose.
+
+---
+
+## Step 6: Smart List
+
+<!-- hint:list style="cards" -->
+
+**Task:** Review the list of Socrates element types.
+
+**Question:** Which element type do you think is most effective for learning — quizzes, games, terminals, or diagrams? Why?
+
+**Checkpoint:** The user should reason about different learning styles and how each element serves a different purpose.
+
+---
+
+## Step 7: Step Tracker
+
+<!-- hint:steps -->
+<!-- hint:progress -->
+
+**Task:** Check your progress through this walkthrough.
+
+**Question:** You're past the halfway point. What have you learned so far about how Socrates structures a lesson?
+
+**Checkpoint:** The user should recognize the pattern: each step introduces a concept, asks a question, and validates understanding.
+
+---
+
+## Step 8: Web Embed
+
+<!-- hint:embed url="https://example.com" -->
+
+**Embed:** https://example.com
+
+**Task:** Observe how external content can be embedded directly in a lesson.
+
+**Question:** When would embedding an external resource be more useful than describing it in text? What are the trade-offs?
+
+**Checkpoint:** The user should mention interactivity, visual learning, and the risk of external content becoming unavailable.
+
+---
+
+## Step 9: Inline Quiz
+
+<!-- hint:quiz inline -->
+
+**Task:** Answer a quick inline quiz question.
+
+**Question:** What does XP stand for in Socrates's gamification system?
+
+**Checkpoint:** Experience Points. The user should understand XP drives belt progression.
+
+---
+
+## Step 10: Celebration
+
+<!-- hint:celebrate -->
+
+**Task:** You've completed the full walkthrough! Every element type has been exercised.
+
+**Question:** Looking back at all 10 steps, which teaching element felt most engaging to you? Which would you want more of in a real module?
+
+**Checkpoint:** Any thoughtful reflection is valid. This step tests the celebration/completion visual.

package/modules/demo-test/workshop.yaml

@@ -0,0 +1,31 @@
+scenarios:
+  - id: create-greeting
+    title: "Build a Greeting Script"
+    difficulty: beginner
+    xp: 20
+    setup: []
+    files:
+      - name: greet.sh
+        content: |
+          #!/bin/bash
+          # TODO: Accept a name argument and print a greeting
+          echo "Hello, World!"
+        language: bash
+        readonly: false
+    task: "Modify greet.sh to accept a name as the first argument ($1) and print 'Hello, <name>!' instead of 'Hello, World!'. If no argument is provided, default to 'World'."
+    validations:
+      - label: "Script accepts a name argument"
+        check: output-contains
+        pattern: "\\$1|\\${1}"
+      - label: "Default fallback to World"
+        check: output-contains
+        pattern: "World|:-|default"
+      - label: "Greeting printed correctly"
+        check: output-contains
+        pattern: "Hello,"
+    hints:
+      - "Use ${1:-World} to provide a default value when no argument is given."
+      - "The full line: echo \"Hello, ${1:-World}!\""
+    agent_prompts:
+      on_start: "What does the :- syntax do in bash parameter expansion? Why is a default value useful?"
+      on_complete: "How would you extend this to accept both a first name and last name? What about validating the input?"

package/modules/design-critique/content.md

@@ -0,0 +1,93 @@
+# Design Critique — Structured Feedback That Improves Work
+
+<!-- hint:slides topic="Design critique: critique vs criticism, Liz Lerman Critical Response Process, I Like/I Wish/What If, and facilitation tips" slides="4" -->
+
+## Why Critique Matters
+
+Design critique is a collaborative process for evaluating design work and generating actionable feedback. Done well, it improves outcomes, builds shared understanding, and creates a culture where feedback is valued. Done poorly, it demoralizes designers and produces watered-down "design by committee" results.
+
+## Critique vs Criticism
+
+| Critique | Criticism |
+|----------|-----------|
+| Goal-oriented: improve the work | Emotion-driven: express opinion |
+| Specific, tied to principles | Vague ("I don't like it") |
+| Offers alternatives | Only identifies problems |
+| Separates person from work | Often feels personal |
+| Invites dialogue | Shuts down conversation |
+
+**Key insight:** Criticism judges; critique analyzes and helps the designer think through solutions.
+
+## Liz Lerman's Critical Response Process
+
+Liz Lerman's Critical Response Process (CRP) provides four clear steps for structured feedback:
+
+1. **Statements of meaning** — What resonates? What stands out? (No opinions yet.)
+2. **Artist as questioner** — The designer asks their own questions about the work.
+3. **Neutral questions** — Audience asks questions that begin with curiosity, not opinion.
+4. **Permissioned opinions** — Only after permission, specific suggestions may be offered.
+
+```mermaid
+flowchart TD
+    A[Work Presented] --> B[Statements of Meaning]
+    B --> C[Artist As Questioner]
+    C --> D[Neutral Questions]
+    D --> E{Permission Given?}
+    E -->|Yes| F[Opinions / Suggestions]
+    E -->|No| G[End Session]
+    F --> G
+```
+
+## Structured Feedback Frameworks
+
+### I Like / I Wish / What If
+
+A simple framework to balance positivity with constructive suggestions:
+
+- **I like...** — What works well (anchors feedback in strengths).
+- **I wish...** — A specific improvement, phrased as desire not complaint.
+- **What if...** — Open-ended alternatives that spark new ideas.
+
+**Example:** "I like how the primary CTA stands out. I wish the secondary actions had clearer hierarchy. What if we grouped related actions under a menu?"
+
+### Rose / Thorn / Bud
+
+- **Rose** — Something that's working well.
+- **Thorn** — A problem or concern.
+- **Bud** — Potential or opportunity not yet realized.
+
+## Running Effective Critique Sessions
+
+1. **Set the stage** — Clarify the goal (e.g., "We're deciding whether this flow solves the checkout problem").
+2. **Define constraints** — What's on/off the table? Scope the feedback.
+3. **Establish rules** — No "I don't like" without reasoning; reference principles (e.g., WCAG, user research).
+4. **Time-box** — 15–30 minutes per artifact keeps focus.
+5. **Document** — Capture decisions and action items. What will change?
+
+## Giving Feedback
+
+- **Be specific** — "The contrast ratio fails WCAG AA" > "It's hard to read."
+- **Reference principles** — Cite usability heuristics, accessibility standards, or user research.
+- **Suggest alternatives** — Don't just say "change this"; offer a direction.
+- **Separate person from work** — Critique the design, not the designer.
+
+## Receiving Feedback
+
+- **Listen first** — Don't defend or explain during feedback. Take notes.
+- **Clarify** — Ask neutral questions: "What specifically feels unclear?"
+- **Thank** — Acknowledge the intent to help, even when you disagree.
+- **Decide later** — You don't have to accept every suggestion; decide after reflection.
+
+## Common Anti-Patterns
+
+| Anti-pattern | Why it fails |
+|--------------|--------------|
+| **Subjective opinions without reasoning** | "I don't like blue" gives no actionable direction. |
+| **Design by committee** | Everyone's opinion gets equal weight; the design loses coherence. |
+| **Feedback too late** | Critique after implementation is costly; critique early and often. |
+| **Missing context** | Feedback without knowing goals, users, or constraints is useless. |
+| **HiPPO (Highest Paid Person's Opinion)** | One voice overrides evidence and process. |
+
+## Summary
+
+Design critique is a skill. Use structured processes (CRP, I Like/I Wish/What If) to ensure feedback is specific, principle-based, and constructive. Run focused sessions, give permission for opinions, and document outcomes. The goal is better work, not consensus for its own sake.

package/modules/design-critique/exercises.md

@@ -0,0 +1,71 @@
+# Design Critique Exercises
+
+## Exercise 1: Convert Criticism to Critique
+
+**Task:** Take these criticism statements and rewrite them as critique. Make them specific, principle-based, and include at least one alternative.
+
+- "I don't like the layout."
+- "The colors are wrong."
+- "This is confusing."
+
+**Validation:**
+- [ ] Each rewrite references a principle (e.g., usability, accessibility, hierarchy)
+- [ ] Each rewrite is specific about what feels wrong and why
+- [ ] Each rewrite suggests at least one alternative direction
+
+**Hints:**
+1. "Layout" → Which element? Alignment? Hierarchy? White space?
+2. "Colors" → Contrast? Brand? Accessibility?
+3. "Confusing" → Which step? What's the user trying to do?
+
+---
+
+## Exercise 2: Facilitate a CRP Session
+
+**Task:** Facilitate a 15-minute Critical Response Process session with 2–3 colleagues. Use a real design artifact (screen, flow, or component). Document the output.
+
+**Validation:**
+- [ ] All four CRP steps were completed in order
+- [ ] "Statements of meaning" contained no opinions or suggestions
+- [ ] "Permissioned opinions" were only given after explicit permission
+- [ ] At least 2–3 actionable next steps were documented
+
+**Hints:**
+1. Print or share the CRP steps so everyone can see them
+2. If someone gives an opinion early, gently redirect: "Let's save opinions for step 4"
+3. Capture notes in a shared doc for the designer
+
+---
+
+## Exercise 3: Spot the Anti-Patterns
+
+**Task:** Read this feedback transcript and identify at least three anti-patterns (subjective opinion without reasoning, design by committee, missing context, HiPPO, etc.). Rewrite one piece of feedback to be constructive.
+
+**Sample transcript:**
+> "I think we should make the button bigger." / "Actually, I liked the smaller one." / "The CEO said she wants it blue." / "Let's just try both and see."
+
+**Validation:**
+- [ ] At least three anti-patterns identified with labels
+- [ ] One piece of feedback rewritten to reference principles and suggest alternatives
+- [ ] The rewrite would help the designer take action
+
+**Hints:**
+1. "I think" + no reasoning = subjective opinion
+2. "The CEO said" without evidence = HiPPO
+3. "Try both" without criteria = design by committee
+
+---
+
+## Exercise 4: Give Principle-Based Feedback
+
+**Task:** Choose a design (from a portfolio, Dribbble, or a real project). Write three pieces of feedback that each reference a specific principle: one usability heuristic (Nielsen), one accessibility guideline (WCAG), and one visual design principle (e.g., hierarchy, contrast).
+
+**Validation:**
+- [ ] Each feedback cites a named principle or guideline
+- [ ] Each feedback is specific to an element or pattern in the design
+- [ ] Each feedback suggests what would improve compliance or effectiveness
+
+**Hints:**
+1. Nielsen's heuristics: visibility, match real world, user control, consistency, error prevention, recognition over recall, flexibility, aesthetic design, error recovery, help
+2. WCAG: contrast ratios, focus order, alt text, keyboard access
+3. Visual: F-pattern, hierarchy, proximity, alignment

package/modules/design-critique/module.yaml

@@ -0,0 +1,41 @@
+slug: design-critique
+title: "Design Critique -- Structured Feedback That Improves Work"
+version: 1.0.0
+description: "Learn to give and receive design feedback that actually improves outcomes."
+category: ux-design
+tags: [design-critique, feedback, ux-design, collaboration, design-process]
+difficulty: beginner
+
+xp:
+  read: 10
+  walkthrough: 30
+  exercise: 20
+  quiz: 15
+  quiz-perfect-bonus: 10
+
+time:
+  quick: 5
+  read: 15
+  guided: 40
+
+prerequisites: []
+related: [code-review, user-story-mapping]
+
+triggers:
+  - "How do I give design feedback?"
+  - "How do I run a design critique?"
+  - "What's the difference between critique and criticism?"
+  - "How do I improve my design review process?"
+
+visuals:
+  diagrams: [diagram-flow, diagram-mermaid]
+  quiz-types: [quiz-drag-order, quiz-timed-choice]
+  slides: true
+
+sources:
+  - url: "https://www.nngroup.com"
+    label: "Nielsen Norman Group"
+    type: docs
+  - url: "https://www.oreilly.com/library/view/discussing-design/9781491902398/"
+    label: "Discussing Design by Adam Connor"
+    type: book

package/modules/design-critique/quick-ref.md

@@ -0,0 +1,63 @@
+# Design Critique Quick Reference
+
+## Critique vs Criticism
+
+| Critique | Criticism |
+|----------|-----------|
+| Specific | Vague |
+| Principle-based | Opinion-based |
+| Suggests alternatives | Only identifies problems |
+| Separates person from work | Feels personal |
+
+## Liz Lerman's Critical Response Process (CRP)
+
+| Step | What Happens |
+|------|--------------|
+| 1. Statements of meaning | What resonates? (No opinions.) |
+| 2. Artist as questioner | Designer asks their own questions |
+| 3. Neutral questions | Audience asks curious, non-opinion questions |
+| 4. Permissioned opinions | Suggestions only after artist invites them |
+
+## I Like / I Wish / What If
+
+| Phrase | Purpose |
+|--------|---------|
+| **I like...** | Anchor in strengths |
+| **I wish...** | Frame improvement as desire |
+| **What if...** | Open-ended alternatives |
+
+## Giving Feedback
+
+| Do | Don't |
+|----|-------|
+| Be specific | Say "I don't like it" without reasoning |
+| Reference principles (WCAG, heuristics) | Give opinions without evidence |
+| Suggest alternatives | Only identify problems |
+| Separate person from work | Make it personal |
+
+## Receiving Feedback
+
+| Do | Don't |
+|----|-------|
+| Listen and take notes | Defend during feedback |
+| Ask clarifying questions | Accept everything blindly |
+| Thank participants | Dismiss or argue |
+| Decide later what to act on | Commit to changes in the moment |
+
+## Common Anti-Patterns
+
+| Anti-pattern | Fix |
+|--------------|-----|
+| Subjective opinion without reasoning | Require principle or evidence |
+| Design by committee | Prioritize against goals and users |
+| Feedback too late | Critique early and often |
+| Missing context | Set goal and constraints upfront |
+| HiPPO overrides | Use process; cite evidence |
+
+## Critique Session Checklist
+
+- [ ] Set goal and constraints
+- [ ] Choose framework (CRP or I Like/I Wish/What If)
+- [ ] Time-box (15–30 min per artifact)
+- [ ] Document action items
+- [ ] Assign next steps

package/modules/design-critique/quiz.md

@@ -0,0 +1,73 @@
+# Design Critique Quiz
+
+## Question 1
+
+What is the main difference between critique and criticism?
+
+A) Critique is shorter; criticism is longer
+B) Critique aims to improve the work with specific, principle-based feedback; criticism is often opinion without direction
+C) Critique is given in person; criticism is written
+D) Critique is for design; criticism is for code
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Critique is goal-oriented and analyzes work to help the designer improve. It references principles, offers alternatives, and separates person from work. Criticism tends to be vague, emotional, and judgmental without actionable direction. -->
+
+## Question 2
+
+In Liz Lerman's Critical Response Process, when may participants offer opinions or suggestions?
+
+A) At any time during the session
+B) Only after the artist grants permission
+C) Only during "Statements of meaning"
+D) Only if the facilitator approves
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: The fourth step of CRP is "Permissioned opinions." Participants may only offer opinions or suggestions after the artist explicitly invites them. This creates psychological safety and ensures feedback is welcomed, not imposed. -->
+
+## Question 3
+
+Which feedback is the best example of critique?
+
+A) "I don't like the blue. Change it."
+B) "The primary CTA contrast is 3:1, which fails WCAG AA (4.5:1). Consider darkening the background or lightening the text."
+C) "It looks bad."
+D) "My boss said to make it bigger."
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Good critique is specific (which element, what metric), references principles (WCAG), and suggests alternatives. Options A, C, and D are vague, subjective, or authority-based without reasoning. -->
+
+## Question 4
+
+What does "I Wish" in the I Like / I Wish / What If framework accomplish?
+
+A) It expresses negative feelings about the design
+B) It frames a desired improvement as a wish, which feels less accusatory and more constructive
+C) It allows the designer to ignore feedback
+D) It replaces the need for "What If"
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: "I wish" reframes criticism as desire. Instead of "This is wrong," you say "I wish the hierarchy were clearer." This reduces defensiveness and keeps the focus on improvement rather than blame. -->
+
+## Question 5
+
+Which is a common anti-pattern in design critique?
+
+A) Giving feedback early in the process
+B) Design by committee—everyone's opinion gets equal weight, producing incoherent results
+C) Documenting action items after the session
+D) Using a structured framework like CRP
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Design by committee occurs when all feedback is treated equally without prioritization against goals, users, or evidence. The design loses coherence. Early feedback (A), documenting actions (C), and using frameworks (D) are good practices. -->
+
+## Question 6
+
+When receiving feedback, what should the designer do during the feedback phase?
+
+A) Defend each point as it's raised
+B) Listen, take notes, ask clarifying questions—and decide what to act on later
+C) Accept every suggestion immediately
+D) End the session if feedback is too critical
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Defending in real-time shuts down dialogue and makes people hesitant to share. The designer should listen first, clarify with neutral questions, thank participants, and decide later which feedback to incorporate. Not all feedback needs to be accepted. -->

package/modules/design-critique/resources.md

@@ -0,0 +1,27 @@
+# Design Critique — Resources
+
+## Videos
+
+- [Liz Lerman's Critical Response Process](https://www.youtube.com/watch?v=ZQtZq19_OtM) — Introduction to CRP for creative feedback.
+
+## Articles and Readings
+
+- [Design Critiques: Encourage a Positive Culture](https://www.nngroup.com/articles/design-critiques/) — Nielsen Norman Group. Step-by-step guide to effective critique sessions.
+- [Derailed Design Critiques: Tactics for Getting Back on Track](https://www.nngroup.com/articles/derailed-design-critiques/) — Nielsen Norman Group. How to handle common pitfalls.
+- [I Like, I Wish, I Wonder](https://www.designkit.org/methods/i-like-i-wish-i-wonder) — IDEO Design Kit. The "I wonder" variant of the framework.
+- [Giving and Receiving Design Feedback](https://alistapart.com/article/giving-and-receiving-design-feedback/) — A List Apart. Practical tips for both roles.
+
+## Books
+
+- **Discussing Design** by Adam Connor and Aaron Irizarry — Definitive guide to design critique: frameworks, facilitation, and building a culture of feedback. O'Reilly.
+
+## Tools
+
+- [Miro](https://miro.com) — Collaborative boards for running remote critique sessions with sticky notes and diagrams.
+- [Figma Comments](https://www.figma.com) — In-context feedback on design files; use with structured templates (I Like / I Wish / What If) for consistency.
+- [Notion](https://www.notion.so) — Document critique outcomes, action items, and decisions for future reference.
+
+## Workshops and Templates
+
+- [Critical Response Process Handout](https://lizlerman.com/critical-response-process/) — Liz Lerman's official CRP description and facilitation notes.
+- [Design Critique Worksheet](https://www.nngroup.com/articles/ux-workshop/) — Template for structuring critique sessions with goals and documentation.

package/modules/design-critique/walkthrough.md

@@ -0,0 +1,68 @@
+# Design Critique Walkthrough — Learn by Doing
+
+## Before We Begin
+
+Critique is not criticism: criticism judges without direction; critique analyzes against principles and suggests alternatives. The goal is to improve the work while respecting the designer.
+
+**Diagnostic question:** When someone has given you feedback on a design (or any creative work), what made it feel constructive? What made it feel dismissive or vague?
+
+**Checkpoint:** You can distinguish one characteristic of critique (specific, principle-based, suggests alternatives) from criticism (vague, opinion-only).
+
+---
+
+## Step 1: Distinguish Critique from Criticism
+
+Before giving feedback, you need to recognize the difference.
+
+<!-- hint:buttons type="single" prompt="Which feedback type is more useful?" options="Vague opinion,Specific with alternatives" -->
+
+**Task:** Look at a design artifact (wireframe, mockup, or flow). Write two pieces of feedback: one that is criticism (vague, opinion-based) and one that is critique (specific, principle-based, with alternatives).
+
+**Question:** What makes your "critique" version more useful than the "criticism" version? How would the designer know what to change?
+
+**Checkpoint:** The user can articulate that critique includes specificity, references to principles, and suggests alternatives—while criticism is opinion without direction.
+
+---
+
+## Step 2: Apply I Like / I Wish / What If
+
+<!-- hint:card type="concept" title="I Like / I Wish / What If: affirm, improve, imagine" -->
+<!-- hint:list style="numbered" -->
+
+**Task:** Run a mini critique on a design (yours or a peer's) using only the I Like / I Wish / What If framework. Write at least one response in each category.
+
+**Question:** Did "I wish" force you to be more constructive than a raw complaint? Why does "What if" open possibilities instead of shutting them down?
+
+**Checkpoint:** The user produces feedback in all three categories and can explain how the framework shapes their language.
+
+---
+
+## Step 3: Practice Liz Lerman's Critical Response Process
+
+<!-- hint:list style="numbered" -->
+
+**Task:** Run a 10-minute critique session using CRP. Choose one person as the "artist" (designer) and one as facilitator. Go through: (1) Statements of meaning, (2) Artist as questioner, (3) Neutral questions, (4) Permissioned opinions.
+
+**Question:** What was different about giving feedback only after "permission" was granted? Did it change how you phrased your opinions?
+
+**Checkpoint:** The user completes all four steps and notices that permission creates psychological safety and more thoughtful suggestions.
+
+---
+
+## Step 4: Run a Design Critique on a Wireframe
+
+**Task:** Conduct a 15-minute design critique on a real wireframe or prototype. Set the goal and constraints upfront. Use either I Like/I Wish/What If or CRP. Document at least three actionable next steps.
+
+**Question:** At the end, can you list what specifically will change? If not, what was missing from the feedback?
+
+**Checkpoint:** The session produces documented action items that are specific enough to implement.
+
+---
+
+## Step 5: Receive Feedback Without Defending
+
+**Task:** Present your own design work to a partner and receive feedback. Your job: listen, take notes, ask clarifying questions. Do not defend or explain during the feedback phase.
+
+**Question:** How did it feel to only listen? What would have happened if you had defended each point as it came up?
+
+**Checkpoint:** The user completes the exercise without defending and can reflect on how listening changes the quality of feedback received.