Review all question files in a lesson's questions/ folder. Checks titles, question text, answer options, hints, and solutions. Fixes issues inline and appends a WHY report.
Purpose: Review all .adoc files in the questions/ subfolder of a lesson. Fixes formatting, hint quality, and solution completeness directly in each file. Records every change with a reason.
When to use: Alongside or after the other lesson review stages. Run on any lesson that has a questions/ folder.
Input: Path to a lesson folder (e.g. asciidoc/courses/my-course/modules/1-intro/lessons/1-overview/)
Output:
questions/*.adoc — fixed in placeREVIEW-REPORT.md in the lesson folder — created or appended with a questions sectionThis review is separate from lesson content review because questions have different rules and a different purpose. The skill checks:
Check whether a questions/ folder exists:
questions/*.adoc
If no questions/ folder or no .adoc files exist, record "No questions found" in the report and stop.
Read each question file in full before making any changes.
Question titles must be in Title Case — all major words capitalised.
❌ = What is a graph database?
✅ = What Is a Graph Database?
The title should be brief (3–8 words) and describe the question topic, not repeat the question text.
Each question file must follow this structure:
[.question]
= Question Title
Brief question text here. One or two sentences maximum.
For multiple-answer questions, add: "Select all that apply."
* [ ] Option A
* [x] Option B (correct)
* [ ] Option C
* [ ] Option D
[TIP,role=hint]
.Hint
====
Hint text
====
[TIP,role=solution]
.Solution
====
Solution text
====
The question text should ask exactly one thing. If the text contains sub-bullets explaining a scenario, convert them to prose or a numbered list.
❌
Given the following:
* A graph database with 1 million nodes
* A query that scans all nodes
* No indexes defined
What will happen?
✅
A query scans all nodes in a graph database with 1 million nodes and no indexes defined. What will happen?
Only one bullet list is permitted in a question file — the answer choices. Bullet lists in the scenario or question text must be converted to prose or numbered lists.
If more than one answer option has [x], the question text must say "Select all that apply:" (or similar) before the answer list.
❌ (two correct answers, no instruction)
Which of the following are valid Cypher clauses?
* [x] MATCH
* [ ] FIND
* [x] RETURN
* [ ] GET
✅
Which of the following are valid Cypher clauses? Select all that apply.
* [x] MATCH
* [ ] FIND
* [x] RETURN
* [ ] GET
Answer options must use AsciiDoc checkbox syntax:
* [x] Answer text* [ ] Answer textQuestions should have 3–5 answer options. Fewer than 3 makes it too easy to guess; more than 5 creates cognitive overload.
Incorrect options should be plausible — things a learner who hasn't fully understood the content might reasonably choose. If any option is obviously wrong (nothing to do with the topic), flag it for improvement.
The hint guides the learner toward the answer without giving it away. It should explain the relevant concept, not tell them to "think about" something.
.Hint title❌ (tells them what to think, not helpful)
[TIP,role=hint]
.Hint
====
Think about the features and limitations of each tier.
====
✅ (explains the concept enough to guide reasoning)
[TIP,role=hint]
.Hint
====
AuraDB Free provides a fully managed Neo4j instance with limited resources at no cost, making it ideal for learning and small projects. The other tiers add features like larger storage, higher performance, or enterprise controls.
====
❌ (antagonistic or dismissive)
[TIP,role=hint]
.Hint
====
You should know this from the lesson.
====
✅ (warm and direct)
[TIP,role=hint]
.Hint
====
The lesson covered how relationships in a graph are different from foreign keys in a relational database. Consider which approach stores adjacency information directly.
====
The solution must:
.Solution title❌ (states the answer but doesn't explain why)
[TIP,role=solution]
.Solution
====
The correct answer is B.
====
✅ (states the answer and explains the reasoning)
[TIP,role=solution]
.Solution
====
The correct answer is **AuraDB Free**.
**AuraDB Free** is the only tier that is available at no cost. It provides a fully managed Neo4j instance suitable for learning and experimentation. AuraDB Professional and above include additional features and resources but require a paid subscription.
====
For multi-answer questions, bold each correct answer in the explanation:
[TIP,role=solution]
.Solution
====
The correct answers are **MATCH** and **RETURN**.
**MATCH** is the Cypher clause used to find patterns in the graph. **RETURN** specifies what data to include in the results. `FIND` and `GET` are not valid Cypher clauses.
====
Each question should test content that is explicitly covered in the corresponding lesson.adoc.
Read lesson.adoc and check whether the topic of each question is clearly explained there.
If a question tests something not covered in the lesson:
⚠️ Question "What Is a Graph Database?" tests a definition that does not appear in lesson.adoc. Either add the definition to the lesson, or move this question to the lesson where it is taught.
Do not remove questions — flag them for the author to resolve.
After fixing all question files, create or append REVIEW-REPORT.md in the lesson folder.
## Questions Review — YYYY-MM-DD
**Questions found:** 3 (questions/1-graph-elements.adoc, questions/2-cypher-match.adoc, questions/3-create-nodes.adoc)
**Status:** ✅ Complete / ⚠️ Issues remain
### questions/1-graph-elements.adoc
#### Changes Made
- **Title**: `= What is a graph database?` → `= What Is a Graph Database?` — _Question titles must be in Title Case_
- **Hint**: Replaced "Think about what makes graphs different" with explanation of graph structure — _Hint must guide reasoning, not tell learners what to think_
- **Solution**: Added bold to correct answer and added explanation of why — _Solution must state the answer AND explain the reasoning_
### questions/2-cypher-match.adoc
#### Changes Made
- **Multi-answer phrasing**: Added "Select all that apply." — _Two correct answers marked; learner must be told to select multiple_
#### Issues Requiring Manual Review
- [ ] Correct answer is `[x] MATCH` but lesson.adoc does not explain the MATCH clause — _Question tests content not covered in lesson; add to lesson or move question_
### questions/3-create-nodes.adoc
#### Changes Made
- None — no issues found
.cursor/review-lesson-content.mdc — §8 Question Reviews.cursor/technical-lesson-review.mdc — Questions section.cursor/rules/course-content-style.mdc — Quiz Guidelines.cursor/write-lesson-question.mdc — Full question authoring guide