Recording Change Intent

Recording Change Intent

Use this skill when a change carries risk and the reason for it exists only in someone's head, a chat thread, or a ticket nobody will find again.

Tests prove a change works. Coverage proves it was executed. Neither records why it was made, which constraint forced the odd shape, or what was considered and rejected. That is intent debt, and it is the one debt an agent structurally cannot pay down: a coding agent can write the implementation, the tests, and the docs, but it cannot supply the human reason the work was commissioned. As AI-assisted output grows, intent debt grows with it while every other quality signal keeps looking healthy.

The fix is small and unfashionable: on high-risk changes, require the rationale to be written down somewhere durable and linked to the change.

When to Use

• an AI-assisted or agent-generated change touches auth, money, schema, or public surface
• reviewers routinely ask "why is this like this" and nobody knows
• a codebase's decisions live in closed tickets and departed colleagues
• a per-change gate needs an intent check next to its test and coverage checks
• an ADR practice exists but nothing links ADRs to the commits that implement them
• a post-incident review cannot reconstruct why a change was made

Operating Principles

• Intent is why, not what. The diff already says what changed. refactor: extract computeRefund is a restated diff, not a rationale.
• Only high-risk surface needs it. Demanding a rationale on every typo fix trains people to write filler, and filler is worse than silence because it looks like compliance.
• A human writes it. An agent can draft it from context and must hand it to a human to confirm or replace. A generated rationale nobody read is intent theatre.
• Durable and linked. In the commit, in an ADR the commit references, or in a register keyed by module. Not in a PR description that a squash-merge will discard, and not in chat.
• A malformed record is not a missing one. Report them differently: one needs writing, the other needs fixing, and conflating them makes the gate feel arbitrary.
• Two layers, different strengths. Fast advisory feedback at commit time; real enforcement at push or CI. Fast feedback that blocks gets disabled; enforcement that is bypassable gets bypassed.
• Constraints and rejected alternatives are the valuable part. "Why not the obvious way" is what a future reader actually needs.

Workflow

Phase 1: Decide whether this change needs a rationale

Take the tags from scoping-change-relevance, or apply the rules in ./resources/high-risk-surface-rules.md directly. High-risk surface is:

• a new public export - a new capability other code can now call
• a new endpoint or externally reachable operation
• a modified auth path - anything touching who can do what
• a schema or migration change, especially an irreversible one
• a removed guard, removed validation, or removed test
• a new external dependency or call that adds a failure mode
• a change to a module the contract marks critical-path

Everything else: no rationale required. Say so explicitly, so the gate is visibly proportionate rather than universally nagging.

Phase 2: Check what rationale already exists

Any one of these covers the change:

git log <base>..HEAD --format='%H%n%B'          # read the whole message, trailers included
git log <base>..HEAD --format='%(trailers:key=Intent,valueonly)'
git log <base>..HEAD --format='%(trailers:key=Intent-Ref,valueonly)'

Trailers are the standard Key: value block at the end of a commit message - the same mechanism as Signed-off-by:. No tooling, no external service, and they survive rebase and squash if written into the final message. See ./resources/intent-trailer-spec.md.

Phase 3: Classify each high-risk change

"Restated diff" deserves the separate row. Intent: added the refund endpoint passes any mechanical check and carries no information. A human reviewing intent records should reject it as they would reject an assertion-free test.

Phase 4: Draft, then hand over

Where a rationale is missing, draft one from the evidence available - the diff, the linked ticket, the branch name, the surrounding code, the conversation. Then hand it to the author with the draft clearly marked as a draft, because a rationale the author has not confirmed is not a rationale.

A good record answers three questions in a few lines:

1. Why now - the trigger. A bug, a requirement, a limit that was hit.
2. What constrained the shape - the reason it is not the obvious implementation.
3. What was rejected - the alternative someone will otherwise propose in six months.

feat(billing): allow partial refunds on settled orders

Support desk cannot resolve disputes on settled orders without a full
reversal, which breaks the monthly reconciliation report.

Intent: Partial refunds must be idempotent because the provider retries
  webhooks up to 5 times; we key on (orderId, providerRefundId) rather
  than generating our own id, so a retry cannot double-refund. Rejected
  a queue-based approach - it would have needed a new consumer and the
  reconciliation window is 15 minutes, not seconds.
Intent-Ref: ADR-0042

More examples, including bad ones and why they fail, in ./resources/intent-trailer-spec.md.