| name | Change Control |
| description | Keep edits controlled, reversible, and easy to review. Activate whenever modifying existing artifacts - code, documents, configs, prompts, workflows, plans - especially edits to things that currently work, changes others depend on, batch modifications, or anything hard to undo. Trigger signals: "update", "refactor", "change", "edit", "migrate", "replace", touching shared or production material, or noticing an edit growing beyond its original intent. |
Change Control
Purpose
A change is good when it does what it intends, does nothing else, and can be understood and undone by someone who isn't you. This skill governs how changes are made — sized, isolated, documented, and reversible — independent of what they are. It applies equally to code, documents, prompts, configs, and strategy plans: anything with a working current state that an edit could damage.
When to use this skill
- Editing anything that currently works or that others depend on.
- Changes that are hard to reverse (sent, deployed, deleted, published, migrated).
- Multi-part edits where review will matter later ("what changed and why?").
- Editing prompts or workflows whose behavior is sensitive to wording.
When NOT to use this skill
- Greenfield creation — nothing exists yet to protect (though
plan-gate still applies).
- Your own scratch work and drafts no one depends on.
Operating procedure
Step 1 — Classify the change by risk before touching anything:
| Class | Definition | Handling |
|---|
| R0 — Cosmetic | No behavior/meaning change: formatting, typos, comments | Make it. Don't mix it into R2+ changes. |
| R1 — Local, behavior-preserving | Internal restructuring; external behavior/meaning identical | Verify preservation (tests, before/after comparison). |
| R2 — Behavior-changing | Output, meaning, interface, or policy changes | Requires intent statement, verification of both the new behavior and non-regression of the old. |
| R3 — Hard to reverse | Deletes, sends, deploys, migrations, published artifacts, anything external-facing | All of R2, plus a rollback answer before executing, plus explicit confirmation if acting for someone else. |
Step 2 — State intent in one line. "This change makes X do Y because Z." If you can't fill that sentence, you're not ready to edit. If it needs the word "and" twice, it's two changes — split them.
Step 3 — Make the change, honoring the isolation rules:
- One concern per change. Bug fix ≠ refactor ≠ cleanup. Reviewers can verify one intent; they rubber-stamp three.
- No drive-by edits. Adjacent ugliness you noticed goes to the flag list (
scope-fence), not into this diff.
- Preserve existing behavior by default. Anything not explicitly targeted should work/read exactly as before — including things you consider bugs (they may be load-bearing).
- Match the local style, even where you'd have chosen differently. Consistency reviews cheaper than taste.
- Keep it minimal but not cryptic: the smallest change that fully accomplishes the intent.
Step 4 — Preserve reversibility:
- Code: small commits/diffs, no unrelated file churn, note the revert path if non-obvious.
- Documents/plans/prompts: keep the prior version recoverable (version history, dated copy, or quoted original); mark what changed and why.
- R3: write the rollback down first. "How do I undo this?" answered after a migration is a very different conversation.
Step 5 — Verify at the class-appropriate level (live-state-truth): R1 → prove preservation; R2 → prove new behavior and old behavior's survival; R3 → verify in the safest available mode first (dry-run, staging, one-item sample).
Step 6 — Document tradeoffs. If the change accepts a cost (slower but clearer, shorter but less nuanced, quick fix over proper fix), record it where the next person will find it — commit message, doc changelog, or delivery note.
Quality bar
- A reviewer can state the change's intent from the diff alone.
- Nothing outside the stated intent changed — verified, not assumed.
- The undo path is known, and for R3, was known before execution.
Common failure modes
- The kitchen-sink diff: fix + refactor + formatting in one change. The bug fix is now unreviewable and unrevertable on its own.
- Silent behavior change during "refactoring": an R1 that was actually an R2. The label you assign is a claim — verify it.
- Fixing "obviously wrong" existing behavior uninvited: it may be compensating for something you can't see. Flag it; don't fold it in.
- Irreversible-by-carelessness: overwriting the only copy of a doc, force-pushing, deleting before confirming the backup exists. R3 handling exists precisely for the two seconds this saves.
- Prompt/config edits without a diff: wording changes to prompts are behavior changes (R2) with invisible blast radius — keep the old version and compare outputs.
Example
Request: "Fix the off-by-one in the pagination."
- Do: the one-line fix (R2: intent stated, boundary test added, suite run) — done.
- Don't: also rename the confusing variable, also reformat the file, also "modernize" the loop. Those go to the flag list: "Noticed while here (not changed):
pgIdx naming is misleading; file has mixed indentation."
Works with sibling skills
scope-fence decides what is in scope; this skill governs how the in-scope change is executed. They're enforced together.plan-gate produces the intent that step 2 states; live-state-truth performs step 5's verification.debugging-playbook step 7 (minimal fix) is this skill applied to bug fixes.effort-calibration: R3 changes are automatically Critical-tier.
Provenance and maintenance
Written 2026-07 as part of a portable, project-agnostic quality pack. No repo-specific claims. Re-verify by inspecting your last few substantive diffs/edits: if any contains changes its stated intent doesn't cover, isolation discipline is slipping. Map the R-classes onto your team's actual review/deploy gates if you have them.
