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.