Notes for My 2 AM Self: Handoff Notes

What Is It (In One Sentence)

Document "what was done, why it was done, and where the next risks lie" so that any offline reader—especially your future self—can pick up directly without digging through chat logs.

When to Use It (4 Scenarios)

- **Handoffs across days/weeks**: You worked on a service all day and need to hand it off to a colleague tomorrow morning. If they need to "open and continue" in the afternoon, a handoff note readable in 3 minutes is far cheaper than an hour of screen sharing.

- **Juggling two or three parallel tasks alone**: CI fixes aren’t merged, queue bugs remain unsolved, and you switch contexts daily. Without a "scene reconstruction" checklist, you spend 20 minutes re-establishing context every time you switch back.

- **Handing code/config to AI or generic scripts**: Generic tools lack your implicit context; without instructions, they silently break conventions, turning tests red overnight. Dropping a `HANDOFF.md` in the root directory is cheaper than fixing 10 bugs afterward.

- **You have a headache and just want to "clock out for tonight"**: Spending 30 minutes on notes saves your life compared to "sorting it out tomorrow"—because the you at 8 AM tomorrow is a different brain from the you at 11 PM tonight.

When Not to Use It (Counterexamples)

- **Single, single-file, semantically clear changes** – A `commit message` is sufficient; don’t create a separate document for a one-line change.

- **Post-incident reviews** – That’s what postmortems are for; they have their own templates and audience. Stuffing "handoff notes" into incident records only confuses both.

- **Your team already has a full set of documentation/issue standards** – Use them; don’t create a parallel track. Your goal is to reuse existing structures, not add another layer.

- **You are still in the "uncertain draft" phase** – If the conclusion might be overturned within a few days, don’t write notes yet. Just label it as "still under verification."

Practical Checklist (5-Part Structure, Each Part Under 30 Words)

1. Current Status     —— Replayable in three sentences: "Current step + evidence"
2. Why This Approach  —— One sentence on what ideas/plans you rejected
3. Next Steps         —— Specify required people/tools + verification method
4. Unresolved Risks   —— Max two items; label as "likely to bite / occasionally bites"
5. Contact a Human    —— Fallback path: "If X happens, ask Y first"

**That’s it. A reader finishes the entire note in 3 minutes; 80% of readers finish after reading just 10 lines.** If you can’t explain an item clearly within 30 words, it’s genuinely unclear—force yourself to rewrite it or cut it.

**Where to Put It**: Place it where the next reader will "open it"—`HANDOFF.md` in the code root, the first Release Note item in the branch description, or a pinned message in the group chat. Burying it deep in a wiki with triple breadcrumb trails is equivalent to not writing it at all.

Common Pitfalls (Gotchas)

- **Stopping halfway**: Half-finished notes hurt readers most—seeing "TODO: add later" makes them leave. Either finish it or clearly label it "This is a draft, missing section N"; don’t make readers guess.

- **Dumping all background at the start**: Background info is old news and not worth a line. The first sentence must tell the reader "where things stand right now."

- **Hiding the verification path**: Saying "tests passed after changes" isn’t enough; show the command and a snippet of the green output (screenshots of short lines work). The most expensive part for readers is "reproducing it in their fresh environment to verify it’s truly green."

- **Blaming tone**: "Why didn’t X check this yesterday?"—keep such statements out of handoff notes. You are writing for the person taking over, not for a judge.

- **Accumulating versions**: 5 lines today, 5 more tomorrow, more the next day... After two weeks, no one reads the 40-line mess. Archive old versions, keep only the latest; "Current Status" must never exceed 5 sections.

A Real Lesson

Two years ago, I worked late into the night fixing a low-level protocol issue. Exhausted, I skipped writing notes and handed the service off to a colleague. Three weeks later, he asked on Slack, "How exactly is the return value calculated for the XX replay window?" The answer was clearly written in the double-byte v2 comment of my commit. He spent two hours dissecting the entire protocol spec to figure it out. Since then, I’ve adopted one hard rule: **Any task spanning across days is incomplete without a 5-part note**. Two months later, I rarely faced colleagues asking pointedly, "Why did you change it so strangely back then?"

---

**cover-theme:** engineer writing sticky notes at late night