Keeping the understanding honest

Last reviewed: 16 Sep 2026

An understanding is only useful while it is true. Code changes, decisions get reversed, an agent guesses. This page is how the understanding stays honest over months, what each mark means, and the small part that is yours.

The rules agents follow

Four rules, held by the platform rather than by good intentions:

Evidence or it is unverified. An entry about the code cites a file and lines the agent actually opened. Without that it shows as not yet checked, and the next agent knows to treat it as a note.
Supersede, never contradict. When something changes, the agent records a new entry that replaces the old one, with a link back. Two entries that disagree never sit side by side. The history reads as what changed and why.
Dispute, never overwrite. An agent that suspects an entry is wrong but cannot prove it marks it disputed. The entry stays; the flag reaches you.
Say where it came from. Observed means seen in the code or the record. Proposed means the agent's interpretation. A proposed entry is allowed; a proposed entry dressed as observed is not.

The marks, and what to do about each

Not yet checked. Nothing backs it. Ask an agent working in that topic to cite it: "cite the file for the claim about X". Or leave it; agents back-fill citations as they work.
Not checked in N months. It had evidence once and nothing has touched it since. Not wrong, just old. Agents re-check these when they work nearby; the mark clears when new evidence lands.
Re-verify. The file it cites has changed since. A changed file is a prompt to look, not proof of error. The next agent in that topic checks it.
Disputed. An agent thinks it is wrong. This one is yours: it sits in Needs you until you settle it.
Retired. Superseded or dropped. It stays in the history and leaves the map.

Your part

Three things only:

Settle disputes. Let an agent settle it when you do not know; keep it when you do; drop it when it is plainly wrong. A disputed entry left for a week is the one thing that makes the word on Status say At risk.
Dispute what you know is wrong. You know things agents cannot see: the decision made in a meeting, the customer who left. Say "that entry about X is wrong, dispute it" or "record that we reversed the decision on X".
Watch for Drifting. When the word says the code moved and the understanding did not, one agent's re-check fixes it. Ask "re-check the understanding against the recent changes".

What honesty costs

Nothing you do daily. The gates run at the moments that matter: an entry cannot claim a file it did not open; a job cannot close without a commit or an honest "nothing durable"; a title that reads like code is sent back to be rewritten. The understanding grows slower than a chat log and stays readable for it.

Tidying the map

Over time topics drift into near-duplicates (auth and authentication). Ask an agent to "merge the auth areas"; every entry moves and the history stays. Ask it to "describe what the billing area is about" so the map reads like a table of contents. Neither is urgent; do it when the map starts to look untidy.