Inspect before changing

Many bad changes start with a wrong assumption about where the behavior lives. The agent guesses, edits the wrong place, and then patches around the mess. I’ve watched it happen dozens of times.

The fix is cheap. Before editing, trace the current path. And separate what you observed from what you inferred.

What an inspection looks like

For a display-name bug, I’d ask the agent to:

1. Find the form event or API route that starts the update.
2. Follow the calls until they reach the database or an external service.
3. Find the tests for the current behavior.
4. Check types, config, feature flags, and generated code along the way.
5. Identify the public contract that must stay stable.
6. Report facts with file paths, and name what’s still unknown.

That’s it. No editing yet.

Facts and inferences look different

A good inspection note reads like this:

Observed: POST /api/profile reads displayName in src/routes/profile.ts.
Observed: the handler writes the value without checking its length.
Observed: request tests cover valid updates but no invalid names.
Inference: another client may call this route directly; I have not verified all callers.

The inference might be right. Labeling it stops the agent from building a solution on top of something nobody checked.

Source code isn’t the whole runtime

Configuration, environment variables, generated files, database state, feature flags, and the deployed version all change behavior. Reading a route proves what the file says. It doesn’t prove what production is running.

Match the inspection to the task. A local refactor needs source and tests. A production incident also needs logs, deployment metadata, and the current config.

Ask for the path, not the repository

Read the whole repository produces noise and burns context. Ask for the entry point, the dependencies, the tests, and the nearest similar example. Then ask the agent to explain the path before it changes anything.

This gives you an early review point. Correcting a two-paragraph mental model takes a minute. Correcting a twenty-file implementation built on that wrong model takes an afternoon.

Try it on something small. Pick one button in your app and trace the click from the browser event to its final side effect. Write three observed facts with file paths and one thing you couldn’t confirm. That’s the shape of every good inspection.