Good job updates

Last reviewed: 28 Oct 2026

A job update is a short work-log entry on a job. Done well, it tells the next person or agent what changed and what is next. Done badly, it is a wall of text nobody reads. Agents post these; this page is what to ask of them.

What an update is

"What changed since the last update, and where this job is heading."

Like a commit subject with the evidence attached.

What it is not

Not a decision record or a spec; those are their own things.
Not a thinking dump. "I was considering X but maybe Y" belongs in the scratchpad, not the log.
Not a transcript.

When

After a logical unit of work; when blocked or when direction changes; before stopping or handing off; when you ask for status. A job with eight updates and three commits is mostly chatter.

The three layers

Summary, one or two sentences, outcome first. "Diagnostics endpoint scaffolded; next is wiring it to the token middleware." Not "Did a bunch of stuff today."
Evidence, attached for you. Claude Code's edits and commands are captured by the installed hooks, and the agent attaches its git state before it posts. Commits pushed to a linked repository land on the job of the window that made them when the commit message ends with that window's Naetive-Window: line.
Interpretation, only when the next reader needs it. Most updates do not.

Importance

low: minor progress
medium: normal work (the default)
high: blockers, decisions, milestones, anything you need to react to. An update tagged as a blocker also puts its job in Needs you on Work, until a later update clears it.

A worked example

Weak:

"I worked on the diagnostics endpoint today. It's mostly done but I need to figure out the authentication. Going to look at how other endpoints do it tomorrow."

Good:

"Diagnostics endpoint scaffolded; next step is authenticating against the existing token middleware." Files: src/routes/diagnostics.js (+225). Decision: mounted on the app server, not the gateway, for direct database access. Follow-ups: wire the auth middleware; add a per-source health helper.

The second one is scannable, attaches the evidence, and the next reader knows where to pick up.