tdd-workshop/docs/plans/2026-03-10-workshop-improvements-design.md

# TDD Workshop Improvements - Design Document

**Date:** 2026-03-10  
**Author:** Workshop Facilitator  
**Status:** Approved

## Overview

This document outlines the design for enhancing the TDD workshop materials to create a comprehensive, ready-to-deliver 2-hour hands-on session for developers familiar with TDD concepts but lacking practical experience.

## Goals

1. Provide a complete live-demo kata (FizzBuzz) with step-by-step progression
2. Enhance facilitator guidance with detailed scripts and timing
3. Create participant reference materials (TDD cheat sheet)
4. Add setup and troubleshooting documentation
5. Improve solution files with test-to-code traceability

## Target Audience

- **Participants:** Developers who know what TDD is but haven't practiced it regularly
- **Facilitators:** Workshop leaders who need clear guidance and scripts
- **Format:** 2-hour in-person workshop
- **Language:** Dart

## Design Decisions

### Approach: Incremental Enhancement

We'll build improvements in three phases:

1. **Phase 1:** Live demo foundation (FizzBuzz kata)
2. **Phase 2:** Documentation (guides, reference card, setup)
3. **Phase 3:** Polish (enhanced solutions, root README)

This allows for testing each component and ensures core materials are ready first.

### Directory Structure

```
tdd-workshop/
├── README.md                           # NEW: Workshop overview
├── FACILITATOR_GUIDE.md                # ENHANCED: Add detailed scripts
├── WORKSHOP_PLAN.md                    # NEW: Complete schedule & checklists
├── TDD_REFERENCE_CARD.md               # NEW: One-page participant handout
├── SETUP_GUIDE.md                      # NEW: Installation & troubleshooting
├── docs/
│   └── plans/                          # Design documents
├── fizzbuzz/                           # NEW: Live demo kata
│   ├── README.md
│   ├── DEMO_SCRIPT.md                  # Facilitator walkthrough
│   ├── pubspec.yaml
│   ├── lib/
│   │   └── fizzbuzz.dart
│   └── test/
│       └── fizzbuzz_test.dart
├── password_validator/
│   └── lib/
│       └── password_validator_solution.dart  # ENHANCED: Add test references
└── shopping_cart/
    └── lib/
        └── shopping_cart_solution.dart       # ENHANCED: Add test references
```

## Component Designs

### 1. FizzBuzz Demo Kata

**Purpose:** Provide a ready-to-demonstrate kata showing RED-GREEN-REFACTOR in real-time.

**Git Strategy:** Linear commit history showing each TDD cycle:
- Commits alternate between RED (failing test) and GREEN (minimal implementation)
- Each commit message clearly labeled: "RED: ...", "GREEN: ...", "REFACTOR: ..."
- Facilitator can `git checkout` each commit to show progression

**Key Commits:**
1. Initial setup
2. RED: Test for 1 → "1"
3. GREEN: Return "1" (hardcoded)
4. RED: Test for 2 → "2"
5. GREEN: Return n.toString()
6. RED: Test for 3 → "Fizz"
7. GREEN: Check divisibility by 3
8. RED: Test for 5 → "Buzz"
9. GREEN: Add divisibility by 5
10. RED: Test for 15 → "FizzBuzz"
11. GREEN: Check both (order matters!)
12. REFACTOR: Optional cleanup

**DEMO_SCRIPT.md Contents:**
- Minute-by-minute timing guide (0-5, 5-10, 10-15)
- Talking points for each step
- Common mistakes to demonstrate intentionally
- Key insights participants should notice

### 2. Enhanced Documentation

#### TDD_REFERENCE_CARD.md
One-page handout covering:
- RED-GREEN-REFACTOR cycle diagram
- When to refactor (code smells)
- Common test patterns (Arrange-Act-Assert)
- Dart test assertions quick reference
- Tips for staying disciplined
- Link to tdd-katas for more practice

#### SETUP_GUIDE.md
Pre-workshop setup with:
- Dart SDK prerequisites
- Installation steps
- Verification procedures
- Troubleshooting common issues (pub get fails, PATH issues, etc.)
- IDE setup recommendations

#### WORKSHOP_PLAN.md
Complete facilitator reference with:
- Pre-workshop checklist (1 week, 1 day, morning of)
- Minute-by-minute schedule (8 segments, 120 minutes)
- Materials checklist (digital & physical)
- Facilitation tips (energy management, handling questions)
- Success metrics

### 3. Enhanced FACILITATOR_GUIDE.md

**Additions:**
- Full scripts for each segment (not just bullet points)
- Detailed live demo section with FizzBuzz walkthrough
- Expanded intervention table with more scenarios
- Transition scripts between segments
- Backup plans for running ahead/behind

**Structure:**
- Each segment has "What to say", "What to do", "What success looks like"
- Timing checkpoints throughout
- Ready-to-use phrases for common situations

### 4. Enhanced Solution Files

**Strategy:** Add inline comments linking code to tests and explaining design evolution.

**Comment Types:**
- **Test reference:** `// STEP 2: From test "rejects password with no uppercase"`
- **Design decision:** `// Map chosen over List for O(1) lookup by name`
- **Refactoring note:** `// Originally 5 if-blocks → extracted to rule functions`
- **Pattern highlight:** `// This is the Open-Closed Principle in action`

**Benefits:**
- Solutions become teaching tools
- Participants see why code looks this way
- Design patterns are explicitly named

### 5. Root README.md

**Purpose:** Orient anyone opening the repository.

**Sections:**
- Workshop overview (what, why, who)
- For facilitators (where to start)
- For participants (how to choose a kata)
- Repository structure explained
- Quick start instructions
- Links to additional resources

## Implementation Plan

### Phase 1: FizzBuzz Kata (30-45 minutes)
1. Create fizzbuzz/ directory structure
2. Set up pubspec.yaml
3. Build kata with git commits (12 commits total)
4. Write DEMO_SCRIPT.md
5. Write fizzbuzz/README.md

### Phase 2: Documentation (45-60 minutes)
1. Create TDD_REFERENCE_CARD.md
2. Create SETUP_GUIDE.md
3. Create WORKSHOP_PLAN.md (incorporate detailed schedule)
4. Enhance FACILITATOR_GUIDE.md with scripts

### Phase 3: Polish (30-45 minutes)
1. Enhance password_validator_solution.dart with comments
2. Enhance shopping_cart_solution.dart with comments
3. Create root README.md
4. Review all materials for consistency

## Success Criteria

- [ ] Facilitator can run the entire 2-hour workshop using only these materials
- [ ] Live demo kata is ready to present without preparation
- [ ] Participants have clear setup instructions and reference materials
- [ ] Solution files explain design decisions, not just implementation
- [ ] All documentation uses consistent tone and terminology

## Open Questions

None - design is approved and ready for implementation.

## Next Steps

Proceed with implementation using the three-phase approach outlined above.