# Acceptance Criteria: nw-workshopper Agent

## Overview

This document consolidates all acceptance criteria and BDD scenarios from the user stories into a single reference for the DISTILL wave (acceptance-designer). Each scenario traces to a user story and job story.

---

## Feature: Workshop Context Discovery (US-WS-001)

### Business Rule: Structured context gathering
The agent must capture all essential workshop parameters before proceeding to design.

```gherkin
Feature: Workshop Context Discovery
  As an IT trainer starting a new workshop design
  I want the agent to guide me through defining the workshop context
  So that all subsequent design steps have a solid foundation

  Scenario: Complete context captured for online workshop
    Given Marco Benedetti invokes *workshop "Kubernetes Networking"
    When the agent conducts the discovery conversation
    And Marco provides:
      | Field         | Value                                  |
      | audience      | 16 mid-level DevOps engineers          |
      | proficiency   | 2-3 years Kubernetes experience        |
      | duration      | 90 minutes                             |
      | format        | Online via Zoom + Miro                 |
      | materials     | 40-slide deck from previous conference |
    Then the agent creates a workshop context with all 6 fields populated
    And displays a confirmation summary for Marco to validate
    And no field shows "unknown" or "TBD"

  Scenario: Context with missing information uses defaults
    Given Kenji Takahashi 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 of 8-12 participants
    And marks the assumption with "[ASSUMPTION: group size 8-12, confirm before delivery]"
    And proceeds to learning outcomes without blocking

  Scenario: Greenfield context without existing materials
    Given Sofia Rinaldi invokes *workshop "TDD for Our Java Codebase"
    When the agent asks about existing materials
    And Sofia responds "I have nothing written down"
    Then the agent proceeds without requiring materials
    And notes "All content will be generated fresh -- no existing materials to repurpose"

  Scenario: Context re-confirmation after changes
    Given Marco has a confirmed workshop context
    When Marco says "Actually, the group size is 24, not 16"
    Then the agent updates the context object
    And re-confirms the updated context
    And flags any downstream impacts ("24 participants changes pair activities to 12 pairs")
```

---

## Feature: Learning Outcome Generation (US-WS-002)

### Business Rule: Bloom's-calibrated outcomes
Outcomes must be mapped to Bloom's taxonomy and calibrated to time and audience.

```gherkin
Feature: Learning Outcome Generation
  As an IT trainer who has defined workshop context
  I want learning outcomes at the right Bloom's level
  So that activities can be designed to produce measurable learning

  Scenario: Bloom's-calibrated outcomes for 90-minute technical workshop
    Given a workshop context:
      | topic    | Kubernetes Networking              |
      | audience | 16 mid-level DevOps engineers      |
      | duration | 90 minutes                         |
    When the agent generates learning outcomes
    Then 3-5 outcomes are produced
    And each outcome has a Bloom's taxonomy level (Remember through Create)
    And the highest Bloom's level is Analyze (appropriate for 90 min with mid-level audience)
    And the agent explains: "90 minutes supports Remember through Analyze. Evaluate/Create requires half-day or longer."

  Scenario: Full-day workshop enables higher Bloom's levels
    Given a workshop context:
      | topic    | Cloud-Native Security              |
      | audience | 30 developer advocates             |
      | duration | 6 hours                            |
    When the agent generates learning outcomes
    Then outcomes reach Evaluate or Create levels
    And the agent explains the time-level relationship for full-day sessions

  Scenario: Too many outcomes for time slot rejected
    Given a workshop context with duration 45 minutes
    When Marco requests 8 learning outcomes
    Then the agent explains: "45 minutes supports 2-3 outcomes at Remember-Understand level"
    And suggests reducing to 2-3 outcomes
    And does not proceed with 8 outcomes unless Marco extends the time slot

  Scenario: User adjusts generated outcomes
    Given the agent has generated 4 outcomes for Marco's workshop
    When Marco says "I want to add an outcome about NetworkPolicy syntax"
    Then the agent integrates the new outcome
    And assigns an appropriate Bloom's level
    And re-validates total outcome count against session duration
    And warns if the new outcome makes the design infeasible
```

---

## Feature: 4C Workshop Structure (US-WS-003)

### Business Rule: TBR 4C framework with facilitator talk-time constraint
All workshops use the 4C structure with Concrete Practice as the largest phase.

```gherkin
Feature: 4C Workshop Structure
  As an IT trainer with defined learning outcomes
  I want a TBR 4C structure with proper time allocation
  So that my workshop follows learner-centered principles

  Scenario: 4C structure with TBR-compliant allocation
    Given 4 learning outcomes for a 90-minute online workshop
    When the agent generates the 4C structure
    Then four phases are created:
      | Phase             | Time  | Purpose                          |
      | Connections       | 15 min | Activate prior knowledge        |
      | Concepts          | 20 min | Introduce new information       |
      | Concrete Practice | 40 min | Apply and practice              |
      | Conclusions       | 15 min | Synthesize and transfer         |
    And phase durations sum to 90 minutes
    And Concrete Practice has the largest allocation (at least 35%)
    And estimated facilitator talk time is 15.5% (under 20% threshold)

  Scenario: Short session compression preserves all 4 Cs
    Given a 45-minute conference slot
    When the agent generates the 4C structure
    Then all 4 phases are present (none omitted)
    And Concrete Practice still has the largest allocation
    And no break is included (session under 60 minutes)

  Scenario: Long session includes breaks
    Given a 4-hour workshop
    When the agent generates the 4C structure
    Then at least one substantial break (15-20 min) is included
    And break placement follows energy management principles
    And total activity time + breaks = 4 hours

  Scenario: User requests excessive lecture time
    Given Sofia requests "I want to present for about 45 minutes of the 90"
    When the agent generates the 4C structure
    Then the agent explains TBR research on facilitator talk time
    And quantifies the impact: "45 min talk time = 50%, well above the 20% guideline"
    And suggests learner-centered alternatives (jigsaw, card sort, guided discovery)
    And allows Sofia to override with explicit acknowledgment
```

---

## Feature: Domain-Specific Activity Design (US-WS-004)

### Business Rule: Activities must be domain-specific, outcome-aligned, and include contingencies

```gherkin
Feature: Domain-Specific Activity Design
  As an IT trainer with a 4C structure
  I want creative activities that use real domain content
  So that participants learn through doing, not listening

  Scenario: Activity uses real domain content
    Given a 4C structure for "Kubernetes Networking"
    And LO-3 [Apply] "Troubleshoot broken Service-to-Pod routing"
    When the agent designs the Concrete Practice activity
    Then the activity references real Kubernetes concepts: Pod, Service, kubectl, CNI
    And includes specific technical scenarios (e.g., "Service selector mismatch", "NetworkPolicy blocking traffic")
    And does not use generic placeholders ("debug a network issue")

  Scenario: Every activity has complete facilitation card
    Given 6 activities designed for a 90-minute workshop
    When the agent completes activity design
    Then each activity card contains:
      | Section               | Content                                    |
      | 4C Phase              | Which phase this activity belongs to        |
      | Learning Outcome      | Which LO(s) this activity addresses         |
      | Duration              | Base time, compress option, extend option    |
      | Group Configuration   | Pairs, triads, groups, individual            |
      | Format Requirements   | Online, in-person, or both                  |
      | Setup Instructions    | What to prepare before the activity          |
      | Activity Instructions | Step-by-step for participants                |
      | Facilitation Tips     | Guidance for the facilitator during activity |
      | Plan B                | What to do if the activity falls flat        |
      | Assessment Checkpoint | What to observe, adjustment trigger           |

  Scenario: Plan B achieves same learning outcome
    Given an activity card for "Troubleshooting Lab" mapped to LO-3
    When the agent designs the Plan B
    Then the Plan B targets the same learning outcome (LO-3)
    And uses a different facilitation approach (e.g., guided walkthrough instead of autonomous pairs)
    And is described with enough detail to execute without preparation

  Scenario: Format-incompatible activity detected and replaced
    Given an online workshop via Zoom + Miro
    When the agent generates an activity requiring physical card sorting
    Then the agent detects the format incompatibility
    And replaces it with a Miro-based equivalent (drag sticky notes)
    And explains the substitution

  Scenario: Assessment checkpoint with adjustment trigger
    Given an activity card for "Troubleshooting Lab"
    When the agent designs the assessment checkpoint
    Then the checkpoint specifies an observable indicator ("Can pairs articulate root cause?")
    And includes a threshold ("If < 50% of pairs articulate root cause")
    And includes an adjustment action ("Extend debrief by 5 minutes")
```

---

## Feature: Energy-Aware Timing (US-WS-005)

### Business Rule: Timing manages energy patterns, not just clock time

```gherkin
Feature: Energy-Aware Timing
  As an IT trainer with activities designed
  I want a timing plan that accounts for human energy patterns
  So that learning happens when attention is highest

  Scenario: Energy annotations on every segment
    Given 6 activities for a 90-minute workshop
    When the agent creates the energy timeline
    Then each activity segment has an energy level: HIGH, MEDIUM, or LOW
    And the opening activity is HIGH energy
    And the closing activity is MEDIUM energy (reflective)
    And no more than 25 minutes of consecutive LOW energy without a shift

  Scenario: Adaptation points with three options
    Given a 90-minute energy timeline
    When the agent defines adaptation points
    Then at least 2 adaptation points exist
    And each point specifies:
      | Option   | Description                              |
      | Expand   | How to extend this segment if time allows |
      | Compress | How to shorten this segment if behind     |
      | Skip     | What to skip and how to compensate        |
    And the Skip option names the affected learning outcome

  Scenario: Break placement follows energy principles
    Given a 90-minute workshop
    When the agent places the break
    Then the break is positioned before the longest sustained activity block
    And the break duration is 5 minutes (for 90-minute sessions)
    And the break is described as a "recovery point" in the energy annotation

  Scenario: Multi-cycle plan for half-day workshop
    Given a 4-hour workshop with 12 activities
    When the agent creates the energy timeline
    Then at least 2 energy cycles exist (each 90-120 minutes)
    And a 15-20 minute break separates cycles
    And each cycle opens with a re-energizer activity
```

---

## Feature: Workshop Coherence Validation (US-WS-006)

### Business Rule: All 6 dimensions must pass before export

```gherkin
Feature: Workshop Coherence Validation
  As an IT trainer with a complete design
  I want to validate that all pieces connect
  So that I deliver the workshop with confidence

  Scenario: All 6 validation dimensions pass
    Given a complete workshop design:
      | Component         | Status              |
      | Learning Outcomes | 4 outcomes defined  |
      | 4C Structure      | All phases allocated|
      | Activities        | 6 activities designed|
      | Energy Timeline   | Annotated and timed |
    When the agent runs coherence validation
    Then 6 dimensions are checked:
      | Dimension                   | Result |
      | Learning outcome coverage   | PASS   |
      | Facilitator talk time       | PASS   |
      | Activity-outcome alignment  | PASS   |
      | Timing feasibility          | PASS   |
      | Bloom's progression         | PASS   |
      | Assessment coverage         | PASS   |
    And overall status shows "WORKSHOP DESIGN VALIDATED"

  Scenario: Orphan learning outcome detected
    Given LO-4 [Analyze] exists but no activity maps to it
    When the agent runs coherence validation
    Then "Learning outcome coverage" reports FAIL
    And the failure identifies "LO-4 [Analyze]: no mapped activity"
    And remediation options: add activity, embed in existing, or remove outcome

  Scenario: Talk time exceeds 20%
    Given estimated facilitator talk time is 32%
    When the agent runs coherence validation
    Then "Facilitator talk time" reports FAIL
    And identifies segments: "Introduction (15 min), Concept explanation (10 min)"
    And suggests learner-centered alternatives for each segment

  Scenario: Bloom's level gap detected
    Given outcomes at Remember, Understand, and Analyze (skipping Apply)
    When the agent runs coherence validation
    Then "Bloom's progression" reports FAIL
    And identifies the gap: "Level skip from Understand to Analyze"
    And suggests adding an Apply-level activity between them

  Scenario: Iteration after validation failure
    Given coherence validation reported 2 failures
    When Marco modifies the design to address both failures
    And invokes *review again
    Then the agent re-validates all 6 dimensions
    And reports updated results
```

---

## Feature: Facilitator Package Export (US-WS-007)

### Business Rule: Export produces complete, consistent artifact set

```gherkin
Feature: Facilitator Package Export
  As an IT trainer with a validated design
  I want a complete facilitator package
  So that I am ready to deliver without additional preparation

  Scenario: Complete online workshop package
    Given a validated "Kubernetes Networking" workshop (online format)
    When Marco invokes *export
    Then these artifacts are generated:
      | Artifact               | Purpose                                      |
      | facilitator-guide.md   | Minute-by-minute plan with facilitator notes  |
      | activity-cards/        | Individual cards (6 activities)                |
      | timing-sheet.md        | Energy timeline with adaptation points         |
      | participant-handout.md | Pre-workshop prep + post-workshop reference    |
      | miro-board-spec.md     | Board architecture for online delivery         |
      | assessment-rubric.md   | Formative checkpoints with indicators          |

  Scenario: Artifact consistency check
    Given the facilitator guide references "Network Bingo" at minute 0
    When Marco reads the corresponding activity card
    Then the activity card title matches "Network Bingo"
    And the timing matches the facilitator guide (10 minutes)
    And the learning outcome reference matches (LO-1)

  Scenario: In-person workshop package adaptation
    Given a validated "TDD for Our Java Codebase" workshop (in-person format)
    When Sofia invokes *export
    Then a room-setup-guide.md is generated instead of miro-board-spec.md
    And the room setup guide specifies table arrangements for 12 participants
    And a materials checklist is included

  Scenario: Export blocked by validation failure
    Given a workshop design with an orphan learning outcome (validation FAIL)
    When Marco invokes *export
    Then the agent runs validation
    And displays the failure: "LO-4 has no mapped activity"
    And blocks export: "Resolve critical validation failures before exporting"
    And provides remediation guidance

  Scenario: No unresolved variables in exported artifacts
    Given all artifacts generated for the workshop
    When the agent checks for unresolved placeholders
    Then no artifact contains "${...}" patterns
    And no artifact contains "TBD" or "TODO" markers
    And all workshop context values (topic, audience, duration) are resolved
```

---

## Feature: Pedagogical Gamification Design (US-WS-008)

### Business Rule: Every game mechanic must have pedagogical justification

```gherkin
Feature: Pedagogical Gamification Design
  As an IT trainer who wants to increase engagement
  I want gamification that serves learning outcomes
  So that game mechanics reinforce rather than distract from learning

  Scenario: Game mechanics with pedagogical justification
    Given a validated workshop with 4 learning outcomes
    When Marco invokes *gamify
    Then at least 3 game mechanics are designed
    And each mechanic has a "Pedagogical Justification" field
    And each justification references a specific learning outcome or Bloom's level
    And no mechanic has justification "engagement only" without learning connection

  Scenario: Progression system maps to Bloom's levels
    Given a workshop with outcomes from Remember to Analyze
    When the agent designs a progression system
    Then progression levels correspond to Bloom's levels
    And advancement from one level to the next requires demonstrating the corresponding skill
    And the agent describes how progression scaffolds difficulty

  Scenario: Audience-appropriate gamification for seniors
    Given audience "senior architects with 10+ years experience"
    When the agent designs gamification
    Then extrinsic rewards (points, badges, leaderboards) are avoided
    And peer challenge and professional narrative are used instead
    And the framing is described as "collegial" and "professional"

  Scenario: Challenge curve aligns with flow channel
    Given a Concrete Practice activity with difficulty tiers
    When the agent designs the challenge mechanic
    Then tiers map to Bloom's levels: easy=Remember, medium=Apply, hard=Analyze
    And participants can self-select difficulty
    And the rationale explains skill-challenge balance (Csikszentmihalyi flow theory)

  Scenario: Gamification without learning connection flagged
    Given Marco asks "add a leaderboard to make it competitive"
    When the agent evaluates the request
    Then the agent asks: "What learning outcome does the competition serve?"
    And if the answer is "engagement only," flags it as decoration
    And suggests an alternative mechanic serving both engagement and learning
```

---

## Feature: Miro Board Architecture (US-WS-009)

### Business Rule: Board is the learning environment, not a visual aid

```gherkin
Feature: Miro Board Architecture
  As an IT trainer running an online workshop
  I want a Miro board that guides participants through the workshop
  So that the board itself serves as the learning environment

  Scenario: Board architecture with 4C zones
    Given a validated online workshop with 4C structure
    When Marco invokes *miro-board
    Then the architecture includes 4 zones:
      | Zone              | Color  | Purpose                         |
      | Connections       | Blue   | Prior knowledge activation      |
      | Concepts          | Green  | New information discovery       |
      | Concrete Practice | Orange | Hands-on application            |
      | Conclusions       | Purple | Synthesis and commitment        |
    And navigation arrows connect zones in sequence
    And zones are numbered in session order

  Scenario: Participant frames sized for group
    Given 16 participants working in pairs (8 pairs)
    When the agent designs participant frames
    Then 8 participant frames exist within each activity zone
    And each frame contains pre-built templates for the activity
    And frames are labeled with pair identifiers

  Scenario: Board buildable within 30 minutes
    Given the complete board architecture specification
    When Marco evaluates the specification
    Then approximate frame dimensions are provided
    And color codes are named (not just "blue" but "Miro Light Blue #B8D7F0")
    And template contents described (what text/stickies pre-fill each frame)
    And a step-by-step build guide is included

  Scenario: In-person workshop redirected to room setup
    Given an in-person workshop for 12 developers
    When Sofia invokes *miro-board
    Then the agent explains: "In-person workshops benefit from physical space design, not Miro boards"
    And offers a room setup guide with table arrangements and materials checklist
    And if Sofia insists, generates a simplified capture board (not facilitation board)

  Scenario: Facilitator notes section hidden from participants
    Given the board architecture
    When the agent designs the facilitator notes area
    Then the notes section is positioned outside the participant-visible area
    And contains activity timing, facilitation tips, and adaptation reminders
    And the build guide instructs the facilitator to lock/hide this section during the session
```

---

## Cross-Cutting Scenarios

### Business Rule: Agent commands are discoverable and consistent

```gherkin
Feature: Agent Command Interface
  As a user of the nw-workshopper agent
  I want clear commands for each capability
  So that I can navigate the workshop design process

  Scenario: Core command invocation
    Given the user has loaded the nw-workshopper agent
    When the user invokes *help
    Then the agent displays available commands:
      | Command       | Purpose                                           |
      | *workshop     | Start a new workshop design from topic             |
      | *review       | Run coherence validation on current design         |
      | *export       | Generate facilitator package                       |
      | *gamify       | Add gamification layer to current design           |
      | *miro-board   | Design Miro board architecture for current design  |
      | *help         | Display available commands                         |

  Scenario: Command outside active context
    Given no workshop context has been defined
    When the user invokes *gamify
    Then the agent explains: "No active workshop design. Start with *workshop 'Your Topic' first."
    And does not proceed
```

### Business Rule: Emotional arc coherence across the journey

```gherkin
Feature: Emotional Arc
  The workshop design journey should build confidence progressively

  @property
  Scenario: Progressive confidence building
    Given the user follows the workshop design journey from Step 1 through Step 7
    Then each step produces a tangible, visible artifact
    And the agent's tone shifts from supportive (Steps 1-2) to collaborative (Steps 3-5) to celebratory (Steps 6-7)
    And no step produces an error or ambiguity that breaks the confidence arc
    And the validation step (Step 6) is framed as "confirmation" not "testing"
```
