A practical record for documenting meaningful changes to an existing software workflow that uses a model.
When a model, prompt, tool, data source, permission, evaluation, approval path, monitor, or rollback plan changes, the surrounding system changes with it. ai-change-record gives that change a small, reviewable home.
The record captures what changed, why it changed, who owns the decision, what needs to be checked again, what should be watched after the change, when work should pause, and how the previous state can be restored or contained.
It documents a decision. It does not approve one.
A change can look small in a diff and still alter how a system behaves.
Examples:
- switching to a new model version
- changing a system instruction
- adding a search or retrieval source
- giving a workflow access to a new tool
- widening or narrowing permissions
- changing source data or data handling
- replacing an evaluation or acceptance check
- moving a human review step
- changing what is monitored after release
- changing the rollback or containment path
Without a record, those decisions are often scattered across commits, chat threads, tickets, dashboards, and memory. Months later, another person can see that something changed without being able to reconstruct why, what was checked, or how to undo it.
The AI Change Record keeps that context beside the change.
Every record has ten sections.
| Section | Question |
|---|---|
| Identity | Which workflow and decision does this record belong to? |
| Change statement | What is different before and after the change? |
| Change surface | Which parts of the workflow are affected? |
| Purpose | Why is the change being made and who may be affected? |
| Boundary | What remains unchanged and what does this record not authorize? |
| Evidence and re-check | What should be tested, reviewed, or verified again? |
| Monitoring | What observable condition matters after the change? |
| Pause condition | What should stop normal operation and trigger human review? |
| Rollback or containment | How can the change be reversed or limited if needed? |
| Outcome and retention | What happened, what remains open, and where is the record kept? |
The point is not to produce a long document. The point is to preserve enough context for another person to inspect the change later.
Use a change record when a change could alter behavior, access, output, review, recovery, or the decisions downstream of the workflow.
A useful test is:
If this change causes a problem later, would another person need more than the commit diff to understand what happened?
If yes, write a record.
Record the old and new versions, the reason for the change, the checks that should be repeated, and the path back if the new version causes regressions.
Record the material behavior the instruction is intended to change. Do not paste private system prompts into a public record.
Record what the new tool can reach, what it is being used for, and whether its addition changes existing permissions or failure modes.
Record changes to corpora, indexes, embeddings, source data, or data-handling routes when those changes could affect what the workflow can retrieve or produce.
Record any change in what the workflow may read, write, send, modify, spend, schedule, or otherwise act upon.
Record changes to tests, acceptance conditions, human review, escalation, or other checks that determine whether work continues.
Record changes to the signals being watched, pause conditions, rollback paths, or containment procedures.
Suppose a support workflow currently drafts replies using model A and a reviewed internal knowledge base. The team wants to move to model B.
The code change may be one line.
The record should still answer:
- which workflow is changing
AtoB- why the change is being made
- what behavior is expected to improve
- what remains unchanged, such as draft-only access
- which support cases should be re-tested
- who reviews the test results
- what error or quality signal should pause the rollout
- how to return to model
A - who owns the final decision
That is the kind of context a diff cannot preserve by itself.
Copy templates/ai-change-record.md into the project where the change is happening.
Keep the record close to the work when possible. A useful path might be:
docs/changes/ACR-2026-09-02-model-b.md
Complete every section that applies. When something is unknown, say that it is unknown and assign a follow-up owner rather than inventing an answer.
The supported record states are:
Proposed
Under review
Introduced
Paused
Reverted
Contained
Those states describe what happened to the change. They do not imply that the system is safe, compliant, or approved for uses outside the decision being recorded.
Run the dependency-free validator against a completed record:
python3 scripts/validate_change_record.py path/to/record.mdThe validator checks that required sections and accountability fields are present and rejects a small set of unsupported assurance phrases.
A passing result means the Markdown has the expected structure.
It does not mean:
- the change is correct
- the evidence is sufficient
- the system is secure
- the system is safe
- the workflow meets a legal or regulatory requirement
- the change should be released
Those decisions still belong to the people responsible for the system and the context in which it operates.
A record may be reviewed or shared beyond the immediate implementation team, so keep it intentionally narrow.
Do not place the following in a public record:
- passwords, tokens, credentials, or secrets
- personal or customer data
- private support transcripts
- proprietary system prompts
- sensitive security details
- raw private evaluation data
- information that belongs in a restricted incident or legal record
Reference a permitted location instead when supporting material cannot safely live beside the record.
action-boundary-brief and ai-change-record sit on different sides of work.
before a consequential action when an existing workflow changes
Action Boundary Brief AI Change Record
--------------------- ----------------
what is the intended outcome? what changed?
what may the workflow touch? which surface changed?
what may it decide or do? what must be checked again?
who owns exceptions? what should be monitored?
what condition stops the action? what condition pauses the change?
what review record is needed? how can it be rolled back or contained?
Use the first to define a boundary before meaningful access or execution. Use the second to preserve context when an established workflow changes.
They can be used together, but neither grants permission by itself.
The fields in the template were informed by public work on lifecycle risk management, testing, monitoring, human oversight, permissions, and recovery.
See references/source-notes.md for the specific source links and the limits of that interpretation.
The references inform the method. They do not turn this repository into a compliance checklist or certification tool.
| Path | Purpose |
|---|---|
SKILL.md |
Compact operating instructions for creating a change record. |
templates/ai-change-record.md |
Reusable Markdown template. |
scripts/validate_change_record.py |
Dependency-free structural validator. |
references/source-notes.md |
Source basis and method limits. |
ARCHITECTURE.md |
File structure and design boundaries. |
DEPLOYMENT.md |
Public-site release and rollback guidance. |
QA.md |
Release checks and verification notes. |
index.html |
Public walkthrough for the method. |
A static version of the method is published at:
https://virtualmase.github.io/ai-change-record/
The site explains the record and uses fictional examples. It does not collect, score, approve, or retain visitor input.
Useful contributions include:
- clearer field wording
- better fictional examples
- validator improvements
- corrections to source notes
- accessibility improvements
- documentation that makes the method easier to use without weakening its boundaries
Read CONTRIBUTING.md before opening a pull request.
Do not put private incidents, credentials, customer information, personal data, or security-sensitive details in a public issue or pull request. Use SECURITY.md for responsible security reporting.
Licensed under Apache-2.0.
Academic citation metadata is available in CITATION.cff.
virtualmase
build quietly.