Skip to content

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.

Code structureSymbolsCall chainsData modelsBehaviourBusiness modelRequirements

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.

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

checksusescalls?dispatchesreads?Entry pointPOST /orders/{id}/cancelHandlerOrderController.cancelServiceOrderService.cancelRepositoryOrderRepository.updateStatusColumnorders.statusGuardorder.isShipped()Libraryjakarta.validation @ValidPossible callerSupportController.overrideMap stops hererefunds.dispatch(event)Possible readerNightlyExportJob.run
An illustrative code graph for order cancellation. Confirmed links run from the route to the handler, service, repository and status column. A support controller is a possible caller, a nightly export job is a possible reader, validation is a library call, and the refund dispatch is unknown, so the map stops there.

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.

Database schemastatus VARCHAR(20) NOT NULL

Never empty

V12__orders.sql:7
ORM mapping@Column(nullable = true) private String status;

May be empty

Order.java:31
API contractstatus?: OrderStatus

Optional

openapi.yaml:212

Three 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.

performschangesguardsperformsfromtoENTITYCustomerACTIONCancel orderFIELDOrder.statusRULEShipped orders stay putENTITYSupport agentSTATEPLACEDSTATECANCELLED
  • 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.

Proposed changeRequire a reason when a customer cancels an order

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}/cancel
  • SupportController.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.