agentleFS
nicolasaprnicolasapr/contract-tree/skills/change-with-contracts/SKILL.md

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.

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
  1. Distinctive:

    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 …

    line 12
  2. Very specific:

    If the repo has no .contract-tree/ yet, run map-modules first (at least for the area you're touching), then return here.

    line 16
  3. Very specific:

    Read .contract-tree/tree.md.

    line 23
  4. Very specific:

    Read io.input as the module's precondition, io.output as its postcondition, and each invariant as a boundary guarantee (Design by Contract).

    line 29
  5. Very specific:

    Update the CONTRACT.md; no cascade.

    line 40
  6. Distinctive:

    When unsure whether a change is additive or breaking, treat it as breaking and compute the radius.

    line 45
  7. Very specific:

    Follow references/blast-radius.md: from tree.md, follow → edges transitively from the changed module to collect all downstream modules, …

    line 50
  8. Distinctive:

    When you present the radius, note how each downstream module is coupled to the changing output (its connascence — a renamed field is weak.

    line 67
  9. Very specific:

    Update every CONTRACT.md whose boundary changed, and regenerate the affected part of .contract-tree/tree.md if the dependency graph changed.

    line 85

≈ “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.

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

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.md only 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.md as 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.

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.