Write status updates and handoffs

The owner hires a team so they do not have to chase it. Your updates should let them know, at a glance, whether things are on track and whether they need to act. Your handoffs should let a teammate carry on as if they had been there. The standard: status first, change since last time, specific asks with deadlines, absolute dates, file paths that work, and nothing the reader has to decode.

When to use

• "Keep me posted." / "Where are we with X?"
• End of a task, a day or a week; a scheduled update (see schedule-recurring-work).
• You are blocked or something is going wrong.
• Handing work to a teammate, or picking it up from one.
• The owner is about to make a decision and needs the current picture.

What you need

• The goal and the deadline or target you are reporting against.
• What changed since the last update (check your notes, todo, session_search for the last update you sent).
• The facts: numbers, dates, file paths, links. Check them before writing.
• Who reads it: the owner (short, decisions), a teammate (detail, context), the whole team (brief_team).

Method

Status update

1. Lead with the status word and why. On track, At risk, Off track, or Done. Definitions:
   • On track: will hit the date, scope and budget as agreed.
   • At risk: may miss without action; you have a recovery plan or need a decision soon.
   • Off track: will miss unless something changes; a decision is needed now.
   • Done: delivered, with where it is.
2. What changed since last time. Outcomes, not activity: "Supplier comparison finished: Northline is 14% cheaper" beats "Worked on supplier comparison". Two to four lines.
3. What is next, with dates.
4. What you need from the reader, each item with a specific question, a deadline, and what you will do if you hear nothing ("If I don't hear by Thu 8 Oct 17:00, I'll go with option A").
5. Risks only if they are real and new; each with what you are doing about it.
6. When the next update comes ("Next update Friday", or "next update when the quote arrives, by Wed at the latest").
7. Length: routine updates 60 to 150 words. If you need more, the extra goes in a linked document.

Handoff

Write it so the receiver could finish the work with you unreachable. Template in references/update-templates.md:

1. Goal and definition of done (who it is for, deadline).
2. Current state: done, in progress (the exact step you stopped at), not started.
3. Where everything is: full paths, links, accounts (which connected app or which site your browser is signed in to; never passwords).
4. Next steps in order, the first one small enough to start in five minutes.
5. Decisions already made and why (so they are not reopened).
6. Open questions and who can answer them.
7. Traps: what nearly went wrong, quirks of the data or the site.
8. Put it where they will find it: a HANDOFF.md in the job folder; copy the folder or the note into ~/Desktop/Team/<job>/ if the teammate works on another computer; then send a short message with ask_teammate (or brief_team for several people) pointing at it. Ask them to confirm they have it.

Blocker or escalation

State the problem in one line, its impact (what slips, by how much), the options with your recommendation, and the decision needed by when. Raise it as soon as you know, not at the deadline.

Picking up a handoff

Read the whole note, open every file it names, run the first step, then confirm back with what you understood and any gaps.

Tools

• Chat to the owner: a short message plus show_card: note (tone: success, warning or danger to match the status) for a status line, plan for steps with owners and status, metrics for numbers against target.
• Teammates: ask_teammate for one person, brief_team for several. Keep durable team facts (decisions, conventions) in team memory with memory.
• Files: the job folder in your work space; shared work in ~/Desktop/Team/.

Output

Status update:

[On track / At risk / Off track / Done]: [one-line reason]
Since last update: [outcome 1]; [outcome 2]
Next: [step] by [Day DD Mon]; [step] by [date]
Need from you: [question] by [date]. If no answer, I'll [default].
Next update: [when]

Handoff: the HANDOFF.md from the template, plus a two-line message saying where it is.

Checks before you finish

• Status word first and it matches the facts (an unanswered decision blocking the date is At risk, not On track).
• Every ask is a question someone can answer, with a deadline and a default.
• Dates absolute with weekday checked (date -d 2026-10-09 +%A in terminal); times with time zone if readers are in different zones.
• File paths open; links work; no passwords or secrets anywhere.
• Handoff test: could the receiver start the next step without asking you anything?

Pitfalls

• Activity lists ("worked on", "looked into", "continued with"). Report outcomes and what they mean.
• Green until it's red. Flag risk early; an early At risk is worth more than a late Off track.
• Burying the ask in paragraph three. Asks go in their own labelled line.
• Relative dates ("next week", "tomorrow") that mean different things when read later.
• Repeating the same update when nothing changed. Say what you learned or what you are trying next, or say "no change" in one line and when you expect news.
• Handoffs that live only in chat. Chat scrolls away; the note goes in the job folder.
• Blame. Describe what happened and what is needed, not whose fault it was.

See also: meeting-notes-and-actions, draft-emails-for-owner, schedule-recurring-work (weekly updates on a timer).