explaining-changeslisted

# Explaining changes A diff says what moved. It cannot say which constraint forced the shape, which alternative was rejected, or which trap was avoided — and that is the half a reader needs in six months. The Observatory measures the first half without anyone's help. This skill writes the second. ## The one rule **Write only what the diff cannot show.** Restating the diff in prose is worse than an empty `why`: it fills the field, so nobody looks again, and it carries no information. If nothing non-obvious happened, say so and leave the field empty. A `why` worth storing answers at least one of: - **the constraint** — what made this shape necessary rather than the obvious one - **the rejected alternative** — what was tried or considered, and why it lost - **the trap** — what would have broken, and how it was found - **the evidence** — the measurement that settled it, with its command or file:line Never invent one. A fabricated reason is read as true by everything downstream, and nothing in the ledger can tell it from a measured one. ## Recording it The Observatory's Stop hook has already stored the facts as a `proposed` record and printed its id. Correct that record rather than creating a second one: ``` observatory_record( owner="agent:claude-code", memory_id="<the id the hook printed>", expected_revision=<the revision it printed>, statement="<the same claim, unchanged>", why="<one or two sentences>" ) ``` `owner` has no default — a write that could claim