Before you refactor, ask the graph

Before you refactor, ask the graph

I’ve broken more refactors than I care to admit.

Not because the idea was wrong. Because I changed something without knowing what still depended on it, or what was already dead and shipping anyway.

Your coding agent can rewrite a function in seconds. Out of the box, it still can’t see the blast radius. That gap is where “simple cleanup” turns into a long night.

You open something that should be easy:
• rename a shared helper
• delete an old path
• split a god module

Then reality shows up:
• grep floods the terminal
• half the hits are comments or tests you don’t care about
• the risky callers are three folders away
• the dead code is still in production

So the agent does what agents do. It makes a confident change. You find out what broke in review, or worse, after merge.

I’ve lived that loop. It’s why we built this part of ContextStream.

Three plain answers:

1. What depends on this?
   Callers, importers, downstream modules. The real graph, not a text match.

2. What’s already unused?
   Code you’re about to carefully “improve” that nothing runs anymore.

3. Where is the complexity concentrated?
   The files that will punish a casual edit.

That’s not a bigger prompt. That’s structure.

How this looks with ContextStream

ContextStream keeps a code-health graph over your project: symbols, files, dependencies. It makes that available to the agent you already use.

Before a refactor, ask in ordinary language:

> “What depends on AcmeClient.send?
> Show unused code in src/billing/.
> Where are the circular dependencies around payments?”

A useful answer looks like:
• the files and symbols in the blast radius
• dead paths you can delete instead of rewrite
• complexity hotspots to touch last (or isolate first)

Then the edit is smaller, safer, and honest. That’s the outcome I want every time I touch shared code.

I use some version of this every time:

1. Name the symbol or folder you’re about to change
2. Ask what depends on it
3. Ask what’s unused nearby
4. Record a baseline only after the analysis finishes
5. Make the smallest change the graph supports
6. Re-check impact before you merge

If step 2 is empty, you’re guessing. I’ve guessed. It costs more than the five minutes of asking.

Why agents need this now

Coding agents are fast at producing diffs. They’re still weak at system memory: what the codebase is, not just what the open files say.

Text search finds strings.
A dependency graph finds consequences.

ContextStream is built for that second job. Durable project context, ranked for the task, delivered where the agent works, including code search and code-health over the real graph.

Try it on the change you were going to make anyway

Pick one risky cleanup on your list. Before you touch a line, ask the graph those three questions.

If the answer changes the plan, the post already paid for itself.