An AI agent can make a wrong change with extraordinary precision. Give it an older checkout, a generated file instead of its source, or a preview that no longer matches production and it will confidently optimise a version nobody uses.
This is why I separate orientation from implementation. Before the first edit, establish what is true now, identify the exact editable source behind it, and understand the surfaces that change can affect. Speed begins after that proof—not before it.
§1Why versions drift
Modern work has more layers than “the code” and “the website.” The public artifact may have come from a branch, a generated directory, a manual deploy, a build pipeline, or a working copy that no longer exists. Meanwhile, another clean local directory may appear authoritative because it has a familiar name and no pending changes.
- Production can be ahead of local: a newer deploy exists, but the open checkout never received it.
- Local can be ahead of production: completed work is waiting in a branch or preview.
- Generated output can be ahead of source: a build artifact was changed or recovered without its inputs.
- Documentation can be behind both: a once-correct note still points agents toward an obsolete path.
- Two tools can own different truths: one system controls source, another controls deployment, and a third holds live data.
§2Use a question-specific truth hierarchy
There is no single universal source of truth. The authoritative surface depends on the claim. Public rendering answers “what does a visitor see?” A deployment record answers “what artifact is serving?” Version control answers “what history can be reproduced?” A structured data source answers “what facts should every interface repeat?”
The orientation ladder
- 01ObserveInspect the real public or operational outcome.
- 02TraceIdentify the deploy, build or process producing it.
- 03LocateFind the exact source and branch behind that artifact.
- 04CompareMeasure drift against other plausible working copies.
- 05BoundMap shared files, generated surfaces and collision risk.
- 06EditBegin only when the chain can be explained.
§3The five-minute orientation protocol
- State the claim: name exactly what must become true for a user, operator or future agent.
- Inspect the outcome: open the live surface, fetch the current machine-readable output, or check the operational state.
- Trace its origin: identify the serving deploy, build command, branch, data file or process.
- Compare candidates: check recent history, status and changed paths in every plausible working copy.
- Declare the source: record the path, branch and evidence that make one location authoritative for this task.
For this change, the authoritative outcome is [surface]. It is currently produced by [deploy or process] from [source]. I verified that by [evidence]. The edit begins in [location] and must preserve [constraints].
§4Map the blast radius before touching shared state
Once the source is known, ask what else consumes the same fact or asset. A small visible change can have a large release radius: HTML, indexes, structured data, caches, generated files, tests and alternate views may all carry a copy.
The useful question is not “which file should change?” It is “which readers, machines and future builds depend on this value?” Search references, inspect build scripts, note generated outputs, and identify other active work touching the same surface.
§5Do not solve drift by interrupting other work
If another agent or person is active in a plausible source tree, treat that directory as occupied. Read it if needed, but do not build, format, switch branches or overwrite files there. Take a snapshot into an isolated workspace, preserve the origin, and make the preview independently.
Isolation turns coordination from a social hope into a technical property. The active worker keeps its state; the redesign or investigation gets a reproducible starting point; integration happens only after both sides can be compared.
§6Know when orientation is complete
You are ready to edit when you can answer these questions without guessing:
- What outcome am I changing?
- What artifact or process produces that outcome now?
- Which exact source can reproduce it?
- How does that source differ from other plausible copies?
- Who or what else is touching the same files or release state?
- What evidence will prove the new outcome after the edit?
If one answer is missing, keep orienting. An extra minute before the edit is cheaper than a perfect patch to the wrong reality.
§7A copy-usable source-of-truth brief
orient before implementation
OUTCOME
What must become true, and for whom?
LIVE EVIDENCE
What public or operational surface shows the current state?
ORIGIN
Which deploy, process, build or data source produces it?
EDITABLE SOURCE
Exact repository, branch, directory and source file.
DRIFT CHECK
Which other copies looked plausible, and how do they differ?
COLLISION CHECK
Who or what else is active on the same release surface?
BLAST RADIUS
Which pages, indexes, caches, schemas or generated files depend on it?
PROOF
Which focused check and real-world render will establish success?
STOP CONDITION
What would make this unsafe to continue?Steal this
- Trace backward from the outcome that matters; do not trust directory names.
- Choose the source of truth per claim, not per project.
- Compare every plausible working copy before editing.
- Map downstream consumers and active collaborators.
- Use an isolated workspace when another agent is active.
- Start implementation only when the evidence chain can be explained.