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. It is written once, when the change has landed — checked against the real code rather than drafted from a plan, so it tells the story of how it is now and why.

Not every change earns one. Choosing between two viable approaches, adding conceptual surface (a rule, a decorator, a namespace), or a refactor that spans several PRs does; a bug fix, a routine dependency bump, or a vocabulary term 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 one-screen budget, the Last edited line, and where an entry registers — 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
- [ ] Written once the change has landed — never a gate on starting the work
- [ ] One screen: ≤500 words, no restated plan steps, driving question named in the PR body
- [ ] `Last edited` line present with the PR numbers; rejections in dropdowns
- [ ] Written against the code, not from memory — error strings, diagram branches, guardrail
      scopes and snippets all verified against `src/`
- [ ] `## 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)