change-and-decision-log git:20261001.a762959A

Immutable. This exact content never changes and is served at /api/v1/blob/fb2d96b0b9163e7f.

---
name: change-and-decision-log
description: >
  Set up or audit the habit of writing down what changed, why a real judgment call was made,
  and when to come back and re-check something — so an AI agent picking this project up in a
  future session, with no memory of this one, can actually resume where the last session left
  off instead of re-discovering context or re-litigating a decision that was already made. Use
  when a user asks "how do I keep track of decisions/changes," "help me document this so we
  don't lose it," "set up a changelog," or when auditing whether a project's process lets things
  get silently forgotten between sessions. Complements measurement-discipline (this pack), which
  is the narrower change-ledger-for-attribution tool; this skill is the broader cross-session
  memory system that makes the AI agent's documentation *be* its memory.
---

# Change & Decision Log

An AI agent has no memory between sessions except what got written down somewhere it will
actually read again. The fix for "the AI forgot" or "we're re-arguing something we already
settled" isn't a smarter agent — it's the habit of writing three specific kinds of things down,
at the moment they happen, not reconstructed later from memory. Done well, the documentation
*becomes* the agent's mind across sessions: a future session should be able to read it and pick
up cold, not re-derive what a past session already worked out.

---

## Step 0 — Ask before assuming

1. Does any changelog/decisions-log/review-date system already exist for this project? Check for
   files that look like `CHANGELOG.md`, `DECISIONS.md`, `ROADMAP.md`, or an equivalent, before
   assuming none exists.
2. Who actually reads these back later — a human, an AI agent starting a fresh session, or both?
   This changes how explicit entries need to be: an AI agent with zero memory of what happened
   needs the reasoning spelled out, not just a terse label a human who was there would still
   understand.
3. How much time/how many separate sessions typically pass between touches on this project? The
   larger the gap, the more this system is doing real work — a project worked continuously by one
   person barely needs it; one resumed cold by a fresh AI agent every time needs it constantly.
4. Is there already a habit of flagging uncertain items and coming back to them, or do uncertain
   items currently just get guessed at or silently dropped?

**If none of this is known:** assume the more demanding case — a project resumed cold, by an AI
agent with no memory of prior sessions, with real gaps between them — since that's the scenario
where skipping this system costs the most, and the system costs little extra to set up even if
the actual usage pattern turns out lighter than that.

---

## Step 1 — The changelog: what changed, when, and why

- One file (or equivalent), one entry per significant change: what happened, roughly when, and
  *why* — not "updated file.json," but "fixed X because Y was wrong per Z source."
- Threshold for "significant enough to log": if a future session would otherwise have to
  reconstruct this from git history or diffs to understand the current state, it belongs here.
- Check that logging happens as the last step of doing the work itself, not as a separate task
  someone has to remember afterward — the latter reliably lapses. Verify this is actually true,
  not just declared as a rule somewhere.

---

## Step 2 — The decisions log: judgment calls that could get re-litigated

- Distinct from the changelog: not "what changed" but "what was decided, where a real judgment
  call existed, and why" — the kind of thing a future session might otherwise second-guess or
  redo from scratch.
- Every entry needs the *reasoning*, not just the outcome. "Chose X" is not useful on its own;
  "chose X over Y because Z" is what actually prevents re-litigating it later.
- Check specifically for decisions that were made implicitly — in a conversation, in a commit
  message, only in someone's head — but never actually written to the log. These are exactly the
  ones that get re-argued later, because nothing shows they were ever settled.

---

## Step 3 — The review-date / staleness backstop

- Anything that can go stale (a fact, a figure, a piece of content, an architecture doc) should
  carry an explicit "next review by" date or trigger condition — not rely on someone remembering
  to check it eventually.
- A date sitting in a file is not enough on its own: check for (or build) a lightweight mechanism
  that actually surfaces what's overdue, rather than a date nobody re-reads. Weight this by how
  much activity has happened *since* the last check, not just elapsed time — a doc untouched for
  months in an inactive area matters less than one sitting behind a lot of unlogged recent change.
- **"Flag, don't guess"** is the companion rule: when something can't be confirmed right now,
  write down what's uncertain and why, rather than guessing at it or silently skipping it. An
  explicit flag is recoverable later by anyone (human or AI); a silent guess or a silent gap
  isn't — nothing will ever surface it again.

---

## Step 4 — Make it legible to a cold-start reader

The real test: could an AI agent — or a human — with zero memory of prior sessions read the
changelog, the decisions log, and the list of open flags, and know within a few minutes what
state things are actually in, without re-reading the project's entire history? If yes, the
system is working. If not, something in Steps 1–3 either isn't being kept current at the moment
work happens, or is written too tersely for someone with no shared context to actually use.

---

## Output shape

Whether a changelog, a decisions log, and a review-date/staleness mechanism already exist for
this project. If not: a minimal starting structure for each, sized to the project (a single
`CHANGELOG.md` and `DECISIONS.md` is enough for most cases — this doesn't need to be elaborate
to work). If they exist: a habit audit — is logging actually happening at the moment work
finishes rather than as an afterthought; are decisions logged with their reasoning, not just
their outcome; is anything flagged-and-forgotten rather than flagged-and-tracked; would a
cold-start reader actually be oriented by reading these files today.