status-updates git:20260720.adc529aA

Immutable. This exact content is served forever at /api/v1/blob/feb9d2f9f484f205.

---
name: status-updates
description: Write status updates with progress, risk, and asks calibrated to the audience, honoring the no-surprises rule. Use when reporting project status upward or fixing updates nobody reads.
---

# Status updates

A status update manages other people's models of your work. The
test: after reading, does the audience know whether to relax, help,
or escalate: in under a minute?

## Method

1. **Lead with the state, in one line.** Green/yellow/red (or
   on-track/at-risk/blocked) plus the headline: "Yellow:
   migration on track for the 15th, but vendor API limits may
   slip the final cutover a week." Readers triage from line
   one; burying the state under narrative is how yellow
   projects surprise people as red (see exec-briefing for
   the highest-altitude version).
2. **Structure as progress / plan / risks / asks.** What
   moved since last update (outcomes, not activity: "cutover
   rehearsed clean" beats "worked on migration"); what
   happens next period; what could go wrong and what you are
   doing about it; what you need from whom, by when.
   Empty risk sections on hard projects read as not looking
   (see tradeoff-analysis instincts).
3. **Enforce no-surprises upward.** Bad news travels *ahead*
   of the written cadence: the moment a date is credibly at
   risk, the stakeholder hears it directly with your
   mitigation plan: never first in a status doc, never first
   in the meeting (see roadmap-communication's
   change-loudly rule). Surprise erodes more credibility
   than the slip itself.
4. **Calibrate altitude per audience.** Team: task-level in
   the standup channel. Peers/partners: dependency-relevant
   milestones. Executives: outcome, confidence, date, ask:
   three sentences (see six-pager-narrative and
   exec-briefing for the formats above this). One underlying
   truth, several altitudes: divergent stories eventually
   collide (the roadmap-communication rule again).
5. **Quantify against the baseline.** "12 of 30 services
   migrated, was 8 last week, pace holds the date" gives the
   reader trend and confidence; adjectives ("good progress")
   give them nothing to verify (see product-metrics'
   definition ethic in miniature). Link the dashboard for
   the curious; do not paste it.
6. **Keep the cadence and keep it short.** Same day, same
   format, weekly for most projects; ten minutes to write
   from notes kept during the week (see
   decision-journals). An update that takes an hour to
   write is doing archaeology that running notes should
   have prevented; an update skipped two weeks running is
   how projects go dark (see one-on-one-meetings' channel
   separation: status lives *here*, not in the 1:1).

## Boundaries

- Status theater (long updates optimized to look busy)
  wastes the channel; activity lists without outcome
  movement are the tell (see cognitive-load's ethic
  applied to prose).
- Written status does not replace the hard synchronous
  conversation when a project is truly red; it schedules
  one (see incident-commander-role's comms discipline
  for the emergency version).
- Automated dashboards report metrics, not judgment; the
  human's paragraph of "what this means and what I am
  doing" is the part that cannot be generated.