# User Stories: nw-workshopper Agent

## Epic: AI-Assisted Workshop Design

The nw-workshopper agent helps IT trainers, engineering managers, agile coaches, and developer advocates design complete, facilitator-ready learning experiences using Train from the Back of the Room (TBR), Bloom's taxonomy, gamification design, and Miro board architecture.

---

## US-WS-001: Workshop Context Discovery

### Problem
Marco Benedetti is a freelance IT trainer who delivers 3-4 workshops per month. He finds it overwhelming to start designing a new workshop from scratch -- he has a topic ("Kubernetes Networking"), a date, and an audience, but no structured process to translate that into a learning experience. His current workaround is copying last quarter's slide deck and tweaking it, which produces lecture-heavy sessions with low engagement.

### Who
- IT Trainer | Booked for a workshop on a technical topic | Wants to transform a vague topic idea into a structured design starting point

### Solution
The agent conducts a structured discovery conversation to capture workshop context: topic, audience proficiency, group size, time slot, format (online/hybrid/in-person), and existing materials. The agent asks the right questions in the right order so the trainer feels guided, not interrogated.

### Domain Examples

#### 1: Happy Path -- Marco designs a new online workshop
Marco invokes `*workshop "Kubernetes Networking"` and the agent asks about his audience (16 mid-level DevOps engineers), time (90 minutes), format (online via Zoom + Miro), and existing materials (a 40-slide deck from a previous conference talk). The agent captures all context and confirms it back to Marco before proceeding.

#### 2: Edge Case -- Sofia has no existing materials
Sofia Rinaldi invokes `*workshop "TDD for Our Java Codebase"` for her team of 12 developers. She has domain expertise but no slides, no exercises, nothing written down. The agent acknowledges the blank-slate starting point and proceeds to learning outcomes without requiring existing materials, noting that all content will be generated fresh.

#### 3: Error/Boundary -- Insufficient information
Kenji Takahashi invokes `*workshop "Retrospective Facilitation"` but only provides the topic. The agent asks follow-up questions for audience, group size, time, and format. If Kenji says "I do not know the group size yet," the agent proceeds with a reasonable default (8-12 participants) and flags it as an assumption to revisit.

### UAT Scenarios (BDD)

#### Scenario: Complete context captured
```gherkin
Given Marco invokes *workshop "Kubernetes Networking"
When the agent asks about audience, group size, time slot, and format
And Marco provides "16 mid-level DevOps engineers, 90 minutes, online via Zoom + Miro, existing 40-slide deck"
Then the agent creates a workshop context object with all fields populated
And confirms the context back to Marco for validation
And no field is left as "unknown" or empty
```

#### Scenario: Missing information handled gracefully
```gherkin
Given Kenji invokes *workshop "Retrospective Facilitation"
When the agent asks about group size
And Kenji responds "I do not know yet"
Then the agent suggests a default range (8-12 participants)
And flags the assumption explicitly
And proceeds to learning outcomes without blocking
```

#### Scenario: Existing materials acknowledged
```gherkin
Given Marco mentions he has "a 40-slide deck from a previous conference talk"
When the agent captures workshop context
Then the agent notes existing materials as a content source
And later references them during activity design (Step 4)
And suggests which slides can be repurposed as reference material vs. replaced by activities
```

### Acceptance Criteria
- [ ] Agent asks structured discovery questions covering: topic, audience, proficiency, group size, duration, format, existing materials
- [ ] Context confirmation displayed before proceeding to next step
- [ ] Missing information handled with sensible defaults and explicit assumption flags
- [ ] Context object consistently referenced by all subsequent steps

### Technical Notes
- Workshop context is the shared artifact referenced by all subsequent steps; changes must propagate
- Agent must support both greenfield (no materials) and enhancement (existing materials) starting points
- Format detection (online/hybrid/in-person) drives downstream decisions (Miro board relevance, activity types)

### Dependencies
- None (entry point)

### Traces To
- JS-1: Workshop Structure Design
- Outcome 1.1: Minimize the time to translate a vague topic idea into specific learning outcomes

---

## US-WS-002: Learning Outcome Generation

### Problem
Marco Benedetti is an IT trainer who knows his technical domain (Kubernetes Networking) deeply but struggles to articulate specific, measurable learning outcomes at the right difficulty level. His current workaround is writing vague objectives like "understand Kubernetes networking" that do not guide activity design and cannot be assessed. Sofia Rinaldi faces this worse -- as a non-trainer, she has never written a learning outcome in her life.

### Who
- IT Trainer | Has domain expertise and workshop context defined | Wants learning outcomes at the right Bloom's level for the audience and time available

### Solution
The agent generates 3-5 learning outcomes mapped to Bloom's taxonomy levels, calibrated to the audience proficiency level and time constraints. The agent explains the Bloom's calibration ("90 minutes supports Remember through Analyze; Evaluate/Create would need a half-day") so the trainer understands the reasoning.

### Domain Examples

#### 1: Happy Path -- Calibrated outcomes for 90-minute workshop
For Marco's "Kubernetes Networking" workshop (16 mid-level DevOps engineers, 90 minutes), the agent generates:
- LO-1 [Remember]: Identify the 4 core K8s networking components (Pod network, Service, Ingress, NetworkPolicy)
- LO-2 [Understand]: Explain how Pod-to-Pod communication works across nodes using CNI plugins
- LO-3 [Apply]: Troubleshoot a broken Service-to-Pod routing scenario using kubectl
- LO-4 [Analyze]: Compare CNI plugin approaches (Calico vs Cilium) for given network requirements

#### 2: Edge Case -- Full-day workshop enables higher Bloom's levels
For Aisha Okonkwo's full-day "Cloud-Native Security" workshop (30 developer advocates, 6 hours), the agent generates outcomes reaching Evaluate and Create levels:
- LO-5 [Evaluate]: Assess the security posture of a sample Kubernetes deployment against CIS benchmarks
- LO-6 [Create]: Design a network policy set for a multi-tier application

#### 3: Error/Boundary -- Too many outcomes for time slot
Marco asks for 8 learning outcomes in a 45-minute conference session. The agent explains that 45 minutes realistically supports 2-3 outcomes at Remember-Understand level, and suggests either reducing outcomes or extending time.

### UAT Scenarios (BDD)

#### Scenario: Bloom's-calibrated outcomes for 90 minutes
```gherkin
Given a workshop context for "Kubernetes Networking" with mid-level DevOps engineers and 90 minutes
When the agent generates learning outcomes
Then 3-5 outcomes are produced
And each outcome has a Bloom's taxonomy level assigned
And the highest level is Analyze (appropriate for 90 minutes with mid-level audience)
And the agent explains the time-level calibration reasoning
```

#### Scenario: Outcomes adjustable by user
```gherkin
Given the agent has generated 4 learning outcomes for Marco's workshop
When Marco says "I want to add an outcome about NetworkPolicy syntax"
Then the agent integrates the new outcome at the appropriate Bloom's level
And re-validates that total outcomes remain feasible within 90 minutes
And flags if the addition requires dropping another outcome or extending time
```

#### Scenario: Outcome count exceeds time feasibility
```gherkin
Given Marco requests 8 learning outcomes for a 45-minute session
When the agent evaluates feasibility
Then the agent explains the time-outcome constraint (45 min supports 2-3 outcomes)
And suggests either reducing to 2-3 outcomes or extending the session
And does not proceed with an infeasible design
```

### Acceptance Criteria
- [ ] Outcomes mapped to Bloom's taxonomy with level explicitly stated
- [ ] Number of outcomes calibrated to session duration (not exceeding feasibility)
- [ ] Bloom's level calibrated to audience proficiency
- [ ] User can adjust outcomes before proceeding
- [ ] Time-level calibration reasoning explained to user

### Technical Notes
- Bloom's levels: Remember, Understand, Apply, Analyze, Evaluate, Create
- Rough time heuristics: 45 min = 2-3 at Remember-Understand; 90 min = 3-5 up to Analyze; half-day = 4-6 up to Evaluate; full-day = 5-8 up to Create
- Learning outcomes are shared artifacts consumed by Steps 3-7

### Dependencies
- US-WS-001 (workshop context must be defined)

### Traces To
- JS-1: Workshop Structure Design
- Outcome 1.1, 1.2: Learning outcome clarity and Bloom's calibration

---

## US-WS-003: 4C Workshop Structure

### Problem
Marco Benedetti is an IT trainer who knows about Train from the Back of the Room but finds it difficult to apply the 4C framework (Connections, Concepts, Concrete Practice, Conclusions) consistently. He finds it time-consuming to allocate time across phases and ensure the Concrete Practice phase gets the majority of time (TBR principle). His current workaround is a loosely structured agenda that always drifts toward lecture.

### Who
- IT Trainer | Has learning outcomes defined | Wants a complete 4C structure with time allocations that follow TBR principles

### Solution
The agent generates a complete 4C flow with time allocations, phase descriptions, and activity slots per phase. The agent ensures Concrete Practice receives the largest time allocation and facilitator talk time stays under 20%.

### Domain Examples

#### 1: Happy Path -- 90-minute 4C structure
For Marco's 90-minute workshop, the agent produces:
- Connections (15 min): "What do you already know?" -- activate prior knowledge
- Concepts (20 min): "New information, learner-centered" -- discover, not lectured
- Concrete Practice (40 min): "Apply, make mistakes, learn" -- hands-on activities
- Conclusions (15 min): "What did you learn? What will you do differently?" -- synthesize and commit
- Facilitator talk time: ~14 min / 90 min = 15.5% (under 20% threshold)

#### 2: Edge Case -- 45-minute conference slot
For Aisha's 45-minute conference workshop, the agent adjusts:
- Connections (5 min): Quick pair-share, no elaborate activity
- Concepts (10 min): Single focused concept, learner-driven
- Concrete Practice (22 min): One substantial hands-on activity
- Conclusions (8 min): Quick teach-back and action commitment
- No break (under 60 minutes)

#### 3: Error/Boundary -- User wants 50% lecture time
Sofia Rinaldi asks the agent to allocate 50% of time to her presenting content. The agent explains the TBR principle (facilitator talks < 20%), suggests learner-centered alternatives for content delivery (jigsaw, card sort, guided discovery), and offers a compromise if Sofia insists (showing the engagement risk).

### UAT Scenarios (BDD)

#### Scenario: 4C structure with TBR-compliant time allocation
```gherkin
Given learning outcomes LO-1 through LO-4 for a 90-minute online workshop
When the agent generates the 4C structure
Then four phases are created: Connections, Concepts, Concrete Practice, Conclusions
And phase durations sum to 90 minutes (including any breaks)
And Concrete Practice receives the largest time allocation (at least 35% of total)
And estimated facilitator talk time is under 20%
```

#### Scenario: Short session adaptation
```gherkin
Given a workshop context for a 45-minute conference slot
When the agent generates the 4C structure
Then all four phases are present (none omitted)
And each phase is compressed appropriately
And no break is included (session under 60 minutes)
And Concrete Practice still receives the largest allocation
```

#### Scenario: User requests excessive lecture time
```gherkin
Given Sofia requests 50% facilitator presentation time
When the agent generates the 4C structure
Then the agent explains the TBR principle and engagement research
And suggests learner-centered alternatives for content delivery
And shows the projected engagement difference (lecture vs. active learning)
And allows Sofia to override with an explicit acknowledgment of the trade-off
```

### Acceptance Criteria
- [ ] All four 4C phases present in every workshop design
- [ ] Concrete Practice receives the largest time allocation
- [ ] Facilitator talk time estimated and reported (target: under 20%)
- [ ] Break included for sessions over 60 minutes
- [ ] Phase durations sum to total session time

### Technical Notes
- The 4C structure is TBR's core framework (Sharon Bowman): Connections, Concepts, Concrete Practice, Conclusions
- Facilitator talk time = sum of all segments where the facilitator is speaking to the whole group
- The 20% threshold is a TBR guideline, not an absolute rule -- but exceeding it should require explicit user acknowledgment

### Dependencies
- US-WS-002 (learning outcomes must be defined)

### Traces To
- JS-1: Workshop Structure Design
- Outcome 3.1: Minimize time to structure content into 4C flow
- Outcome 5.1: Facilitator talk time under 20%

---

## US-WS-004: Domain-Specific Activity Design

### Problem
Marco Benedetti is an IT trainer who faces the "blank page problem" -- staring at a learning outcome like "Participants can troubleshoot broken Service-to-Pod routing" and having no idea how to turn that into an engaging 20-minute activity. He finds it creatively exhausting to invent activities that are both technically accurate and pedagogically sound. His current workaround is recycling the same 5 activity formats (quiz, pair programming, group discussion, demo, Q&A) for every workshop, which participants notice.

### Who
- IT Trainer | Has 4C structure with activity slots | Wants creative, domain-specific activities designed for each learning outcome

### Solution
The agent designs detailed activity cards for each slot in the 4C structure. Each card includes setup instructions, participant instructions, facilitation tips, timing with compress/extend options, group size requirements, a Plan B contingency, and an assessment checkpoint. Activities use real domain content, not generic placeholders.

### Domain Examples

#### 1: Happy Path -- Troubleshooting Lab activity card
For Marco's LO-3 [Apply], the agent designs a "Troubleshooting Lab":
- Pairs receive a pre-configured K8s cluster with a broken networking scenario
- 4 different scenarios distributed across 8 pairs (2 pairs per scenario)
- Diagnose, document, fix, verify sequence
- Debrief with one pair per scenario sharing their approach
- Plan B: Switch to guided walkthrough if pairs are stuck
- Assessment: Can pairs articulate root cause, not just the fix?

#### 2: Edge Case -- Activity for non-technical audience
For Sofia's "TDD for Our Java Codebase" workshop, the agent designs activities appropriate for developers who are TDD skeptics:
- "Red-Green Refactor Relay" -- pairs race to complete a failing test, make it pass, then refactor, passing to the next pair
- Activity acknowledges resistance ("you might think TDD is slow") and uses the experience to demonstrate the opposite

#### 3: Error/Boundary -- Activity incompatible with format
Marco's workshop is online, and the agent generates an activity requiring physical card sorting. The agent detects the format mismatch, flags it, and suggests a Miro-based equivalent (drag sticky notes instead of physical cards).

### UAT Scenarios (BDD)

#### Scenario: Activity cards are domain-specific
```gherkin
Given a 4C structure for "Kubernetes Networking" with LO-3 [Apply] "Troubleshoot broken Service-to-Pod routing"
When the agent designs the Concrete Practice activity
Then the activity uses real Kubernetes concepts (Pod, Service, kubectl, CNI)
And includes specific technical scenarios (not "debug a network issue" generically)
And the activity card includes setup, instructions, facilitation tips, and Plan B
```

#### Scenario: Every activity has Plan B contingency
```gherkin
Given 6 activities designed for Marco's workshop
When the agent completes activity design
Then each activity card includes a "Plan B" section
And the Plan B achieves the same learning outcome with different facilitation approach
And the Plan B is described with enough detail to execute without preparation
```

#### Scenario: Format-incompatible activity detected
```gherkin
Given an online workshop via Zoom + Miro
When the agent generates an activity requiring physical materials
Then the agent detects the format incompatibility
And suggests a digital equivalent appropriate for Miro
And does not include the incompatible activity in the final design
```

#### Scenario: Activity includes assessment checkpoint
```gherkin
Given an activity card for "Troubleshooting Lab" mapped to LO-3
When the agent completes the activity design
Then the card includes an assessment checkpoint
And the checkpoint specifies what to observe ("Can pairs articulate root cause?")
And includes an adjustment trigger ("If < 50% articulate root cause, extend debrief by 5 min")
```

### Acceptance Criteria
- [ ] Activities use real domain content from the workshop topic
- [ ] Each activity maps to at least one learning outcome
- [ ] Each activity card includes: setup, instructions, facilitation tips, timing (with compress/extend), Plan B, assessment checkpoint
- [ ] Activities are compatible with the declared workshop format
- [ ] No generic placeholder activities ("discuss in groups" without specifics)

### Technical Notes
- Activity design is the highest-opportunity area (Score 16.9 in opportunity analysis)
- Plan B is critical for overcoming the anxiety force -- facilitators fear activities falling flat
- Assessment checkpoints embed formative assessment without requiring a separate assessment step

### Dependencies
- US-WS-003 (4C structure must be defined)
- US-WS-002 (learning outcomes must be defined)

### Traces To
- JS-2: Activity Design for Learning Outcomes
- Outcome 3.3: Minimize time to design creative, domain-specific activities
- Outcome 3.2: Minimize likelihood of activities misaligned with outcomes

---

## US-WS-005: Energy-Aware Timing

### Problem
Marco Benedetti is an IT trainer whose workshops consistently run over time. He finds it frustrating that the "important stuff" gets crammed into the last 30 minutes when attention is lowest. His current workaround is linear time-blocking in a spreadsheet ("10:00-10:30 Topic A, 10:30-11:00 Topic B") which has no mechanism for adaptation when activities run long or short, and no consideration of human energy patterns.

### Who
- IT Trainer | Has activities designed for a 4C structure | Wants a timing plan that manages energy patterns and includes adaptation mechanisms

### Solution
The agent creates an energy-aware timeline with activity sequencing matched to human attention patterns (high-energy opener, focused deep-dive, reflective close). The timeline includes adaptation points where the facilitator can expand, compress, or skip activities without losing learning continuity.

### Domain Examples

#### 1: Happy Path -- 90-minute energy timeline
For Marco's workshop:
- 0-15 min: HIGH energy (Connections -- movement, social, competitive)
- 15-35 min: MEDIUM energy (Concepts -- cognitive load, small group work)
- 35-40 min: RECOVERY (micro-break before deep practice)
- 40-80 min: LOW->HIGH (Practice -- focused work, then lively debate)
- 80-90 min: MEDIUM (Conclusions -- reflective, personal)
- Adaptation points at 35 min, 55 min, and 75 min with specific expand/compress/skip instructions

#### 2: Edge Case -- Half-day workshop needs multiple energy cycles
For a 4-hour workshop, the agent designs two energy cycles (morning and afternoon) with a substantial break between, and a re-energizer activity after each break to rebuild engagement.

#### 3: Error/Boundary -- All high-energy activities
If the agent generates a plan where all activities are high-energy (discussion, debate, competition), it detects the missing recovery periods and inserts lower-energy reflective segments to prevent burnout.

### UAT Scenarios (BDD)

#### Scenario: Energy-aware timeline for 90 minutes
```gherkin
Given 6 activities with total duration of 85 minutes plus a 5-minute break
When the agent creates the energy timeline
Then each activity segment has an energy level annotation (HIGH, MEDIUM, LOW)
And the session opens with a HIGH energy activity
And the session closes with a MEDIUM (reflective) activity
And a break is placed before the longest activity block
```

#### Scenario: Adaptation points with expand/compress instructions
```gherkin
Given a 90-minute energy timeline with 6 activities
When the agent finalizes the timeline
Then at least 2 adaptation points are defined
And each adaptation point specifies: expand option, compress option, skip option
And the skip option describes which learning outcome is affected and how to compensate
```

#### Scenario: Multi-cycle energy management for long sessions
```gherkin
Given a 4-hour workshop with 12 activities
When the agent creates the energy timeline
Then at least 2 energy cycles are created (each 90-120 minutes)
And a substantial break (15-20 minutes) separates cycles
And each cycle opens with a re-energizer activity
And no more than 25 minutes of sustained low-energy activity without a shift
```

### Acceptance Criteria
- [ ] Every activity segment has energy level annotated
- [ ] Session follows energy pattern: high opener, focused middle, reflective close
- [ ] Adaptation points included with expand/compress/skip instructions
- [ ] Skip instructions describe learning outcome impact and compensation
- [ ] Break included for sessions over 60 minutes
- [ ] Long sessions (3+ hours) have multiple energy cycles

### Technical Notes
- Human attention patterns: peak attention 10-15 minutes, then declining; energy dips after 45-60 minutes; post-lunch dip at 1-2 PM
- Adaptation points are the key differentiator from linear time-blocking -- they address the anxiety force about "what if the plan does not match reality"

### Dependencies
- US-WS-004 (activities must be designed with timing estimates)

### Traces To
- JS-5: Energy and Timing Management
- Outcome 4.1: Timing accounts for human energy patterns
- Outcome 5.2: Minimize time to adapt when activities run long/short

---

## US-WS-006: Workshop Coherence Validation

### Problem
Marco Benedetti is an IT trainer who never validates his workshop design before delivery. He finds that problems only surface during delivery -- an activity that does not map to any learning outcome, timing that does not add up, or a Bloom's level gap (jumping from Remember to Analyze with nothing in between). His current workaround is "wing it and hope for the best," which creates anxiety throughout delivery.

### Who
- IT Trainer | Has a complete workshop design (context, outcomes, 4C structure, activities, timing) | Wants confidence that all pieces connect before delivery

### Solution
The agent runs a coherence validation across 6 dimensions: learning outcome coverage, facilitator talk time, activity-outcome alignment, timing feasibility, Bloom's progression, and assessment coverage. Failures include specific remediation guidance.

### Domain Examples

#### 1: Happy Path -- All dimensions pass
Marco's workshop design passes all 6 dimensions. The agent reports a clean validation with confidence metrics for each dimension.

#### 2: Edge Case -- Orphan learning outcome detected
The agent detects that LO-4 [Analyze] has no activity mapped to it -- Marco removed the CNI Debate activity but forgot to remove or reassign the outcome. The agent flags this with specific remediation: "LO-4 has no activity. Options: (a) add a new activity, (b) embed LO-4 into the Troubleshooting Lab debrief, (c) remove LO-4."

#### 3: Error/Boundary -- Talk time exceeds 20%
The validation detects that Marco added a 15-minute "Introduction" lecture, pushing facilitator talk time to 32%. The agent flags this with TBR reasoning and suggests learner-centered alternatives for the introduction content.

### UAT Scenarios (BDD)

#### Scenario: All 6 validation dimensions pass
```gherkin
Given a complete workshop design with 4 learning outcomes, 6 activities, and energy timeline
When the agent runs coherence validation
Then all 6 dimensions are checked: LO coverage, talk time, activity-outcome alignment, timing feasibility, Bloom's progression, assessment coverage
And each dimension reports PASS with supporting evidence
And an overall "WORKSHOP DESIGN VALIDATED" status is shown
```

#### Scenario: Orphan learning outcome detected
```gherkin
Given a workshop design where LO-4 has no mapped activity
When the agent runs coherence validation
Then the LO coverage dimension reports FAIL
And the failure message identifies LO-4 specifically
And remediation options are provided (add activity, embed in existing activity, remove outcome)
```

#### Scenario: Facilitator talk time exceeds threshold
```gherkin
Given a workshop design with 32% estimated facilitator talk time
When the agent runs coherence validation
Then the talk time dimension reports FAIL
And the specific segments contributing to high talk time are identified
And learner-centered alternatives are suggested for each high-talk segment
```

### Acceptance Criteria
- [ ] 6 validation dimensions checked: LO coverage, talk time, alignment, timing, Bloom's, assessment
- [ ] Each dimension reports PASS or FAIL with evidence
- [ ] Failed dimensions include specific remediation guidance
- [ ] User can iterate (modify design) and re-validate
- [ ] Overall validation status clearly communicated

### Technical Notes
- Validation is automatically triggered before export, but can also be invoked manually via `*review`
- This is the "moment of truth" where confidence crystallizes -- the validation must feel thorough and trustworthy

### Dependencies
- US-WS-005 (complete design must exist)

### Traces To
- JS-1: Workshop Structure Design (validation dimension)
- Outcome 4.3: Validate all learning outcomes covered

---

## US-WS-007: Facilitator Package Export

### Problem
Marco Benedetti is an IT trainer who, even after designing a good workshop, spends another 2-3 hours producing facilitator materials -- session plans, handouts, timing sheets. He finds it tedious to format the same information in different ways for different purposes. His current workaround is a single Google Doc that tries to serve all purposes, which means participants see facilitator notes and the timing sheet is buried in page 7.

### Who
- IT Trainer | Has a validated workshop design | Wants a complete, separated facilitator package ready for delivery

### Solution
The agent compiles the validated workshop design into a facilitator package: facilitator guide, individual activity cards, timing sheet, participant handout, Miro board specification, and assessment rubric. Each artifact serves a specific purpose and audience.

### Domain Examples

#### 1: Happy Path -- Complete package for Marco
The agent generates 6 artifacts for Marco's "Kubernetes Networking" workshop:
1. `facilitator-guide.md` -- minute-by-minute plan with facilitator notes
2. `activity-cards/` -- 6 individual activity cards (printable/shareable)
3. `timing-sheet.md` -- energy timeline with adaptation points
4. `participant-handout.md` -- pre-workshop prep + post-workshop reference
5. `miro-board-spec.md` -- board architecture (online workshops only)
6. `assessment-rubric.md` -- formative checkpoints with indicators

#### 2: Edge Case -- In-person workshop skips Miro spec
For Sofia's in-person workshop, the agent skips the Miro board spec and instead generates a room setup guide (table arrangements, materials checklist, wall space for physical activities).

#### 3: Error/Boundary -- Export before validation
Marco invokes `*export` before the design passes validation. The agent runs validation first, reports failures, and blocks export until critical issues are resolved.

### UAT Scenarios (BDD)

#### Scenario: Complete facilitator package generated
```gherkin
Given a validated workshop design for "Kubernetes Networking"
When Marco invokes *export
Then 6 artifacts are generated in the workshop output directory
And the facilitator guide references activity cards by name and sequence
And the timing sheet matches activity card durations exactly
And the participant handout contains no facilitator-only notes
```

#### Scenario: Format-appropriate artifacts
```gherkin
Given an in-person workshop for "TDD for Our Java Codebase"
When Sofia invokes *export
Then a room setup guide is generated instead of a Miro board spec
And the room setup guide includes table arrangements for the declared group size
And a materials checklist is included (sticky notes, markers, printed cards)
```

#### Scenario: Export blocked by validation failure
```gherkin
Given a workshop design that has not passed coherence validation
When Marco invokes *export
Then the agent runs validation automatically
And displays validation results
And blocks export until all critical validation failures are resolved
And allows export with warnings for non-critical issues
```

### Acceptance Criteria
- [ ] 6 artifact types generated for online workshops; adapted set for in-person
- [ ] Artifacts use consistent terminology, timing, and activity references
- [ ] Participant-facing materials contain no facilitator-only information
- [ ] Export blocked if critical validation failures exist
- [ ] All ${variables} resolved -- no unresolved placeholders in exported artifacts

### Technical Notes
- Export is the final step of the core journey; optional steps (gamification, Miro board) enhance these artifacts
- Artifact format is Markdown for portability
- Output directory: user-specified or default `docs/workshops/{topic-slug}/`

### Dependencies
- US-WS-006 (validation must pass)

### Traces To
- JS-1: Workshop Structure Design (conclusion)
- Outcome 8.1: Minimize time to produce post-workshop materials

---

## US-WS-008: Pedagogical Gamification Design

### Problem
Marco Benedetti is an IT trainer who gets stakeholder pressure to "add gamification" to workshops but finds that points and badges feel gimmicky and disconnected from learning. He finds it impossible to design game mechanics that serve pedagogical goals rather than just adding superficial fun. His current workaround is a Kahoot quiz at the end, which only tests recall (Bloom's Level 1) and feels like an afterthought.

### Who
- IT Trainer | Has a validated workshop design | Wants gamification mechanics that are explicitly justified by pedagogical goals

### Solution
The agent designs a gamification layer for an existing workshop, mapping game mechanics to learning outcomes: progression systems scaffolding Bloom's levels, challenge curves matching the flow channel, narrative frames giving context to activities, and feedback loops reinforcing learning. Every mechanic includes a pedagogical justification.

### Domain Examples

#### 1: Happy Path -- Progression system for Kubernetes workshop
For Marco's workshop, the agent designs:
- **Progression**: Participants advance through "Network Engineer" levels (Novice -> Practitioner -> Specialist -> Architect) as they complete each 4C phase. Levels map to Bloom's (Remember -> Understand -> Apply -> Analyze).
- **Challenge curve**: Troubleshooting Lab has tiered difficulty (easy/medium/hard scenarios). Pairs can choose their challenge level.
- **Narrative**: "Your company's production Kubernetes cluster has network issues. You have been called in as the Network Response Team."
- **Feedback**: Miro board shows team progression through zones (visual progress indicator).
- **Justification**: "Progression system scaffolds from recall to analysis. Tiered challenges maintain flow state by matching difficulty to skill level."

#### 2: Edge Case -- Gamification for senior audience
For a workshop with senior architects (10+ years experience), the agent adjusts:
- No points or levels (would feel patronizing)
- Competitive element: "Architecture Review Board" where pairs critique each other's designs using structured criteria
- Narrative: collegial, not playful ("You are consultants advising a client" not "You are heroes saving the kingdom")
- Justification: "Senior professionals respond to peer challenge and professional narrative, not extrinsic reward systems."

#### 3: Error/Boundary -- Gamification without pedagogical justification
The user asks "add a leaderboard to make it competitive." The agent designs the leaderboard but includes a pedagogical justification requirement: what learning outcome does competition serve? If the answer is "engagement only," the agent flags this as decoration and suggests an alternative mechanic that serves both engagement and learning.

### UAT Scenarios (BDD)

#### Scenario: Every game mechanic has pedagogical justification
```gherkin
Given a validated workshop design with 4 learning outcomes
When Marco invokes *gamify
Then the agent designs at least 3 game mechanics
And each mechanic includes a "Pedagogical Justification" field
And each justification references a specific learning outcome or Bloom's level
And no mechanic exists solely for "engagement" without a learning connection
```

#### Scenario: Audience-appropriate gamification
```gherkin
Given a workshop audience of "senior architects with 10+ years experience"
When the agent designs gamification
Then the agent avoids extrinsic reward systems (points, badges, leaderboards)
And uses peer challenge, professional narrative, and collegial competition
And the framing is described as "professional" not "playful"
```

#### Scenario: Challenge curve matches flow channel
```gherkin
Given a Concrete Practice activity with tiered difficulty
When the agent designs the challenge mechanic
Then difficulty tiers map to Bloom's levels (easy=Remember, medium=Apply, hard=Analyze)
And participants can self-select difficulty level
And the agent describes the flow state rationale (skill-challenge balance)
```

### Acceptance Criteria
- [ ] Every game mechanic has explicit pedagogical justification
- [ ] Gamification design adapted to audience maturity/seniority
- [ ] Challenge curves match Bloom's progression
- [ ] Narrative framing is audience-appropriate
- [ ] No mechanics exist solely for superficial engagement without learning connection

### Technical Notes
- MDA framework: Mechanics (rules) -> Dynamics (behavior) -> Aesthetics (feelings)
- Bartle player types relevant for longer programs but overkill for single sessions
- Gamification is an optional enhancement, never a mandatory component

### Dependencies
- US-WS-006 (validated workshop design required)

### Traces To
- JS-3: Gamification That Serves Learning
- Outcome 3.6: Minimize likelihood of gamification disconnected from learning outcomes

---

## US-WS-009: Miro Board Architecture

### Problem
Marco Benedetti is an IT trainer who runs online workshops where participants get lost on the Miro board. He finds it time-consuming to design a board layout that guides participants through the workshop phases without constant facilitator direction. His current workaround is creating the board on the fly during the session, which looks unprofessional and wastes 10-15 minutes of session time on navigation confusion.

### Who
- IT Trainer | Has a validated online workshop design | Wants a Miro board architecture that participants can self-navigate

### Solution
The agent designs a complete Miro board architecture with distinct zones per 4C phase, participant frames, navigation flow, color coding, facilitator notes section, and timer placement. The architecture is described with enough specificity (dimensions, colors, template specs) that the facilitator can build it in Miro within 30 minutes.

### Domain Examples

#### 1: Happy Path -- Board architecture for Kubernetes workshop
For Marco's online workshop, the agent designs:
- **4 zones**: Connections (blue), Concepts (green), Practice (orange), Conclusions (purple)
- **Navigation**: Large arrows connecting zones, numbered in session order
- **Participant frames**: 8 pair frames within each zone (16 participants = 8 pairs)
- **Templates**: Pre-built sticky note templates in each participant frame
- **Timer section**: Visible timer/phase indicator at top of board
- **Facilitator notes**: Hidden section (outside visible area) with activity instructions

#### 2: Edge Case -- Hybrid workshop with split participants
For a hybrid workshop where 8 participants are in-room and 8 are remote, the agent designs a board that works for remote participants while in-room participants use physical materials. The board includes "mirror zones" where in-room activity results are photographed and placed for remote participants to see.

#### 3: Error/Boundary -- In-person workshop does not need Miro board
Sofia's workshop is in-person. The agent does not generate a Miro board architecture and instead suggests physical space arrangements. If Sofia overrides and requests a Miro board anyway (for documentation), the agent generates a simplified capture board, not a full facilitation board.

### UAT Scenarios (BDD)

#### Scenario: Board architecture with 4C zones
```gherkin
Given a validated online workshop with 4C structure
When Marco invokes *miro-board
Then the agent produces a board architecture with 4 distinct zones (one per C)
And each zone has a color assignment and a descriptive header
And navigation between zones is explicit (arrows, numbering)
And participant frames are sized for the declared group size
```

#### Scenario: Board buildable within 30 minutes
```gherkin
Given a Miro board architecture specification
When Marco reads the specification
Then zone dimensions are described (approximate frame sizes)
And color codes are specified (hex or named colors)
And template contents are described (what pre-fills each participant frame)
And a facilitator can build the complete board in Miro within 30 minutes
```

#### Scenario: In-person workshop gets room setup instead
```gherkin
Given Sofia's in-person workshop for 12 developers
When Sofia invokes *miro-board
Then the agent explains that in-person workshops use physical space, not Miro boards
And offers a room setup guide instead
And if Sofia insists on a Miro board, generates a simplified capture board (not facilitation board)
```

### Acceptance Criteria
- [ ] Board architecture has distinct zones per 4C phase
- [ ] Color coding and navigation flow specified
- [ ] Participant frames sized for group size
- [ ] Architecture buildable in Miro within 30 minutes
- [ ] Format-appropriate: full facilitation board for online, room setup for in-person

### Technical Notes
- Miro-specific guidance: frame sizes, sticky note colors, section links, zoom levels
- The board IS the workshop for online sessions (taste guideline 3)
- Board architecture is an optional enhancement, auto-suggested for online format workshops

### Dependencies
- US-WS-006 (validated workshop design required)
- Workshop format must be "online" or "hybrid"

### Traces To
- JS-4: Miro Board Architecture
- Outcome 3.5: Minimize time to design Miro board architecture

---

## Story Map (Priority Ordering)

```
Workshop Design Journey:
  [Context] --> [Outcomes] --> [4C Structure] --> [Activities] --> [Timing] --> [Validate] --> [Export]
     |              |              |                  |              |            |             |
  US-WS-001     US-WS-002      US-WS-003          US-WS-004     US-WS-005   US-WS-006     US-WS-007
  (Must Have)   (Must Have)    (Must Have)         (Must Have)   (Must Have) (Must Have)   (Must Have)

  Optional Enhancements:
  [Gamification]     [Miro Board]
       |                  |
    US-WS-008          US-WS-009
   (Should Have)      (Should Have)
```

### MoSCoW Summary

| Priority | Stories | Rationale |
|----------|---------|-----------|
| Must Have | US-WS-001 through US-WS-007 | Core workshop design journey -- without any of these, the agent cannot produce a complete workshop |
| Should Have | US-WS-008 (Gamification), US-WS-009 (Miro Board) | Enhancement layers that differentiate but are not required for a usable workshop plan |
| Could Have | Post-workshop follow-up materials, workshop iteration (design-deliver-improve cycle) | Future enhancements after core journey proven |
| Won't Have (v1) | Real-time delivery assistance, automated Miro board generation (API), multi-session program design | Valuable but beyond agent scope for initial release |
