change-with-contracts
Skill1 starsChanged 4 months agoMITView on GitHub
Use when about to change code in a repo that has a contract tree. Locates the affected module via `.contract-tree/tree.md`, classifies whether the change touches the module boundary, computes the downstream blast radius, and requires an explicit preserve-vs-cascade decision from the user before touching boundary-affecting code.
In this repository3 other files it gives its agents.
- check-driftSkill
- contract-treeSkill
- map-modulesSkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 3 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Hard rule: this skill NEVER cascades on its own: When a change would alter a module's boundary, you present the blast radius and let the …
- Very specific: line 16
If the repo has no .contract-tree/ yet, run map-modules first (at least for the area you're touching), then return here.
- Very specific: line 23
Read .contract-tree/tree.md.
- Very specific: line 29
Read io.input as the module's precondition, io.output as its postcondition, and each invariant as a boundary guarantee (Design by Contract).
- Very specific: line 40
Update the CONTRACT.md; no cascade.
- Distinctive: line 45
When unsure whether a change is additive or breaking, treat it as breaking and compute the radius.
- Very specific: line 50
Follow references/blast-radius.md: from tree.md, follow → edges transitively from the changed module to collect all downstream modules, …
- Distinctive: line 67
When you present the radius, note how each downstream module is coupled to the changing output (its connascence — a renamed field is weak.
- Very specific: line 85
Update every CONTRACT.md whose boundary changed, and regenerate the affected part of .contract-tree/tree.md if the dependency graph changed.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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.
Files
Change With Contracts
The procedure for changing code in a repo that has a contract tree. It keeps you oriented with cheap reads and turns any boundary change into a deliberate, visible decision.
Hard rule: this skill NEVER cascades on its own. When a change would alter a module's boundary, you present the blast radius and let the user choose preserve-vs-cascade. No boundary-affecting code is touched before that choice.
If the repo has no .contract-tree/ yet, run map-modules first (at least for
the area you're touching), then return here.
The six steps
1. Locate
Read .contract-tree/tree.md. Find the module(s) where the task lives. Open only
those CONTRACT.md files — read their purpose, io, invariants, and
entrypoints. Do not scan the whole tree.
2. Classify the change
Read io.input as the module's precondition, io.output as its postcondition,
and each invariant as a boundary guarantee (Design by Contract). Then classify into three —
see ../contract-tree/references/principles.md
for the compatibility rule and taxonomy:
- Internal (SemVer PATCH) — internals only; precondition, postcondition, and every
invariant stay true. → Implement freely. On finish, re-check invariants; update
CONTRACT.mdonly if something it declares actually changed. No cascade. - Additive (SemVer MINOR) — the contract changes but stays backward compatible: it
weakens the precondition (accepts more), strengthens the postcondition (guarantees
more), or adds a new optional output/entrypoint. Existing consumers still work. →
Update the
CONTRACT.md; no cascade. This is also the target of a "preserve". - Breaking (SemVer MAJOR) — it strengthens the precondition (demands more of callers), weakens the postcondition (guarantees less), removes/renames required I/O, or breaks a declared invariant. → Go to step 3.
When unsure whether a change is additive or breaking, treat it as breaking and compute the radius; a false alarm is cheap, a missed break is not.
3. Compute the blast radius
Follow references/blast-radius.md: from tree.md, follow → edges
transitively from the changed module to collect all downstream modules, then open
each one's CONTRACT.md to see how it consumes the changing output. Note which
are genuinely affected and how.
4. Present the radius and let the user decide
Show the user: what boundary changes, which downstream modules are affected, and their concrete use points. Then offer the two paths explicitly:
- Preserve — find an additive path to the same goal so the provider evolves without consumers jumping in lockstep (consumer-driven evolution): add a new field/overload instead of changing an existing one, introduce an extension point, adapt at the edge, or deprecate-before-removing. The radius collapses to zero downstream work.
- Cascade — accept the breaking change and propagate it through the affected downstream modules.
When you present the radius, note how each downstream module is coupled to the changing output (its connascence — a renamed field is weak; a relied-on meaning like "meters" or a positional/algorithmic dependency is strong). Stronger coupling means a costlier cascade and a stronger reason to preserve.
Stop and wait for the user's choice. Do not touch boundary-affecting code before it.
5. Execute the chosen path
- Preserve — implement the boundary-safe alternative in the module. Downstream is untouched.
- Cascade — change the root module, then each affected downstream module in
graph order (upstream before downstream), updating each module's
CONTRACT.mdas its boundary changes.
6. Close
Update every CONTRACT.md whose boundary changed, and regenerate the affected
part of .contract-tree/tree.md if the dependency graph changed. An updated
contract is part of "done" — leaving it stale is a bug, because the next task
trusts it.
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
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.

