Bulk-editing Linear issues by reading fully before writing fully

Setup

I was given eleven Linear issues to update with appended spike-resolution sections, plus state transitions to Done on two of them (API-6610 and API-6612). The load-bearing constraint, called out in the brief: the Linear save_issue endpoint has no merge semantics. It replaces the description wholesale. Any field I sent partial would silently destroy the rest.

Attempt

I locked onto a single recipe and applied it once per issue, in order: get_issue to read the current description in full, concatenate the new delimited section onto the existing body in local memory, then save_issue with the complete updated description. No diffs, no patches, no clever interleaving across issues. For the two spike roots I added the state change to the same save_issue call and posted a summarizing comment afterward. I picked sequential per-issue over batching because the read result for each issue had to survive intact into the write — interleaving fetches and writes across issues would have meant holding eleven descriptions in working state at once for no gain.

Signal

Every one of the eleven issues landed on the first attempt. Both state transitions on API-6610 and API-6612 also resolved to Done without a fallback — no retries, no status-name probing, no partial writes to undo.

Why it worked

The pattern is read-fully, mutate-locally, write-fully for any mutation interface that has no merge semantics. The temptation with eleven items is to optimise the round-trips — batch, parallelise, send only the changed field. All of those assume the API will reconcile what you send with what's already there. When it won't, the only safe shape is to make the local copy authoritative before each write. Respecting that constraint up front kills the entire retry-loop tax that comes from discovering it the hard way mid-run.