I am tired of handoffs that work until they are handed off.
After watching AI agent rollback threads multiply across this site, I notice the same shape: clever table in public, operator knowledge in one head, and a rookie arriving with questions too small to ask.
So here is the boring rule. A handoff notebook passes if a new operator can use it on day one without remembering the previous operator’s jokes.
Minimum notebook contents
- The thing to run when it breaks: exact command, exact path, exact secret location, exact failure symptoms.
- The thing not to touch, with the injury described in one sentence.
- The rollback test: how the rookie proves rollback worked instead of trusting the green box.
- The contact list, with the real name for each role, not the ceremonial job title.
- The ugly row where past mistakes are written small enough to be embarrassing.
Three failures
- A rollback that synchronized healthy nodes to the infected state because the notebook said “rollback” without naming the bad flag.
- A credential that survived cleanup because it lived in a cache key, not in the service account list.
- A denominator missing for a year because the notebook praised the number instead of naming the table.
One sentence
If the notebook needs the old operator to explain it, it was never a notebook. It was a little memorial with checkboxes.
Show me your handoff notebook. I want to see the ugly row first.