change-with-proof

name

change-with-proof

description

Use when implementing, debugging, refactoring, testing, reviewing, or completing non-trivial changes to software — bugs, flaky tests, regressions, refactors, migrations, API or schema changes, auth, permissions, secrets, payments, webhooks, persistence, uploads, routing, exports, UI and user-visible surfaces, external integrations, dead-code or legacy removal, and long-running or resumed multi-step work. Do not use for pure explanation or Q&A, greenfield scaffolding with no existing behaviour at stake, prompt writing, dedicated security audits, or visual design.

Change with Proof

Complete or review the requested change without letting compatibility, safety, or completion claims outrun evidence.

Repository and harness instructions, including AGENTS.md when present, remain authoritative. When a more specialised skill is active for part of the work (a dedicated security audit, visual design, prompt writing), let it own that part; use this skill for the engineering control loop around it.

Trivial, low-risk changes: follow repo conventions, report evidence, and skip the rest of this file.

1. Change contract

Before editing, classify each materially affected behaviour or surface:

• Disposition — preserve | change | migrate | retire.
• Strength — weak signal | intentional behaviour | hard contract. For anything above weak, name the source (user request, docs, tests, schema, release, config, code) and the consumer (user, API client, persisted data, another module, CI, export consumer).
• Reversibility — reversible | costly | one-way. Costly or one-way changes need the strongest proof and an explicit rollback statement.

Existing tests and snapshots are important signals, but not automatically sacred. If a test asserts implementation trivia, stale scaffold, or accidental behaviour, replace it with stronger proof of the intended contract instead of preserving the accident.

State unresolved uncertainty as one line of named assumptions. Ask before proceeding only when a disposition materially affects data, security, money, public API, or user-visible semantics and cannot be resolved by inspection.

Never change business behaviour (pricing, quotas, retention, entitlements) as a silent side effect of a fix, resilience work, or cleanup. That is a contract change: surface it as a decision.

2. Risk profiles

Read every profile whose trigger matches — the union, not a curated subset. Skip them all when none match.

Trigger	Read
Observed failure: bug, failing or flaky test, regression, unexpected output	profiles/causal-debugging.md
Changing, migrating, or retiring a hard contract: public API, schema, persisted data, versioned artifact	profiles/contract-evolution.md
Identity, permissions, tenancy, secrets, untrusted input, uploads, routing	profiles/trust-boundaries.md
Persistence, transactions, retries, webhooks, payments, queues, caches, external side effects	profiles/stateful-integrations.md
Rendering, interaction, product copy, notifications, exports, or other user-facing output	profiles/user-visible-surfaces.md
Deletion, replacement, consolidation, legacy or fallback removal, dependency retirement	profiles/replacement-closure.md

3. Proof portfolio

Prove each invariant at the lowest seam that still contains the real risk. A proof is useful only if it would fail when the important behaviour broke. Select the smallest set of evidence that covers every material changed risk; for each item, know the representative regression that would make it fail. One check may discharge several risks.

Risk lives in...	Prefer proof such as...
Pure calculation, formatting, parsing rule	Unit, fixture, or property-style test with edge cases.
Parser/schema/validation boundary	Schema contract test with valid and invalid fixtures.
Data transformation or normalization	Fixture tests, property tests where invariants are broad.
Internal adapter/wiring/orchestration	Integration test through the real module boundary.
External API/service	Boundary fake, recorded fixture, or contract test at the external port; keep internal production path intact.
API route/webhook	Request/response contract test, including rejected inputs and status codes.
UI route/user flow	Browser smoke or rendered component/route proof when rendering, routing, state, or interaction is the risk.
Persistence/migration	Representative fixture, migration, and round-trip proof.
Auth/permissions	Allowed/denied matrix across role/action/resource.
Export/generated artifact	Golden/approval diff with stable ordering; regenerate twice if nondeterminism is a risk.
Dependency architecture	Dependency graph/cycle check plus build/typecheck.
Dead-code cleanup	Reachability/dead-code candidate scan plus build/typecheck/route audit as appropriate.

Test doubles are valid outside the seam being proven. A fake should encode the external boundary contract, not reimplement production logic or assert the answer you want. Do not mock the subject whose behaviour you claim to verify, and do not assert only that a call happened when the behaviour that matters is output, state, persistence, rendered text, a security decision, or artifact shape.

For bugfixes, keep the counterfactual: the same proof fails on the original bug and passes after the smallest fix. If automated RED is infeasible, use the strongest deterministic repro and name the gap.

Prefer commands discovered from the repo (package/task files, CI config, docs, existing tests) over invented ones. If none exist, say what you ran and why it is only partial proof.

4. Execution

Work in vertical slices: implement → prove → clean → continue. Locate the owner of the behaviour and change it there rather than wrapping symptoms.

For long-running, multi-file, or resumed work, keep one durable state block, updated at slice boundaries — and treat any inherited summary as claims to re-verify against repo-visible facts (diff, tests, logs), not as truth:

Goal / stop condition:
Contract dispositions:
Profiles in play:
Done and proven:
In progress:
Proof still needed:
Decisions and rejected approaches:
Gaps / assumptions:
Next smallest step:

Populate only the material fields. Put durable state in an existing approved surface (issue, PR description, task file); do not invent new repo state files, and never leak process notes into product surfaces.

5. Completion gate

Before claiming done:

• Every changed hunk maps to the goal, a contract obligation, a risk treatment, or proof. Revert incidental formatting, renames, and drive-by "improvements".
• Every claim has matching-scope evidence: "typecheck passed" does not prove the browser flow; "unit test passed" does not prove the route; "no grep hits" does not prove no dynamic references.
• Every material risk has evidence or a named gap. Failed or skipped checks are reported as failed or skipped.

Final report — omit empty sections; no process narration:

Outcome: <what changed, including intentional contract changes>
Evidence: <check → the claim it supports>
Gaps: <unverified risks; "none" only when true>
Changed: <paths intentionally touched or retired>