Atlas reconcile
Documents go stale against the implementation. This skill finds the differences and puts the choice in front of a person; it never decides which side is right. In this workspace the authority depends on the question (AGENTS.md, "Authority"): the code answers what exists today, the approved artifact answers what was intended, and a difference between them is a finding for the team.
Read WORKING-AGREEMENT.md and the "Work artifacts" section of AGENTS.md first.
Steps
- Scope it. Ask what to reconcile if it is not stated: one work item (
work/<ID>/), akb/area, or everything that changed since a commit. Runnode scripts/check-stale.mjsfor the pages whose sources changed, andnode scripts/findings.mjs list --openfor what is already filed. - Compare the layers you were asked about, and sort each difference into one of two kinds:
- A page that describes the code is stale. A
kb/page of what exists today (a flow, a component, a lifecycle) is a derived view of the code. When the code moved on, the page is out of date; that needs no decision about intent. Do not file a finding for it. List it as a refresh candidate with what changed (the old and new lines), and leave it toatlas-refresh, whose result goes through a pull request the team reviews. - Two statements of intent or of fact disagree. A document, an original, an approved artifact, a decision page or an artifact's parent against the code, against
kb/, or against each other; a change against its brief (node scripts/scope-check.mjs). Someone has to say which is right, so each is a finding (step 3). Read the sources; do not rely on a page's own claim of being current.node scripts/check-stale.mjsfinds the stale pages.
- A page that describes the code is stale. A
- File one finding per disagreement of the second kind with both sides cited:
node scripts/findings.mjs new --title "..." --expected "<one sentence>" --expected-cite "<citation>" --observed "<one sentence>" --observed-cite "<citation>" [--affects <path>]. Say each side in a plain sentence and add no judgement (no severity, no "bug"). Check the open list first so you do not file a duplicate. Where only one side can be cited, it is a question: add it tokb/open-questions.mdwith a person to ask (the author, the reviewer, the speaker in the transcript). - Do not edit anything to resolve a mismatch. (Stale pages are not edited here either:
atlas-refreshdoes that, with a check and a reviewed pull request.) Do not change a document to match the code, or the reverse, and do not conclude "the code wins". Do not runnode scripts/findings.mjs decideand do not editstatusordecisionin a finding: only a person at a terminal closes one. - Present the lists to the user: the refresh candidates (page, what the code now says,
atlas-refreshto update it), and for each open finding, the two sides in one line each with where to look, and the question "is the document wrong, is the code wrong, was it intended, or is it not a mismatch?". Tell them how to record the answer:node scripts/findings.mjs decide F-NNNN --resolution document-is-wrong|code-is-wrong|intentional|not-a-mismatchin their own terminal. - After people have decided (the finding is
decided, with their name and date), and only then:document-is-wrong: update the document. For akb/page, use theatlas-refreshskill (new citations, new check). For a work artifact the owner owns, say what should change and let the owner edit and re-approve it.code-is-wrong: leave the document alone and tell the user it is now a task for the team; you do not change the code in this skill.intentional: if the knowledge base should record that the difference is deliberate, add it with the finding as the cited evidence; the finding's note says why.not-a-mismatch: change nothing. A decision becomes outdated if the finding changes afterwards (lint-workreportsdecision-outdated): ask the person again.
- Regenerate and check:
node scripts/findings.mjs index(updatesfindings/index.mdandkb/doc-vs-code.md, both generated and never edited by hand),node scripts/sync-status.mjs,node scripts/build-index.mjs,node scripts/lint-kb.mjs. - Tell the user how many findings are open and decided, which pages are stale and waiting for
atlas-refresh, which pages you updated and on whose decision, and what you did not look at. Open findings are listed in the weekly freshness job so they do not sit forever.
This skill cannot find a mismatch nobody wrote down on either side, and it cannot tell which side is right. It makes the differences visible and puts the choice with the people who own it.