Review a single lesson for pedagogical structure, lesson length, opening pattern, concept delivery, and scaffolding. Fixes issues inline and appends a WHY report.

2026-03-2628

name	workshop-review-pedagogy
description	Review workshop content for pedagogical effectiveness
disable-model-invocation	true
allowed-tools	Read, Edit, Write, Glob, Grep

Workshop Review: Pedagogy and Flow

Purpose: Review workshop content for pedagogical effectiveness, learning progression, and instructional design.

When to use: After grammar review is complete and content is ready for pedagogical review.

Prerequisites:

Workshop content is complete
Grammar review completed
AUTHORING-PROGRESS.md shows all lessons completed

Overview

This skill performs a pedagogical review that checks:

Learning progression (scaffolding)
Building block accumulation
Learn → Do → Verify pattern
Bloom's taxonomy alignment
PRIMM framework application (where relevant)
Concept introduction and reinforcement
Duration and pacing

This review focuses on HOW WELL the workshop teaches, not grammar/formatting.

Phase 1: Pre-Review Setup (10 min)

Checklist: Preparation

Read WORKSHOP-PLAN.md for intended progression
Read HOW-TO-BUILD-WORKSHOPS.md for methodology
Read how-we-teach pedagogy lesson
Map out all lessons and types
Identify building blocks
Create review tracking document

Read These Files

MUST READ:
- WORKSHOP-PLAN.md (intended design)
- HOW-TO-BUILD-WORKSHOPS.md (methodology)
- asciidoc/courses/how-we-teach/modules/1-introduction/lessons/2-pedagogy/lesson.adoc
- CONTENT_GUIDELINES.md

REFERENCE:
- All lesson.adoc files in workshop
- All module.adoc files

Create Tracking Document

Create PEDAGOGY-REVIEW-PROGRESS.md:

# Pedagogy Review Progress

**Workshop:** [Name]
**Reviewer:** Pedagogy Review Skill
**Date:** [Date]

## Overall Structure

**Modules:** [N]
**Lessons:** [N] total ([X] required, [Y] optional)
**Duration:** [X] hours core, [Y] hours with optional

## Building Block Progression

- [ ] Module 2: "[Building block 1]" ✓
- [ ] Module 3: "[Building block 2]" ✓
- [ ] Module 4: "[Building block 3]" ✓
- [ ] Module 5: "[Final integration]" ✓

## Review Checklist

### Module 1: [Name]
- [ ] Lesson 1: Pedagogical review
- [ ] Lesson 2: Pedagogical review
- [ ] Lesson 3: Pedagogical review

[Continue for all modules...]

## Issues Found
- Issue: [Description]
- Issue: [Description]

## Review Complete
- Scaffolding verified: Yes/No
- Building blocks stack: Yes/No
- Duration realistic: Yes/No

Phase 2: Workshop-Level Review (30 min)

Checklist: Workshop Structure

First lesson is workshop overview
Module 1 is setup/introduction
Building blocks clearly defined
Building blocks stack progressively
Each module has Learn → Do → Verify pattern
Optional lessons marked and positioned correctly
Final lesson triggers completion modal
Total duration matches target (2 hours core)

Workshop Structure Validation

Required structure:

Module 1: Setup and Introduction (15-20 min)
├── Lesson 1: Workshop Overview (REQUIRED - explains goal)
├── Lesson 2-3: Environment setup
└── Lesson 4: Tool overview (SOURCE OF TRUTH for mechanics)

Modules 2-N: Building Blocks (20-30 min each)
├── Learn: Concept lesson
├── Do: Challenge lesson
├── Verify: Validation/query lesson
└── Practice: Optional practice (marked :optional: true)

Final Module: Integration and Review (15-20 min)
├── Integration lesson or final query
├── Knowledge check quiz (REQUIRED)
└── Triggers completion modal

Check:

Does Module 1, Lesson 1 explain what will be built?
Does each module complete a building block?
Do building blocks stack (each builds on previous)?
Are optional lessons marked :optional: true?
Does final lesson trigger completion (quiz or questions)?

Phase 3: Building Block Review (20 min)

Checklist: Building Block Progression

Each module states its building block
Building blocks are concrete and measurable
Building blocks stack progressively
No orphaned concepts (all lead somewhere)
Final module combines all blocks

Building Block Pattern

Verify each module completes a clear transformation:

Module 2: "Products exist in graph" ✓
└─> Module 3: Uses products, adds "Customer→Order path" ✓
    └─> Module 4: Uses both, adds "Customer→Order→Product path" ✓
        └─> Module 5: Combines all for "Recommendation query" ✓

Check:

Each challenge lesson states what building block it completes
Each validation lesson references the building block
Module overviews state what will be added
Building blocks are cumulative (not independent)

Example good building block markers:

This completes **Building Block 1**: "Products exist in the graph" ✓

This completes **Building Block 2**: "Customer→Order path complete" ✓

Issues to flag:

Building block not stated
Building blocks don't stack
Module doesn't add to previous work
Final module doesn't integrate all blocks

Phase 4: Learn → Do → Verify Pattern Review (Per Module)

Checklist: Pattern Compliance

Concept lesson (Learn) comes before challenge
Challenge lesson (Do) applies the concept
Validation lesson (Verify) proves the value
Gap between Learn and Do is minutes, not modules
Optional practice (if present) comes after Verify

Ideal Pattern

Module N: [Building Block]
├── Lesson 1: [Concept] (Learn) - 3-5 min
│   └─> Teaches 1-2 concepts
├── Lesson 2: [Challenge] (Do) - 7-12 min
│   └─> Applies concepts from Lesson 1
├── Lesson 3: [Validation] (Verify) - 3-5 min
│   └─> Queries what was built in Lesson 2
│   └─> Shows SQL comparison
└── Lesson 4: [Optional Practice] - 5-15 min (optional)
    └─> Additional practice on same structure

Check:

Does concept lesson prepare for the challenge?
Does challenge apply what was just taught?
Does validation query what was just built?
Is the gap small (same module)?

Issues to flag:

Concept taught but not applied
Challenge without preceding concept
Validation without preceding challenge
Large gap between Learn and Do (multiple modules)

Phase 5: Lesson-Level Pedagogical Review (Per Lesson)

Checklist: Lesson Pedagogy

Appropriate length for type (concept: 3-5 min, challenge: 7-12 min)
Blooms taxonomy level appropriate (concept: remember/understand, challenge: apply)
Scaffolding from previous lesson
Introduces no more than 1-2 new concepts (for theory lessons)
Examples use workshop dataset (not generic)
Connection to workshop goal is clear
Prepares for what comes next

Theory/Concept Lesson Review

For each concept lesson, verify:

Opening scaffolding:

References what was learned previously (if not first lesson)
States what will be learned in this lesson
Two-part pattern (context + learning objective)

Content:

1-2 concepts max (not 5-6)
Plain language definitions
Examples from workshop dataset
Connection to workshop goal stated
Bloom's taxonomy: remember/understand (not apply/analyze)

Summary:

Bullet points with bold concepts
Forward reference to next lesson

Issues to flag:

Too many concepts (cognitive overload)
Generic examples (movies, books) instead of workshop data
No connection to workshop goal
Missing scaffolding from previous lesson
Wrong Bloom's level (asking them to "build" in theory lesson)

Challenge Lesson Review

For each challenge lesson, verify:

Structure:

Clear challenge statement upfront
States building block completion
References tool mechanics (Module 1 Lesson 3)
Step-by-step instructions
Verification files present (verify.cypher, solution.cypher)

Pedagogy:

Applies concept from previous lesson
Hands-on (learners DO something)
Automated verification gives feedback
Snapshot option for skip-ahead
Bloom's taxonomy: apply

Connection:

Challenge references preceding concept lesson
Building block marker present
Next lesson will validate what was built

Issues to flag:

Challenge without preceding concept
No verification files
Repeats tool mechanics (should reference Module 1 Lesson 3)
Doesn't complete a building block
No connection to previous/next lessons

Validation Lesson Review

For each validation lesson, verify:

Structure:

Queries what was just built
2-4 business questions
SQL comparisons for each query
Metrics table (lines, JOINs, complexity)

Pedagogy:

Proves value with concrete comparisons
Business questions (not abstract queries)
Progressive complexity
Connection to workshop goal

SQL Comparisons:

Shows SQL side-by-side with Cypher
Fair comparison (not intentionally bad SQL)
Concrete metrics (4 lines vs 8 lines, 0 JOINs vs 3 JOINs)
Explains WHY graph is better for THIS pattern

Issues to flag:

Queries data not yet built
No SQL comparisons
Vague advantages ("faster" without specifics)
Abstract queries (not business questions)
Missing connection to workshop goal

Optional Practice Lesson Review

For each optional practice lesson, verify:

Metadata:

Marked with :optional: true

Opening:

Explicitly addresses both paths (skip or practice)
States who should do it (beginners) and who can skip (advanced)
Connects to upcoming concept

Content:

3-5 progressive exercises
Each has collapsible solution
Solutions include explanations
"Try experimenting" suggestions

Issues to flag:

Not marked :optional: true
Doesn't address both learning paths
Too few exercises (< 3)
Solutions without explanations
No connection to upcoming concept

Quiz Lesson Review

For each quiz lesson, verify:

Metadata:

:type: quiz
:sequential: true (if questions build on each other)

Questions:

8-12 questions total
Cover concepts from all modules
Use [.question] marker (NOT .freetext)
Each has 4 answer options
Each has hint and solution

Pedagogy:

Tests understanding (not trivia)
Wrong answers are plausible
Hints guide without revealing
Solutions explain why answer is correct
Solutions reference module where taught

Final Lesson:

If this is final lesson: triggers completion modal
Summary has congratulations
Next learning steps provided

Issues to flag:

Too few questions (< 8)
Questions test trivia (not understanding)
Wrong marker (.freetext instead of .question)
Missing hints or solutions
Final lesson doesn't trigger completion

Phase 6: Scaffolding and Progression Review

Checklist: Scaffolding

Each lesson builds on previous
No sudden difficulty spikes
Prerequisites clearly stated (workshop level)
Concepts introduced before application
Vocabulary defined before use

Scaffolding Validation

For each lesson, check:

Does it reference what came before?
- Concept lessons: "You learned [X] in the previous lesson"
- Challenges: "Using [concepts from previous lesson]"
- Validations: "You just built [X], now query it"
Does it prepare for what comes next?
- Summary: "In the next lesson, you will..."
- Forward references are accurate
Is the difficulty progression smooth?
- Simple concepts → Complex concepts
- Single-hop → Multi-hop queries
- Basic patterns → Advanced patterns

Issues to flag:

Lesson doesn't reference previous work
Forward reference is inaccurate
Sudden difficulty spike
Vocabulary used before definition
Concept applied before taught

Phase 7: Duration and Pacing Review

Checklist: Duration

Each lesson duration is realistic
Module durations add up correctly
Total core path ≈ 2 hours (target: 1.5-2.5 hours)
Optional lessons add 30-60 minutes
Pacing is balanced across modules

Duration Guidelines

By lesson type:

Concept lesson: 3-5 minutes
Challenge lesson: 7-12 minutes
Validation lesson: 3-5 minutes
Optional practice: 5-15 minutes
Quiz: 5-10 minutes

By module:

Module 1 (Setup): 15-20 minutes
Building block modules: 20-30 minutes each
Final module: 15-20 minutes

Total workshop:

Core path: 2 hours (target: 100-140 minutes)
With optional: 2.5-3 hours

Issues to flag:

Individual lesson too long (> 15 min for any lesson)
Module too long (> 40 min)
Total duration off target (< 90 min or > 180 min for core)
Pacing unbalanced (one module 45 min, another 10 min)

Phase 8: Connection to Workshop Goal Review

Checklist: Goal Connection

Workshop goal stated in overview
Each module connects to goal
Each lesson explains how it enables goal
Building blocks stack toward goal
Final lesson achieves the goal

Goal Connection Validation

Check each lesson for:

Does it state WHY this matters for the goal?
- Concept lessons: "This concept is needed for [goal]"
- Challenges: "This building block enables [goal]"
- Validations: "This pattern is used in [final goal]"
Can you trace from lesson to final goal?
- Lesson → Building Block → Workshop Goal

Example good connections:

You can now traverse Customer → Order → Product paths.

To build a recommendation query, you'll extend this pattern: find customers who bought similar products, then recommend products they haven't purchased yet.

This multi-hop traversal pattern is the foundation for collaborative filtering.

Issues to flag:

Lesson doesn't explain why it matters
Unclear how lesson enables goal
Orphaned concepts (not used in goal)
Goal never actually achieved

Phase 9: PRIMM Framework Review (For Challenges)

Checklist: PRIMM Application

Predict: Challenge states what will be built
Run: Hands-on task with verification
Investigate: Validation queries what was built
Modify: Optional practice varies the pattern
Make: Learners build their own (in challenges)

PRIMM Progression

Ideal flow:

Predict (Concept lesson): "You will build X"
Run (Challenge lesson): Build X with guidance
Investigate (Validation lesson): Query X, understand how it works
Modify (Optional practice): Variations on X
Make (Later challenges): Build similar things independently

Check:

Does workshop move from "Not mine" → "Mine" → "All mine"?
Do later challenges require less guidance?
Are learners gaining agency over time?

Issues to flag:

Always hand-holding (no agency gained)
No opportunity to modify/experiment
Jump from guided to independent too quickly

Phase 10: Final Pedagogical Report

Create Review Summary

Update PEDAGOGY-REVIEW-PROGRESS.md with results:

# Pedagogy Review Complete

**Workshop:** [Name]
**Date Completed:** [Date]

## Summary Assessment

### Overall Structure: ✅ Pass / ❌ Fail
- First lesson is overview: [Yes/No]
- Building blocks stack: [Yes/No]
- Learn → Do → Verify pattern: [Yes/No]
- Final lesson triggers completion: [Yes/No]

### Scaffolding: ✅ Pass / ❌ Fail
- Lessons build on previous: [Yes/No]
- Smooth difficulty progression: [Yes/No]
- Concepts before application: [Yes/No]

### Duration: ✅ Pass / ❌ Fail
- Core path ≈ 2 hours: [Actual: X hours]
- Individual lessons appropriate: [Yes/No]
- Pacing balanced: [Yes/No]

### Goal Connection: ✅ Pass / ❌ Fail
- Goal clearly stated: [Yes/No]
- All lessons connect to goal: [Yes/No]
- Goal achieved in final lesson: [Yes/No]

## Issues Found

### Critical Issues (Must Fix)
1. [Issue description]
2. [Issue description]

### Moderate Issues (Should Fix)
1. [Issue description]
2. [Issue description]

### Minor Issues (Nice to Fix)
1. [Issue description]
2. [Issue description]

## Recommendations

1. [Recommendation]
2. [Recommendation]
3. [Recommendation]

## Ready for Next Review Phase

✅ Pedagogy review complete

**Next step:** Use `workshop-review-technical` skill for technical accuracy review.

References

HOW-TO-BUILD-WORKSHOPS.md - Workshop methodology
how-we-teach pedagogy - PRIMM, Bloom's, principles
CONTENT_GUIDELINES.md - Workshop patterns
.cursor/review-lesson-content.mdc - Lesson review checklist