Back to the lesson·Lesson 7 of 8·Someone else runs it
Written for someone with your job and none of your context
The same deck as the downloads, rendered as a page. Start the slideshow to present it full screen — arrow keys or a click advance one slide, Escape leaves.
What this lesson covers
- What a handover is for
- The seven sections
- Why section 4 is the whole document
- Section 6, and why it is not defensive
- Handover is not a document, it is a period
- What to write as you go
- The README and the handover are different documents
- Report it whole
- What comes next
Speaker notes
A handover is not a description of the code. It is the list of things you know that are nowhere in the repository — why that column is dropped, who to email when the export stops, and which number in the report someone will challenge.What a handover is for
- Not "here is the code" — the code is in the repository and a competent successor can read it.
Speaker notes
Not "here is the code" — the code is in the repository and a competent successor can read it. A handover is the part that is not in the repository, and it is almost entirely a list of decisions and relationships. The test: your successor gets the monthly export, it looks wrong, and they have to decide what to do. Everything they need for that is what the document contains.The seven sections — Example (cont.)
# Handover: nutrition surveillance analysis Written 2026-03-14 by [name], for whoever holds this next. ## 1. What this produces, and who reads it A quarterly GAM estimate by commune, in the cluster report and the district health office's monthly pack. The cluster coordinator reads the commune table first and asks about anything above 10%. ## 2. Run it uv sync && uv run python run.py Takes about four minutes. Outputs land in outputs/ and are safe to delete. ## 3. Where the data comes from, and who to ask data/raw/muac-screening-YYYY-MM.csv — exported from the screening database on the 5th of each month by [name, role, email]. If it does not arrive by the 10th, that is who to chase; it has been late three times in two years and theThe seven sections — Example (cont.)
cause was a permissions change each time. ## 4. Decisions that are not obvious from the code - Commune names arrive spelled four ways. Normalisation is in src/clean.py. Ungrouped, the worst commune splits into four fragments and none looks alarming, which is how this went unnoticed for two rounds. - Children with no age recorded (about 2%) are excluded from the age- disaggregated table but kept in the total. The cluster agreed this in March 2025; the alternative was excluding them everywhere, which moved the headline by 0.4 points. - MUAC is the case definition, not weight-for-height. This is a screening dataset and there are no heights. ## 5. What breaks, and what it looks like - A new water_source code stops the pipeline with "Unknown water_source values". It is usually a form change; map it in src/clean.py and tellThe seven sections — Example (cont.)
[name]. - A row count outside 2,000-3,000 stops it. Usually a truncated download. - If the report renders but a commune is missing, screening did not happen there; that is real and should be stated in the narrative. ## 6. What gets challenged The commune ranking. Eleven of eleven adjacent communes have overlapping intervals, so the chart supports "these three are above the district median" and does not support ranking one commune against its neighbour. The caption says so; keep it there, because it comes up every quarter. ## 7. What I would do next The screening register has no follow-up measurement, so the MUAC 125mm eligibility threshold cannot be evaluated as a discontinuity design. Adding an eight-week re-measurement on a sample of children just above the cut-off would make it estimable. I raised this in January; it is not funded.The seven sections
- Sections 4 and 6 are the ones that cannot be reconstructed — Everything else a successor could work out in a week
Speaker notes
Sections 4 and 6 are the ones that cannot be reconstructed. Everything else a successor could work out in a week.Why section 4 is the whole document
- Every exclusion, recode and threshold in the pipeline was a decision — and the code records what was decided while…
Speaker notes
Every exclusion, recode and threshold in the pipeline was a decision, and the code records what was decided while losing why. A successor readingdf = df[df.age <= 20]knows what it does and not whether they may change it.Why section 4 is the whole document — In Python
# Excluded: 14 children with recorded ages above 20 years in an under-5 # screening. These are data-entry errors (the age field accepts free text). # Agreed with the screening lead 2025-03; they are excluded everywhere rather # than corrected, because we cannot tell 2 from 20 from 12. survey = survey[survey["age_months"] <= 60]Why section 4 is the whole document — In R
# The comment is the handover. Write it when you make the decision.Why section 4 is the whole document
- Write the comment when you make the decision — not at handover time
Speaker notes
Write the comment when you make the decision, not at handover time. At handover time you will remember the decisions and not the reasons, which is exactly backwards.Section 6, and why it is not defensive
- Name the numbers that get challenged and what the answer is — Every recurring analysis has two or three, and a…
- This is institutional memory, and it is the first thing lost in a handover — It is also the cheapest to write down:…
Speaker notes
Name the numbers that get challenged and what the answer is. Every recurring analysis has two or three, and a successor who does not know them will either capitulate to a challenge that has already been settled or re-open an argument that was closed. This is institutional memory, and it is the first thing lost in a handover. It is also the cheapest to write down: three bullets.Handover is not a document, it is a period
- Have them run it while you are still there — Not watch you run it — run it themselves, from a fresh clone, on their own…
- Have them produce one real output — The next monthly report, not a test run
- Leave the questions channel open for one cycle — One quarter, one month, whatever the cadence is
Speaker notes
The document is necessary and it is not sufficient. Have them run it while you are still there. Not watch you run it — run it themselves, from a fresh clone, on their own machine, with you available. Everything that fails is a gap in the repository or the document, and it is the only way to find those gaps. Have them produce one real output. The next monthly report, not a test run. A successor who has produced one report has done the job once. Leave the questions channel open for one cycle. One quarter, one month, whatever the cadence is. Most of what they need to ask arrives at the moment it first breaks.What to write as you go
Write it When The decision comment When you make the decision The "what breaks" entry The first time it breaks The "what gets challenged" entry The first time it is challenged The contact and the cadence When you set it up The "what I would do next" Whenever you think of it Speaker notes
The handover document is much easier if it is not written at handover time.What to write as you go
- Keep it in the repository, in
HANDOVER.md, in version control — A handover in someone's email is a handover to one…
Speaker notes
Keep it in the repository, inHANDOVER.md, in version control. A handover in someone's email is a handover to one person.- Keep it in the repository, in
The README and the handover are different documents
README Handover For anyone who opens the repository For the person who takes it over What it produces, how to run it Why it is the way it is Stays short Can be long Updated with the code Updated when a decision is made The README and the handover are different documents
- A README that has grown into a handover has stopped being read — which loses both
Speaker notes
A README that has grown into a handover has stopped being read, which loses both.Report it whole — Example
Continuity HANDOVER.md documents the analysis decisions, the upstream contacts and cadence, the known failure modes, and the findings that are routinely challenged. It is version-controlled and was last reviewed 2026-03-14. Every exclusion and recode in src/ carries a comment giving the reason and the date it was agreed. The incoming analyst ran the March cycle end-to-end from a fresh clone, with the outgoing analyst available. Two gaps were found and closed: the screening database export permission, and an undocumented commune-name variant.Report it whole
- The last paragraph is the evidence that the handover happened — A handover document nobody has executed is a document…
Speaker notes
The last paragraph is the evidence that the handover happened. A handover document nobody has executed is a document that has never been tested, and the two gaps it found are what it exists to find.What comes next
- The last lesson turns the course on this platform.
Speaker notes
The last lesson turns the course on this platform. Every claim it has made — read-only raw data, a pinned environment, deterministic output, checks that fail loudly, one template many outputs — is checkable in this repository, and the lesson is a tour of where.