Write a dev-diary entry

A dev-diary entry records why a significant change was made — the kind of decision someone will want explained when they ask “why is it like this?” a year from now. You write it twice: a short draft distilled from the approved plan — the thing actually reviewed before the work starts, and the work waits until it has been — and a final version reconciled once the change has landed, rewritten into the story of how it is now.

Not every change earns one. Choosing between two viable approaches, adding conceptual surface (a rule, a module boundary, a namespace), or a refactor that spans several PRs does; a bug fix, a routine dependency bump, or a function that follows an existing pattern does not. The skill always puts that call to you before writing anything — and when an existing entry already tells the decision’s story, it proposes updating that entry instead of adding a sibling.

Entries live under docs/diary/, below the pinned intro, with the newest at the bottom. The mechanics — the two passes, the one-screen budget, and how open assumptions are marked so they render on the page you review — are exactly what the skill enforces:

Working with Claude Code¶

The dev-diary skill’s checklist:

- [ ] Trigger named (decision-weight, not category) and the choice **put to the user** — including
      update-an-existing-entry when one already tells this decision's story
- [ ] Entry staged, never committed by you; commit message proposed and left to the user
- [ ] Remote actions (push, PR, remote branch) confirmed by the user first
- [ ] Entry is the branch's first commit (or mid-flight start noted in the PR body)
- [ ] One screen: ≤500 words, no restated plan steps, driving question named in the PR body
- [ ] `Last edited` line present; assumptions in a **rendered** block; rejections in dropdowns
- [ ] **Pass 1 ends the turn**: page named, preview handoff given, implementation not started
- [ ] Pass 2 staged last, rewritten into how it is now and read against the code — error
      strings, diagram branches, guardrail scopes and snippets all verified against `src/`
- [ ] `git grep -nF "{attention} Assumption" -- 'docs/diary/*.md'` is empty
- [ ] `## What changed from the plan` only where the divergence teaches — each bullet readable
      without the plan
- [ ] TOC entry appended at the bottom of the `Dev Diary` group (below the pinned intro)