document-change-intentions-using-change-intent-records

name	document-change-intentions-using-change-intent-records
description	Use when change intent or decision is worth remembering. Guides Change Intent Records for non-obvious rationale, rejected alternatives, subtle behaviour, or constraints maintainers and agents must preserve.

Document Change Intentions Using Change Intent Records

Use this skill when planning, implementing, reviewing, or explaining a change where future readers need to know why the change exists, what behaviour it protects, and which tradeoffs shaped it.

A Change Intent Record (CIR) is a small, change-level document that captures the intent behind a specific change. CIRs help AI-assisted development by giving future agents and humans durable context that is often lost in chat transcripts, branch notes, or terse commit messages.

Table of Contents

• When Change Intent Is Worth Remembering
• Standard CIR Template
• Recommended Location and Naming
• Relationship to Other Records
• Agent Workflow
• Example: Rejected Alternative
• Example: Non-Obvious Constraint
• Quick Checklist

When Change Intent Is Worth Remembering

Create a CIR when at least one of these is true:

• A reasonable alternative was rejected and future agents might rediscover it.
• The change is constrained by non-obvious product, operational, compatibility, security, or maintenance requirements.
• The intended behaviour is subtle enough that a future refactor could accidentally undo it.
• The change spans multiple files or systems and the rationale is not visible from code alone.
• The user explicitly wants the decision trail preserved.