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	lesson-author
description	Write concept/theory lessons for workshops
allowed-tools	Read, Write, Edit, Glob, Grep

Lesson Author Skill

Purpose: Write concept/theory lessons that introduce 1-2 new concepts in 3-5 minutes.

When to use: Workshop lesson requires teaching a concept before hands-on practice.

Prerequisites:

WORKSHOP-PLAN.md exists with lesson details
Skeleton lesson.adoc file exists
Source course lessons identified

Overview

This skill writes concept/theory lessons that:

Introduce 1-2 new concepts in 3-5 minutes
Focus on Bloom's taxonomy: remember and understand
Use examples from the workshop dataset (not generic examples)
Prepare learners for the next hands-on challenge
Follow the Learn → Do → Verify pattern (this is the "Learn")

Do NOT write challenge lessons, quizzes, or practice lessons. This skill focuses ONLY on concept/theory lessons.

Core Principle: Teaching Graph Databases

Focus on graph databases and graph technologies.

Teach Neo4j on its own merits - Explain nodes, relationships, properties, traversals, and Cypher as graph-native concepts
Use comparisons when helpful - SQL, relational, or other tech comparisons can provide context, but don't overdo it
Be factual, not salesy - Demonstrate features with real examples, stick to facts (index lookups, pointer traversal, lines of code)—do not use Big O or complexity notation (e.g. O(1), O(n), O(k)); use natural language for performance
Make it hands-on and fun - Users should enjoy building something that works
Deliver working value - By the end, they have something that demonstrates value and can be built upon

Using comparisons effectively:

Use visual diagrams (ERD vs Graph) to show structural differences when helpful
Show SQL comparison for final solution if it demonstrates dramatic value
Don't compare constantly - teach graph thinking on its own terms first
When comparing, focus on facts (lines of code, what the engine does, performance in plain language) not vague claims—do not use O(n), O(k), or other Big O notation; explain in natural language (e.g. "follows pointers in memory", "cost scales with connections traversed")

Phase 1: Understand Context (5 min)

Checklist: Gather Information

Read WORKSHOP-PLAN.md for lesson objectives
Read source course lesson(s) identified
Read previous workshop lesson (if not first)
Identify workshop dataset being used
Note building block this lesson supports
Understand what challenge follows this lesson

Key Questions to Answer

Before writing anything, answer:

What 1-2 concepts does this lesson teach?
Why now? Why does this concept come at this point in the workshop?
What comes before? What did learners just complete?
What comes after? What challenge will they do next?
How does it connect? How does this concept enable the next challenge?
What's the building block? Which transformation does this support?

Read These Files

MUST READ:
- WORKSHOP-PLAN.md (for lesson objectives)
- Source course lesson (for concept content)
- Previous workshop lesson (for context)
- CONTENT_GUIDELINES.md (for style rules)

REFERENCE:
- modules/2-foundation/lessons/1-graph-elements/lesson.adoc (example concept lesson)
- HOW-TO-BUILD-WORKSHOPS.md (methodology)

Phase 2: Plan Lesson Structure (10 min)

Checklist: Lesson Outline

Determine 1-2 core concepts to teach
Plan two-part opening (context + learning objective)
Identify examples from workshop dataset
Plan 2-3 main sections (keep it short!)
Plan summary with forward reference
Verify lesson stays under 5 minutes

Structure Template

IMPORTANT: Follow this exact structure from review-lesson-content.mdc:

Introduction (two-part pattern)
├── Part 1: Context or why this matters
└── Part 2: "In this lesson, you will learn..."

Main Content (2-3 sections)
├── Section 1: Core concept A
│   ├── Plain-language definition
│   ├── Example from workshop dataset
│   └── Why it matters for workshop goal
└── Section 2: Core concept B
    ├── Plain-language definition
    ├── Example from workshop dataset
    └── Why it matters for workshop goal

Summary
├── Bullet points with bold concepts
└── Forward reference to next lesson

What NOT to Include

❌ More than 2 concepts (too much for 5 minutes)
❌ Generic examples (movies, books) unless that's the workshop dataset
❌ "Deep dives" or advanced topics
❌ Edge cases or exceptions
❌ Tool mechanics (those go in Module 1 Lesson 3)
❌ Sales language ("powerful", "amazing", "seamlessly")
❌ AI artifacts ("comprehensive understanding", "delve into")

What TO Include

✅ 1-2 focused concepts
✅ Examples using workshop data (Northwind, etc.)
✅ Clear connection to workshop goal
✅ Plain language definitions
✅ Why each concept matters
✅ Preparation for next challenge

Phase 3: Write Opening (5 min)

Checklist: Two-Part Opening

Part 1: Context from previous lesson OR why topic matters
Part 2: "In this lesson, you will learn..."
Opening is 2-3 sentences total (not more!)
Uses "you will" not "we will" or "you'll"
No generic analogies unrelated to workshop

Opening Patterns

Pattern A: Direct Continuation

Use when building directly on previous lesson:

[.slide.discrete]
== Introduction

You learned [X] in the previous lesson. To [accomplish next step], you need to understand [Y].

In this lesson, you will learn [specific concepts].

Example:

[.slide.discrete]
== Introduction

You imported Product nodes in the previous lesson. To query those products, you need to understand how Cypher patterns work.

In this lesson, you will learn how to write basic Cypher patterns to find nodes in your graph.

Pattern B: New/Related Topic

Use when NOT directly continuing:

[.slide.discrete]
== Introduction

[Statement about primary topic and why it matters for workshop goal].

In this lesson, you will learn [specific concepts].

Example:

[.slide.discrete]
== Introduction

Relationships in a graph are first-class citizens, meaning they can store properties just like nodes. This is crucial for modeling business data accurately.

In this lesson, you will learn how to use relationship properties to represent order quantities and prices.

Opening Anti-Patterns to AVOID

❌ Combining into one sentence:

Now that you understand nodes, you'll learn about relationships and how they connect data.

❌ Generic opening without context:

In modern databases, relationships are important. This lesson covers relationships.

❌ Sales language:

Relationships are a powerful feature that will revolutionize how you think about data.

Phase 4: Write Main Content (20 min)

Checklist: Main Sections

2-3 sections with action-oriented headers
Each concept has plain-language definition
Examples use workshop dataset
Connection to workshop goal stated
Code blocks (if any) have context before and after
No more than 1-2 code examples (keep it brief)
Mermaid diagrams use circles for nodes
Screenshots included for tools

Section Structure

For each concept:

Action-oriented header (sentence case, not question)
- ✅ "Understanding graph elements"
- ✅ "How relationships connect nodes"
- ❌ "What are relationships?"
- ❌ "Relationships"
Plain-language definition (1-2 sentences)
- Explain what it is in simple terms
- No jargon without explanation
Example from workshop dataset (concrete, not abstract)
- Use Northwind, or whatever the workshop uses
- Show real data, real business scenarios
Why it matters (connection to goal)
- How does this concept enable the workshop goal?
- What can they do with this knowledge?

Code Block Pattern

CRITICAL: Every code block must follow this pattern from create-new-workshop.mdc:

[Context before - why do we need this?]

[source,cypher]
.Descriptive title describing the query
----
MATCH (n:Node) RETURN n;
----

[Explanation after - what does it do?]

Click **Run** to execute this query. [Expected result].

**Try experimenting:**
* [Suggested modification 1]
* [Suggested modification 2]

Example:

You want to see all Product nodes in your graph. In Cypher, you use the MATCH clause to find nodes by their label.

[source,cypher]
.Find all products
----
MATCH (p:Product)
RETURN p.name, p.unitPrice
LIMIT 5;
----

This query matches nodes with the Product label and returns their name and price properties.

Click **Run** to see the first 5 products. You should see items like "Chai" and "Chang" from the Northwind catalog.

**Try experimenting:**
* Change `LIMIT 5` to `LIMIT 10` to see more products
* Remove `p.unitPrice` to see only names

Numbered Annotations for Multi-Concept Code

Use when code teaches 3+ concepts:

[source,cypher]
.Query with multiple patterns
----
MATCH (c:Customer {id: 'ALFKI'})  // (1)
-[:PLACED]->                       // (2)
(o:Order)                          // (3)
RETURN c.companyName, count(o)    // (4)
----

1. **Node pattern with properties** - Find specific customer by ID
2. **Relationship traversal** - Follow PLACED relationship
3. **Chained pattern** - Continue to Order nodes
4. **Aggregation** - Count the number of orders

Click **Run** to see how many orders this customer placed.

Mermaid Diagrams

CRITICAL: Use [source,mermaid] — not [mermaid] alone. Graph nodes must be circles, not boxes. When using \n inside node labels for line breaks, surround it with spaces on both sides — Message \n role: user, not Message\nrole: user.

[source,mermaid]
----
graph LR
    Customer((Customer)) -->|PLACED| Order((Order))
    Order -->|ORDERS| Product((Product))
----

Phase 5: Write Summary (5 min)

Checklist: Summary Section

Uses [.summary] marker
Bullet points with bold concept names
Brief description after each concept
Forward reference to next lesson
No "read::" button (auto-completes)

Summary Pattern

[.summary]
== Summary

In this lesson, you learned about [topic]:

* **[Concept 1]** - [Brief description]
* **[Concept 2]** - [Brief description]

In the next lesson, you will [what comes next - usually a challenge].

Example:

[.summary]
== Summary

In this lesson, you learned about graph elements:

* **Nodes** - Represent entities in your domain (like customers and products)
* **Relationships** - Connect nodes and represent associations (like PLACED and ORDERS)
* **Properties** - Store data on nodes and relationships (like name and quantity)

In the next lesson, you will use Data Importer to create Product nodes from a CSV file.

Phase 6: Apply Style Rules (10 min)

Checklist: Technical Requirements

Apply These Rules

From .cursor/rules/asciidoc-syntax.mdc:

TWO line breaks between elements
NO MARKDOWN - only AsciiDoc
CRITICAL: Blank line required before ALL lists (after paragraphs, headers, bold text, etc.)
CRITICAL: Callouts in code use angle brackets // <1> not parentheses // (1)

From .cursor/review-lesson-content.mdc:

Two-part opening pattern
Action-oriented headers
Casual, friendly tone
Under 5 minutes
1-2 concepts max

From CONTENT_GUIDELINES.md:

Property naming (id, name not customerId, companyName)
Mermaid diagrams use circles
Code blocks have titles
Screenshots for tools

Line Break Example

= Lesson Title
:type: lesson
:order: 1

// Source: course-name/modules/1/lessons/1-lesson


[.slide.discrete]
== Introduction

Opening paragraph here.


[.slide]
== First Section

Content here.


[.slide]
== Second Section

More content.


[.summary]
== Summary

* Summary points

Notice: TWO blank lines between every section.

Phase 7: Review and Refine (10 min)

Checklist: Self-Review

Re-read the lesson aloud
Check timing (under 5 minutes to read)
Verify examples use workshop dataset
Confirm connection to workshop goal is clear
All code blocks have context before/after
Opening follows two-part pattern
Summary has forward reference
No generic examples or sales language
Proper AsciiDoc formatting throughout

Common Issues to Fix

Issue: Too long (over 5 minutes)

Fix: Cut to 1 concept instead of 2, remove deep dives

Issue: Generic examples (movies, books)

Fix: Replace with workshop dataset examples (Northwind)

Issue: No connection to workshop goal

Fix: Add "why this matters" statements

Issue: Code without explanation

Fix: Add context before and "Click Run" after

Issue: Opening doesn't follow pattern

Fix: Rewrite as Part 1 (context) + Part 2 (learning objective)

Issue: Sales/AI language

Fix: Use factual, educational language

Examples and References

Example Concept Lessons

See these real files:

modules/2-foundation/lessons/1-graph-elements/lesson.adoc
- Demonstrates: Two-part opening, Mermaid diagrams with circles, examples with Northwind data
modules/2-foundation/lessons/2-cypher-primer/lesson.adoc
- Demonstrates: Code blocks with titles, numbered annotations, experiment suggestions
modules/3-modeling-relationships/lessons/1-understanding-relationships/lesson.adoc
- Demonstrates: Building on previous lesson, connecting to workshop goal

What These Files Demonstrate

1-graph-elements/lesson.adoc:

Opens with clear goal: "By the end of this workshop, you will build..."
Defines concepts (nodes, labels, relationships) with visual diagrams
Uses Northwind data in all examples
Shows Cypher patterns progressively
Connects every concept to recommendation goal
Ends with summary + forward reference

Key patterns:

[.slide.discrete] for introduction
[.slide.col-2] for side-by-side content
Mermaid diagrams for visualizations
Callout numbering // (1) for code explanations
Clear connection to goal in every section

Output Checklist

Before marking lesson complete, verify:

References

CONTENT_GUIDELINES.md - Style guide
HOW-TO-BUILD-WORKSHOPS.md - Methodology
create-new-workshop.mdc - Workshop requirements
review-lesson-content.mdc - Lesson review checklist
how-we-teach pedagogy - PRIMM, Bloom's taxonomy