What Could Break

What Could Break

Overview

Listing callers is not the job. Grep does that in a second. This skill finds the breakage grep will not show you, and produces one proof that the change is safe.

Run it before design, not only before merge. Whenever a task asserts something about existing code ("X already handles Y", "just make X public"), that assertion is a hypothesis, and the census of real consumers decides the design.

When to Use

• Use before any multi-file edit, or an edit to a shared path: API payload, config, stored data, a client other apps read, a prompt or policy file
• Use when the user asks "what could this break" or "blast radius of X"
• Use for a small diff you do not trust
• Use when a brief asserts something about existing code, before you design against that assertion

How It Works

Step 1: Do not trust your own writeup

A risk analysis that sounds right is worthless: it reads as convincing whether or not it is true. Find the one or two facts the whole change depends on, and get each one as far down this ladder as is cheap. Say where it stopped.

1. You said so. Worth nothing on its own.
2. You pointed at it. A real file:line, or the library's own source at the pinned version.
3. You walked it. You traced the bad case step by step and it does not reach.
4. You ran it. A script or test calls the real code and fails loud if you are wrong.
5. You saw it live. Reproduced in the running app, service or device.

Rung 4 is usually one small script that imports the same module production runs and calls the exact function you are worried about, with the input you are worried about.

Step 2: Read the change

The diff, the symbols it adds, changes and deletes, and what it now does differently, including what the diff does not spell out. git log -S '<symbol>' and git log -L :<function>:<file> show why the old shape exists; a guard that looks pointless often has a commit explaining the incident it stopped.

Step 3: Find the one fact it is safe because of

Most risky-looking changes are safe because of one fact ("this only drops cache entries that are already expired", "no client reads this field"). If it holds, most risks clear at once. If you cannot find one, the change is not understood yet.

Step 4: Look where grep stops

Search for the literal value, the field name, the error text and the old behavior, not only the symbol you renamed. Then check each of these by hand:

• The same rule living twice. A second config file, a fallback path that hardcodes the old default, a copy synced into another repo, a constant duplicated in a migration or test fixture, a feature flag default.
• Prompts and agent files that restate the rule. System prompts, agent and skill files, AGENTS.md, CLAUDE.md, runbooks. An agent obeys the stale sentence, not your code.
• Every other client. Web, iOS, Android, desktop, CLI, extensions, partner integrations. Mobile clients in users' hands stay on the old version for weeks: what does an old client do with the new shape, and a new client with the old server?
• Wire formats. JSON field names and types, enum values, null versus missing, date formats, pagination shape, error codes, webhook payloads, queue schemas, GraphQL and protobuf contracts.
• Stored state. Columns and their defaults, rows written under the old shape, cache entries, files on disk, append-only logs, session and cookie contents, search indexes. Old data outlives the deploy.
• Environment and secrets. An env var renamed in code but not in the deploy config, CI, the image, or the second service that reads it.
• Processes that restart separately. Web server, workers, cron jobs, serverless functions, the mobile app, a sidecar. During a rollout one runs new code while another runs old code against the same data. Can both coexist for an hour?
• Timing and concurrency. Two writers on the same row or key, a retry that now fires twice, ordering that only held because one step was slow.
• Library source at its pinned version. Read the dependency's code at the lockfile version, not your memory of its docs.
• Generated and vendored code. Clients generated from a schema, vendored copies, committed build artifacts, bundles whose cache-busting key did not change.
• Tests and fixtures that encode the old behavior. A test that passes because its fixture still has the old shape proves nothing about the new one.
• Observability. Dashboards, alerts and log parsers matching a message or metric name you changed.