Turn a lesson or a change into an exercise someone actually completes.
Most course exercises fail the same way. They restate the lesson with the nouns swapped, so finishing one proves nothing and teaches nothing. The learner already saw it done and is now doing it again with a different variable name.
A good exercise sits just past the lesson. It uses what was taught and needs one thing that was not spelled out. It also has a clearly wrong answer that a learner can reach honestly. The flaws beat of a lesson is usually where it comes from, because those are real gaps in real code.
Steps
- [ ] 1. Find the source
- [ ] 2. Pick the gap
- [ ] 3. Build the starter state
- [ ] 4. Write the solution first
- [ ] 5. Write the brief and the rubric
- [ ] 6. Hand it back
1. Find the source
Look in docs/lessons/. If no lesson exists, follow references/shared/change-analysis.md to scope and read the change.
2. Pick the gap
Read references/exercise-design.md before choosing. It covers what separates an exercise from a restatement.
The best candidates, in order.
A flaw the lesson named and left unfixed. Already motivated, already scoped, and the learner knows why it matters. The missing index and the missing pagination from a lesson's flaws beat are exercises sitting in plain sight.
The next obvious feature. The thing a user of the app would ask for next.
A constraint change. Same feature, one rule flipped. Replies were one level deep. Now allow two, and find out what breaks.
Avoid anything the lesson fully demonstrated, and anything needing a tool or a service the learner does not already have set up.
3. Build the starter state
The learner starts from working code with a hole in it, not from an empty file.
Keep the types, the tests, the imports, and the surrounding code. Remove the implementation. A function signature with a comment that states its job beats a blank file. A blank file makes people quit before they learn anything.
Write the starter as a patch or a set of files under docs/challenges/NN-slug/starter/. Say plainly which files to touch and which to leave alone, since guessing at scope is not the skill being taught.
4. Write the solution first
Write it before the brief. Two reasons, both practical.
The exercise gets scoped honestly, because an exercise written without a solution is always harder than the author thinks. And the rubric comes from what the solution actually does rather than from what the author hoped it would.
Put it in docs/challenges/NN-slug/solution/. If the solution needs anything the lesson did not cover, either cover it in the brief or pick a different gap.
5. Write the brief and the rubric
The brief states what to build, where, what must keep working, and what is out of scope. It does not include hints. A time estimate helps, and honest is better than encouraging.
The rubric is what a correct solution does, in checkable terms. Not "clean code". Something a learner can verify alone. The reply appears without a refresh, the deleted parent case returns a message rather than a five hundred, the query no longer scans the whole table.
Three to five items. More than five and nobody checks them.
Include the wrong answer that a reasonable person reaches, and why it is wrong. That is the most valuable part of the whole artifact, because the learner who took that path is the one who needs the explanation.
6. Hand it back
Report the paths, the estimated time, and which lesson it follows.
Reference files
references/exercise-design.md: what makes an exercise teach rather than restatereferences/shared/simplified-english.md: ASD-STE100, the sentence and vocabulary rulesreferences/shared/voice.md: house style, all mediumsreferences/shared/change-analysis.md: scoping a diff, reading it, verifying claims