| name | review-course |
| description | Review course-level structure and metadata — lesson attributes, module organisation, course.adoc completeness, and last-lesson requirements. Run once per course before publishing. |
| allowed-tools | Read, Edit, Glob, Grep |
Review: Course Structure
Purpose: Check and fix course-level structural requirements across all modules and lessons in a course. This is a one-shot review of the whole course, not individual lesson content.
When to use: Run once on the whole course after individual lesson reviews are complete, before the course is published or moved to draft mode.
Input: Path to a course folder (e.g. asciidoc/courses/my-course/)
Output:
- Various
.adoc files fixed in place where possible
COURSE-REVIEW-REPORT.md in the course folder
Overview
This review checks:
- Lesson attributes — every lesson has
:type: and :order: matching its folder
- Question includes — every question file in
questions/ is included in lesson.adoc
- Module files — every
module.adoc has :order: matching its folder and accurate overview content
- Course file —
course.adoc has required attributes, assets, and introductory sections
- Last lesson — the final lesson forces an action (quiz or mark-as-read)
Phase 1: Discover Course Structure
Use Glob to map the course:
Glob: asciidoc/courses/[slug]/modules/*/lessons/*/lesson.adoc
Glob: asciidoc/courses/[slug]/modules/*/module.adoc
Glob: asciidoc/courses/[slug]/course.adoc
Build a list of all modules and lessons with their folder paths. Note the folder numbering (e.g. 3c-using-foo → order 3, 4-deleting-nodes → order 4).
Phase 2: Lesson Attributes
For each lesson.adoc, check:
:type: attribute
Every lesson must have a :type: attribute. Valid values:
| Value | When to use |
|---|
lesson | Default theory/concept lesson |
challenge | Learner must complete a hands-on task |
quiz | Lesson contains only questions (no instructions) |
video | Lesson contains only a video:: block |
If a lesson has no :type:, determine the correct value from its content:
- Has only a
video:: block → video
- Has questions but no instructional steps →
quiz
- Has a hands-on task with verification →
challenge
- Has instructional text →
lesson
Add the missing :type: attribute.
:order: attribute
The :order: value must match the numeric prefix of the lesson folder name.
Examples:
- Folder
1-introduction → :order: 1
- Folder
3c-using-foo → :order: 3
- Folder
4-deleting-nodes → :order: 4
Fix any mismatch.
Question file includes
For each lesson, check that every .adoc file in questions/ is included in lesson.adoc:
Glob: [lesson-folder]/questions/*.adoc
For every question file found, verify an include::questions/[filename].adoc[leveloffset=+1] exists in lesson.adoc. Add any missing includes.
Phase 3: Module Files
For each module.adoc, check:
:order: attribute
The :order: value must match the numeric prefix of the module folder name.
Fix any mismatch.
Overview content
The module.adoc should contain an accurate overview of what the module covers. Read the lesson titles in the module and compare to the module overview text.
If the overview is generic ("This module covers topics...") or does not reflect the actual lesson content, flag it for update:
⚠️ module.adoc overview does not reflect lesson content. Update to mention: [list of lesson topics].
Do not rewrite module overviews automatically — this requires content judgment. Flag only.
Phase 4: Course File
Read course.adoc and check for:
Required attributes
| Attribute | Required | Description |
|---|
:caption: | Yes | Short, succinct course description (1 sentence) |
:key-points: | Yes | 3–5 key points covered by the course |
If either is missing, flag it:
⚠️ :caption: missing from course.adoc — add a 1-sentence description of what this course teaches.
Required assets
| File | Required |
|---|
illustration.svg | Yes — course card illustration |
banner.png | Yes — course banner image |
Check whether these files exist in the course folder. If not, flag them:
⚠️ illustration.svg not found in course folder.
Required sections in course.adoc
The course file should contain:
=== What you will learn — a bulleted list reflecting the content of all modules== This course includes — a summary of what learners will find (lessons, quizzes, challenges)
If either section is missing, flag it.
If either section exists but does not accurately reflect the current course content (e.g. references modules that no longer exist, or misses newly added modules), flag it for update.
Phase 5: Last Lesson
The last lesson in the course must require an action from the learner. This triggers the completion modal and redirects to the certification.
An action means one of:
- The lesson has at least one question (the learner must answer it)
- The lesson has a
read:: button with text (the learner must click it)
If the last lesson is a theory lesson with no questions and no read:: button:
❌ Last lesson has no action. Add a read::[text][] button or a question to trigger the completion modal.
If the last lesson is marked :optional: true:
❌ Last lesson must not be optional. Remove :optional: true from the last lesson.
Phase 6: Write the Report
Create COURSE-REVIEW-REPORT.md in the course folder.
# Course Structure Review — YYYY-MM-DD
**Course:** my-course
**Path:** asciidoc/courses/my-course/
---
## Summary
- Modules reviewed: 4
- Lessons reviewed: 18
- Issues fixed: 3
- Issues requiring manual review: 2
---
## Fixes Applied
- **Lesson type**: `modules/2-querying/lessons/3-match/lesson.adoc` — added `:type: lesson` — _Every lesson must have a :type: attribute_
- **Lesson order**: `modules/3-modelling/lessons/2-relationships/lesson.adoc` — changed `:order: 3` → `:order: 2` — _Order must match folder prefix_
- **Missing include**: `modules/1-intro/lessons/1-overview/lesson.adoc` — added `include::questions/2-check.adoc[leveloffset=+1]` — _Question file existed but was not included_
---
## Issues Requiring Manual Review
- [ ] `modules/2-querying/module.adoc` overview does not reflect lesson content — _Update to mention: MATCH clause, WHERE filtering, RETURN projections_
- [ ] `course.adoc` — `:key-points:` attribute missing — _Add 3–5 key points that summarise what this course teaches_
- [ ] `banner.png` not found in course folder — _Create or add a banner image before publishing_
---
## Module Order Summary
| Module | Folder | :order: | Status |
|--------|--------|---------|--------|
| Introduction | 1-introduction | 1 | ✅ |
| Querying | 2-querying | 2 | ✅ |
| Modelling | 3-modelling | 3 | ✅ |
| Advanced | 4-advanced | 4 | ✅ |
---
## Last Lesson Check
✅ Last lesson (`modules/4-advanced/lessons/5-quiz/lesson.adoc`) has 10 questions — completion modal will trigger.
References
.cursor/review-course.mdc — original course structure checklist.cursor/course-outline-checklist.md — detailed outline requirements.cursor/course-summary-checklist.md — course summary standards
