How it works
From one commit to a map of what a change will touch.
Six steps, one running example. We follow a customer cancelling an order through a small, illustrative system with three repositories, and watch the twin form layer by layer.
01 · Capture one version
Everything starts from an exact commit.
Every repository in the product is pinned to one commit, and every fact the twin records carries that commit with it. When a reviewer opens a citation months later, it opens the line as it was, not the line as it is now.
Files the reader cannot parse are skipped, but never silently. Each one is listed with its reason, so unread code can never look understood.
3 repositories · 3 commits · illustrative
- Read and indexed1,284 files
- Skipped · generated code22 files
- Skipped · binary or too large11 files
- Skipped · parser error4 files
02 · Build the code graph
Files, symbols and calls, with every link graded.
The graph connects entry points to the code they reach: routes to handlers, handlers to services, services to writes. A call that resolves to exactly one declaration is confirmed. An interface with two implementations is possible. A runtime dispatch is unknown, and the path ends there. Select any node.
orders-api @ a41c9e2 · exports-job @ e98f4a0 · illustrative
03 · Keep data models apart
Six views of the data, never merged because two names match.
The database schema, its migrations, the ORM, API contracts, event payloads and client types each describe the same data, and they often disagree. The twin keeps each view with its own evidence and shows where they conflict.
status VARCHAR(20) NOT NULLNever empty
V12__orders.sql:7@Column(nullable = true)
private String status;May be empty
Order.java:31status?: OrderStatusOptional
openapi.yaml:212Three honest answers to “can status be empty?”. A tool that merged these by name would pick one and hide the other two. The twin keeps all three, flags the conflict, and leaves the decision to a person.
04 · Name the business meaning
From guards and writes to rules a product lead can read.
On top of the code and data, the twin proposes a business model: who acts, what they do, which rule guards it and which state it changes. Each assertion links back to the code that supports it and carries a label. Reading the guard is extracted. Calling it a customer policy is an inference. A rule the team wants next is intended.
- Entity
- Field
- Action
- Rule
- State
- API
- Event
- Service
The rule underneath every layer
Two labels on every claim.
What kind of claim is it?
Four kinds of knowledge that never promote each other. Repeating an inference does not make it verified.
- Read from codeA parser found it in the captured commit: a route, a column, a guard. The citation opens the line.
- AI inferenceA model proposed a meaning, such as “this guard is a customer policy”. Useful, and labelled as a guess.
- IntendedSomeone asked for it: a requirement, a brief, a ticket. It describes what should happen, not what does.
- VerifiedA test ran against a named build and passed for its inputs. It proves that case, nothing wider.
How sure is the link?
Every edge in the code graph is graded, so a reviewer knows which paths to trust and which to check.
- ConfirmedThe call resolves to exactly one declaration in the code that was read.
- PossibleSeveral targets fit, such as an interface with three implementations. Each is shown.
- LibraryThe call leaves your code for a dependency. The twin records it and does not guess inside.
- UnknownDynamic dispatch, reflection or an unread repository. The path stops and says so.
05 · Map a change
Edit, depend, protect, and the edge of what is known.
A proposed change is checked against the twin. The result splits into direct edits, indirect dependencies and regression-only checks. Every dependency comes with up to three evidence paths you can open, so a reviewer can see why it is on the list. Where the graph runs out, the report says the map stops here.
Direct edits
Code the plan expects to change.
CancelOrderRequestAdd a required reason field.OrderService.cancelValidate the reason before the status write.V31__add_cancel_reason.sqlNew nullable column, so historical rows stay readable.
Indirect dependencies
Not edited, but reaches the change. Each comes with the path that proves it.
mobile-app 3.2 · CancelButtonCalls the endpoint without a reason. It will start receiving validation errors.CancelButton.onPressapi.cancelOrderPOST /orders/{id}/cancelSupportController.overridePossible caller through an interface with two implementations. Check before rollout.SupportController.overrideOrderOps.cancelOrderService.cancel
Regression only
Must keep working. Needs a check, not an edit.
order.isShipped() guardUntouched, but a valid reason must not bypass it.Historical cancellationsRows with no reason must still load and export.NightlyExportJob.runPossible reader of orders. Confirm it tolerates the new column.
The map stops here
Known gaps. The report will not say “no impact” past this line.
refunds.dispatch(event)The refund handler is chosen at runtime. Whether refunds need the reason is an open question for a person.
06 · Refresh on every push
The twin moves with the code.
Every push produces a new commit and a new reading. The twin compares the two. A renamed handler with a clear trail keeps its history. A workflow that vanished because a repository was unreadable is marked not seen in latest code, not deleted.
Approvals are tied to the exact inputs they were given. If someone moves the shipping guard after the plan was approved, the plan is flagged for review. The old decision stays in history, readable against the code it was made on.
Corrections people made to the model carry forward only while the evidence under them still matches. Otherwise they are shown as conflicts for a person to resolve.