Capture a Lesson as a Minimal Repro
A retold incident fades and drifts. A committed five-line reproducer plus the rule it violates can be replayed by any future reader and re-run when the code changes underneath it.
Procedure
- Reduce the failure to the smallest program that still fails: strip framework, config, and I/O until under about five lines.
- Save it under
lessons/YYYY-MM-DD-<slug>/repro.pywith the failure as an assertion or a non-zero exit. - Write the rule in one line in
README.md: "a float sum of money silently drifts; use integer cents". - Record the trigger and the blast radius in two fields: how it was hit, who or what it affected.
- Note the fix as a diff, then confirm the repro passes on the fixed code.
- Mark the caveat: what the repro does not cover, so readers do not over-generalise from it.
- Link it from the code it concerns, so the next editor finds it, e.g. a comment pointing at
lessons/. - Add it to
lessons/run-all.shso CI re-runs every repro and catches a regression. - Title the directory with the failing date, not the fix date, so the order of discovery is preserved.
- Keep exactly one rule per lesson; two rules in one repro make both untestable.
- Run the repro on the pre-fix commit and paste the exact error string into the README.
- Tag the lesson with the component it concerns, so it surfaces in that area of the repo.
- Keep each lesson self-contained with no imports from the app.
- Give the repro a name that states the symptom, not the fix.
- Note the environment (language version, OS) the repro needs.
- Link the repro from the postmortem so the two stay together.
Pitfalls
- A repro that needs the whole service to run, so nobody reruns it.
- Retelling the timeline instead of reducing the cause.
- An over-broad rule ("floats are bad") that the five lines do not actually show.
- Filing the lesson where the affected code cannot find it.
- A repro with no assertion, so a silent change to the output goes unnoticed.
- Combining the incident and a wish-list of adjacent fixes into one file.
- A repro that passes on a different platform than the one that failed.
- Writing the rule in jargon the next intern cannot parse.
- Forgetting to record the version or commit where the failure happened.
- A name that gives away the fix, spoiling the exercise.
- A repro that only fails on one machine with no note of why.
- A postmortem and a repro that drift apart.
Verification
python3 lessons/*/repro.py ; echo "exit=$?"
# passes when the repro exits non-zero before the fix commit and zero after it
Report to the user: the repro path, the one-line rule, and the pre/post-fix exit codes.