dev-skills

Appearance

Optimize for the Reader ​

When you learn something that changes a document, an issue, an instruction file, or code, fold it in where it belongs. The result should read as if it had been written once, by someone who knew from the start everything you know now. Don't append it to the end because that's less work for you.

Why ​

Documents and code are read far more often than they're written. Every reader of an appended amendment has to reconcile it with the text above it: which part is still true, which part the note overrides, and what the whole thing now says. The writer can do that work once; otherwise every reader does it again. So the burden belongs on the writer. It's also just polite.

Appending optimizes for the writer. Integrating optimizes for the reader.

While it's still being written, integrate ​

Until others have acted on it, a document is a draft, including while it's under review. Treat new information as a revision, not an addendum:

  • Put each fact in the section it belongs to, and restructure sections when the new fact changes their shape.
  • Rewrite sentences the new fact makes wrong. Don't leave them standing with a correction below.
  • Drop anything the new fact makes irrelevant.

❌ DON'T append the correction

Goal: Cache API responses for 24 hours.

...

Update: after review, the cache should be 1 hour, and only for unauthenticated requests.

✅ DO rewrite as if you knew it all along

Goal: Cache unauthenticated API responses for 1 hour.

The same goes for a reply to review feedback: fix the thing itself, then reply saying what changed. The fix lives in the artifact, not in the thread.

Once others have acted on it, supersede ​

Once people have built on a document, its history matters. A plan that PRs were opened and merged against is part of the record, and erasing it would leave those PRs pointing at something that no longer exists. When that plan turns out to be wrong:

  1. Write the new version as a complete, self-contained document. A reader of it should never need the old one.
  2. Put a notice at the very top of the old version saying it's superseded, with a link to the new one. The top, because a reader decides in the first line whether to keep reading.
  3. Leave the rest of the old version intact.

✅ DO redirect the reader before they invest in stale text

Superseded by Plan v2. This plan was executed through #812 and #815, then found to rely on the retired sync API. Read v2 instead.

The principle hasn't changed: the writer spends a minute so no reader spends ten reading something that's wrong.

What stays append-only ​

Some records exist to show what happened, in order. Their history is the point, so add to the end and never rewrite:

  • Changelogs and release notes
  • Commit history
  • Review-thread replies and conversation comments
  • Session logs, such as the log section of a WORK.md
  • Any other chronological log

The test: would rewriting it hide what happened, or when? If so, append.

Where this applies ​

Each of these topics carries the rule for its own case: