Inspect before changing

Many bad changes begin with a wrong assumption about where behavior lives. Before editing, trace the current path and separate what you observed from what you inferred.

For a display-name bug, an inspection might follow this sequence:

1. Find the form event or API route that starts the update.
2. Follow calls until the code reaches the database or external service.
3. Find tests for the current behavior.
4. Check types, configuration, feature flags, and generated code involved.
5. Identify the public contract that must remain stable.
6. Report facts with file paths and name what remains unknown.

Facts and inferences are different

A useful inspection note could say:

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 may be reasonable, but labeling it prevents the agent from building a solution on an unverified assumption.

Source code may not be the whole runtime

Configuration, environment variables, generated files, database state, feature flags, and deployed versions can change behavior. Reading a route proves what the file says, not necessarily what production is running.

Match the inspection to the task. A local refactor may only need source and tests. A production incident may also need logs, deployment metadata, and current configuration.

Ask for the relevant path

Read the whole repository creates noise. Ask the agent to find the entry point, dependencies, tests, and nearest example, then explain the path before changing it.

This creates an early review point. Correcting a two-paragraph mental model is cheaper than correcting a twenty-file implementation.

Try this

Trace one button click from the browser event to its final side effect. Write three observed facts with file paths and one uncertainty you could not confirm.