# Atlas Reconcile

> Syncs the team's documents, work artifacts and knowledge base with what was actually built, by listing every place two layers disagree as a finding with both sides cited, asking the team to decide each one, and then updating only what a person's decision says is wrong. Use when someone asks to sync, reconcile, refresh or realign docs with the implementation, to find stale or contradictory documentation, or to go through the open findings with the team.

- Skill: `chauthehienp3c1/atlas-reconcile` (Agent Skill)
- Install (CLI): `npx get-skill add chauthehienp3c1/atlas-reconcile`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chauthehienp3c1/atlas-reconcile/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: chauthehienp3c1 (https://skillmd.com/u/chauthehienp3c1)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/chauthehienp3c1/atlas-reconcile

---


# 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

1. **Scope it.** Ask what to reconcile if it is not stated: one work item (`work/<ID>/`), a `kb/` area, or everything that changed since a commit. Run `node scripts/check-stale.mjs` for the pages whose sources changed, and `node scripts/findings.mjs list --open` for what is already filed.
2. **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 to `atlas-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.mjs` finds the stale pages.
3. **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 to `kb/open-questions.md` with a person to ask (the author, the reviewer, the speaker in the transcript).
4. **Do not edit anything to resolve a mismatch.** (Stale pages are not edited here either: `atlas-refresh` does 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 run `node scripts/findings.mjs decide` and do not edit `status` or `decision` in a finding: only a person at a terminal closes one.
5. **Present the lists** to the user: the refresh candidates (page, what the code now says, `atlas-refresh` to 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-mismatch` in their own terminal.
6. **After people have decided** (the finding is `decided`, with their name and date), and only then:
   - `document-is-wrong`: update the document. For a `kb/` page, use the `atlas-refresh` skill (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-work` reports `decision-outdated`): ask the person again.
7. **Regenerate and check**: `node scripts/findings.mjs index` (updates `findings/index.md` and `kb/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`.
8. **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.

