Teach a Tool by Its Failure Modes
A flag cheat-sheet is forgotten by lunch. A tool's three most common errors, each tied to the mental model it exposes, gives the learner diagnosis instead of recall.
Procedure
- Pick the three errors a beginner actually hits, in order. For git: detached HEAD, merge conflict, and pushed-then-amended history.
- For each, reproduce it on purpose in a scratch clone:
git clone /tmp/tools-demo && cd tools-demo && git checkout HEAD~1. - Decode the message literally, then name the model it assumes: "detached HEAD means commits here are not on a branch".
- Give the safe recovery command and say who it affects:
git switch -returns to the branch, and nothing is lost if you had not committed. - Mark which errors are one-way (rewriting shared history) versus reversible, because fear is what stalls learners.
- Close each with a "you will know this is happening when..." tell, so they recognise it next time.
- Leave the scratch repo path
/tmp/tools-demoso they can break it freely. - Have them break it deliberately and recover before you move to the next mode.
- Write the three tells on one card they can keep; recall of the tell is the point, not the flag list.
- Ask the learner to cause each error themselves before you explain it.
- Keep the scratch repo disposable and note the one command that recreates it.
- Map each error to the docs page that explains it, so the learner can go deeper.
- Sequence the three errors from most to least common.
- End by showing where the docs explain each error.
- Quiz the tell, not the flag, at the end.
Pitfalls
- A command list with no failure context, remembered for a day.
- Teaching the recovery without the model, so the next variant still stumps them.
- Hiding the dangerous cases, so the learner treats all commands as equally safe.
- Using a shared repo for the deliberate breakage.
- Explaining all flags of one subcommand instead of the errors of the tool as a whole.
- Demoing on a clean repo where the error never actually appears.
- Choosing exotic errors when the common ones are the real time sinks.
- Teaching on a repo that holds uncommitted work they could lose.
- Assuming the learner's mental model of branches matches yours.
- Ordering by severity instead of frequency.
- Leaving the learner with nowhere to read further.
- Testing flag recall when the goal is diagnosis.
Verification
cd /tmp/tools-demo && git checkout HEAD~1 && git status | head -3
# passes when the learner names the state, the model, and the recovery without looking
Report to the user: the three errors, the model each exposes, and the reversible/one-way label.