Review a single lesson for pedagogical structure, lesson length, opening pattern, concept delivery, and scaffolding. Fixes issues inline and appends a WHY report.
Purpose: Review a single lesson.adoc for structural and pedagogical quality. Checks lesson length, opening pattern, concept delivery, Bloom's taxonomy alignment, and scaffolding. Fixes what can be fixed directly; flags issues that require content decisions.
When to use: Stage 2 of the course review pipeline. Run after grammar review.
Input: Path to a lesson folder (e.g. asciidoc/courses/my-course/modules/1-intro/lessons/1-overview/)
Output:
lesson.adoc — fixed in place where possibleREVIEW-REPORT.md in the lesson folder — created or appended with a structure sectionThis review checks:
Read lesson.adoc in full. Identify:
:type: attribute — lesson, quiz, challenge, video)../../course.adoc for module sequence if needed)Note: Apply the full checklist to theory lessons (:type: lesson). For challenge lessons (:type: challenge), focus on sections 2.3 (opening), 2.6 (scaffolding), and 2.7 (summary). Quizzes and videos have minimal structural requirements.
Identify each distinct concept or workflow introduced in the lesson. A "topic" is a section that introduces something the learner did not know before.
Rule: Maximum 3 topics per lesson.
If the lesson has more than 3 topics, flag them for splitting — do not split automatically, as this requires human judgment about how to divide the content.
Each topic section should be 150–250 words (target: 200 words).
| Lesson word count | Status |
|---|---|
| 450–750 words | ✅ Acceptable |
| < 450 words | ⚠️ May be too thin — check topic count |
| > 750 words | ⚠️ Likely needs splitting — flag for review |
Important: Do not split automatically. If a lesson is over 750 words, report the word count and topic count so the author can decide. Only flag as a definite problem if there are clearly 4+ distinct topics.
The introduction must follow a strict two-part pattern:
Part 1: Context (1–2 sentences)
Choose the appropriate pattern:
Option A — Direct continuation: If this lesson builds directly on the previous one.
In the previous lesson, you learned how to use MATCH to read data from the graph. To modify the graph, you need to learn how to create nodes and relationships.
Option B — New/related topic: If this lesson introduces something not directly built from the last.
Heap memory usage directly relates to how often the JVM must perform garbage collection. When heap usage is high, garbage collection runs more frequently, causing query pauses.
Part 2: Learning objective (1 sentence)
Must start with: In this lesson, you will learn
In this lesson, you will learn how to use the CREATE clause to add data to your graph.
❌ Combining context and objective into one sentence:
Now that you understand MATCH, you'll learn how to use CREATE to add nodes.
✅ Split into two separate sentences.
❌ Generic opening with no connection to course context:
In modern databases, data modification is important.
In this lesson, you will learn about CREATE.
✅ Replace Part 1 with something specific to what was just learned or why this topic matters now.
❌ Learning objective that doesn't start with "In this lesson, you will learn":
This lesson covers the CREATE clause.
✅ Rewrite to the standard form.
❌ Bare "You learned..." without specifying when:
You learned how to use MATCH to read data from the graph.
✅ Always specify the referent — "In the previous lesson" makes the callback concrete:
In the previous lesson, you learned how to use MATCH to read data from the graph.
❌ Explicit scaffold header:
== Building on What You Know
✅ Remove the header; fold the content into the introduction paragraph.
All == headers (other than the lesson title) must be:
| ❌ Avoid | ✅ Use instead |
|---|---|
== Node labels | == Understanding node labels |
== The CREATE Clause | == Creating nodes with CREATE |
== What Are Indexes? | == Understanding indexes |
== Core Concept 1: Relationships | == Modelling relationships |
== Why it matters | == How indexes eliminate full scans (name the specific capability) |
== Why this is important | == How short-term memory preserves conversation context (describe what it does) |
Headers must describe what the concept does, not announce that it is significant. "Why it matters" and similar phrases are empty — replace them with the specific behaviour, capability, or outcome being explained.
Do not use explicit "Core Concept N:" prefixes in headers.
If a lesson covers multiple parallel items — types, layers, stages, patterns, steps — the introduction or an overview paragraph must name all of them by name before the first section header begins explaining any of them individually.
❌ Opening says "you will learn about the three memory types" then immediately jumps to == Understanding short-term memory without ever listing what the three types are.
✅ Opening or a brief paragraph after the learning objective names all three: "The three layers are short-term memory, long-term memory, and reasoning memory."
This applies whenever the lesson has N parallel sections explaining N items and the learning objective refers to them collectively ("the three layers", "the four stages", "the five patterns"). The learner must see all N names before any section begins.
How to fix: Add a brief sentence or bullet list immediately after the learning objective that names all items. One sentence is enough: "The three layers are: short-term memory, long-term memory, and reasoning memory."
=== subsections, not bulletsWhen a lesson section introduces 3 or more parallel named items — tool types, memory layers, algorithm families, access modes — and each item requires more than one sentence to explain, use === subsections rather than a flat bullet list.
A bullet list is appropriate for items that can each be described in a single sentence. When each item has a definition, a "when to use" clarification, and possibly prerequisites or caveats, it needs its own subsection.
❌ Three tool types described as a flat bullet list where each bullet contains multiple clauses
✅ Three === subsections, one per tool type, each with a definition paragraph and a "when to use" paragraph
The overview paragraph before the subsections should still name all items (see "Preview before deep-dive" above).
A [TIP] block that contains 4 or more best-practice bullet points is functioning as primary instructional content, not a supplementary note. Promote it to a dedicated == or === section with a descriptive title and prose introduction.
TIP blocks are for one-sentence callouts, edge-case warnings, or optional follow-up references — not for the main teaching content of a section.
❌
[TIP]
.Best practices
====
* **Scope** — Keep agents focused on one task.
* **Descriptions** — State what each tool returns and when to use it.
* **Fallback** — Reserve the dynamic tool for questions no template covers.
* **Save** — Click Update after every change.
====
✅
== Best practices
Keep each agent focused on one task. A narrow scope makes tool selection easier and behavior more predictable.
* **Descriptions** — State what each tool returns and when to use it.
* **Fallback** — Reserve the dynamic tool for questions no template covers.
* **Save** — Click Update after every change.
For each concept section, verify:
To check for assumed knowledge, look at:
../../course.adoc for the prerequisite courses listedTheory lessons (:type: lesson) should target the remember and understand levels:
✅ Definitions, explanations, comparisons, identification ❌ "Build X from scratch", "Design your own Y", "Evaluate the best approach" — those belong in challenge or quiz lessons
If a theory lesson is asking learners to apply or create, flag it:
⚠️ Section "Designing your own schema" asks learners to create, which is above the remember/understand level appropriate for a theory lesson. Consider moving this to a challenge lesson.
Learning outcome bullets in course.adoc, module.adoc, and lesson openings must use verbs that reflect what the learner actually does — not verbs that imply the learner produces output for an audience.
"Describe" is wrong for product concepts. It implies the learner narrates the product to someone else, which is not the course goal. Use the correct Bloom's verb for the intended outcome:
| Wrong verb | Right verb | When |
|---|---|---|
Describe what X is | Understand what X is | Conceptual knowledge of a product or feature |
Describe how X works | Explain how X works | Mechanism or process knowledge |
Describe the steps | Complete the steps / Follow the steps | Procedural, hands-on |
❌ * Describe what Aura Agent is, when to use it, and how it works
✅ * Understand what Aura Agent is, when to use it, and how it works
❌ In this module, you will describe what Aura Agent is...
✅ In this module, you will learn what Aura Agent is...
If this is not the first lesson in the module, the opening should reference what was just learned (Option A above). Check that the reference is accurate — read the previous lesson if needed.
The summary or a closing teaser should mention what comes next. This is usually a challenge lesson.
❌ Salesy or dramatic teasers:
In the next lesson, you will discover the transformational power of graph traversals!
✅ Plain forward reference:
In the next lesson, you will use these concepts to build a query that finds all products ordered by a customer.
The lesson must end with a [.summary] section that:
[.summary] role marker[.summary]
== Summary
In this lesson, you learned about graph elements:
* **Nodes** — Represent entities such as customers and products
* **Relationships** — Connect nodes and represent associations like PLACED
* **Properties** — Store data on nodes and relationships
In the next lesson, you will use Cypher to query these graph elements.
If no [.summary] section exists, flag it (do not create it — generating the summary requires knowing the full lesson context).
After reviewing and fixing, create or append REVIEW-REPORT.md in the lesson folder.
## Structure & Pedagogy Review — YYYY-MM-DD
**Status:** ✅ Complete / ⚠️ Issues remain
### Changes Made
- **Opening**: Rewrote Part 1 to reference the previous lesson (MATCH) — _Two-part pattern: Part 1 must contextualise the current lesson_
- **Learning objective**: Changed `This lesson covers CREATE` → `In this lesson, you will learn how to use CREATE` — _Learning objective must start with "In this lesson, you will learn"_
- **Header**: `== The CREATE Clause` → `== Creating nodes with CREATE` — _Action-oriented, sentence case_
### Issues Requiring Manual Review
- [ ] Lesson word count: ~920 words across 4 topics — _Exceeds 750-word guideline; consider splitting "Advanced options" into a separate lesson_
- [ ] Summary section missing — _Add a [.summary] section with bullet-point recap and forward reference_
- [ ] Analogy in "Understanding indexes" uses a library card catalogue — _Verify this matches the course dataset context; if not, replace with an example from the course data_
.cursor/review-lesson-content.mdc — §1 Length, §3–§7 Pedagogy, Structure, Scaffolding.cursor/rules/lesson-length.mdc — Word count and topic limits