agentleFS
ralfyishereralfyishere/rules-with-receipts/.claude/skills/change-control/SKILL.md

Change Control

Skill2 starsChanged 4 months agoMITView on GitHub

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.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Step 6 — Document tradeoffs: If the change accepts a cost (slower but clearer, shorter but less nuanced, quick fix over proper fix), record …

    line 51
  2. Distinctive:

    Do: the one-line fix (R2: intent stated, boundary test added, suite run) — done.

    line 70
  3. Very specific:

    Don't: also rename the confusing variable, also reformat the file, also "modernize" the loop.

    line 71

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

ClassDefinitionHandling
R0 — CosmeticNo behavior/meaning change: formatting, typos, commentsMake it. Don't mix it into R2+ changes.
R1 — Local, behavior-preservingInternal restructuring; external behavior/meaning identicalVerify preservation (tests, before/after comparison).
R2 — Behavior-changingOutput, meaning, interface, or policy changesRequires intent statement, verification of both the new behavior and non-regression of the old.
R3 — Hard to reverseDeletes, sends, deploys, migrations, published artifacts, anything external-facingAll 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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.