Atlas refresh
The knowledge base is only useful while it is true. Sources move (code changes, docs get edited, new transcripts appear) and each page records what it was
checked against (verified_at and sources[].paths), so we can tell which pages might be wrong without re-reading everything. This skill does the re-checking,
only where it is needed, and packages the result as a change a teammate can review, because a refresh is itself a claim that things are still true.
AGENTS.md governs the standards. In particular: re-verification means looking at the code (or the source) again, not rereading the page and agreeing with it. Concretely, every statement on a refreshed page is re-cited: its footnote is rewritten from the current source (new commit, new lines, a quote copied from the current text), and a second
agent (atlas-verify) checks the result. Changing a citation's commit number without re-reading the code is the cheap way to make a stale page look fresh; the verifier exists to catch it, and you are not allowed to be that verifier.
1. Get the report
- Make sure sources are current: run
node scripts/sync-sources.mjs (add --pull only if the user asks you to pull their clones; a fetch or pull is theirs to decide). It records each registered clone's commit, fetches pull requests again, re-ingests export files that changed, says plainly what it could not do, and ends with the report below. Anything it lists as "cannot" (a Confluence or OneDrive export, a recording) needs the user to export it again into sources/exports/ under the same name; then run node scripts/ingest.mjs folder and sync again. Do not pretend such a source is current. Full steps: .atlas/docs/refresh.md.
- The report is the end of the sync output (or run
node scripts/check-stale.mjs). Exit status 2 means there are findings. It groups pages as:
- Stale: confirmed. Files under the page's
paths changed since its verified_at.commit, or a non-repo source changed after the page was verified.
- Possibly stale: it could not confirm (no local clone, or the page's commit is missing from the clone). Treat as stale until you check.
- Cites a source that is not in the manifest: fix the citation or ingest the source.
- Aging: not re-verified for a long time even though no change was detected. Spot-check these rather than rewrite them.
The report lists what it could not see. Read that section: a clean report from a run without local clones proves less than it looks.
2. Re-verify only the affected pages
For each page in the report, in order of how many readers depend on it (use the roles field and kb/index.md):
- See what changed. For repo sources:
git -C <clone> diff <old-commit>..HEAD -- <paths> (and git log for intent: commit messages and PRs tell you why).
For documents: compare the new normalized file with what the page says.
- Re-check each statement the changes could touch against the code or source, as you would when writing the page fresh, using
node scripts/cite.mjs to find the current lines. Keep the page's structure; change only what is
now wrong or incomplete. A statement whose citation no longer resolves (the quote is gone, the lines moved, the file was deleted) is not "stale wording": the source no longer says it.
- Update the evidence. If a statement is no longer supported by a source, remove it or move the question to
kb/open-questions.md; do not leave it standing, and do not weaken it to "was". If a statement now rests only on a doc, the page becomes documented-only. A statement that no longer holds is
corrected; one that vanished is removed. Never turn a gap into an inference to keep a page whole: the gap is a question.
- Re-stamp
verified_at with today's date and the repo's current commit (git -C <clone> rev-parse HEAD) only when you re-checked the whole page, and re-cite every code citation at that commit (the linter requires it). If you only checked part of it, leave
the stamp, and say in the page which part is newly checked. A stamp is a promise that the page was checked at that point; do not make it cheaply.
- If a page's subject was removed from the system, retire the page (delete it, and note it in the changelog) rather than leaving a description of something that no longer exists.
Fix links to it.
- If the update reveals the page contradicts a doc or an approved artifact, do not quietly rewrite the page to one side. File a finding with both sides cited (
node scripts/findings.mjs new ...; node scripts/findings.mjs list first). If you hit a question only a person can answer, put it on
kb/open-questions.md with someone to ask.
Do not touch pages that are not in the report unless you notice they are wrong; then fix them, and say so.
3. Regenerate and record
Run the atlas-verify skill on every page you changed (a separate agent checks the new text against the sources; you may not check your own refresh). Then node scripts/sync-status.mjs, node scripts/build-index.mjs and node scripts/lint-kb.mjs; fix everything reported.
Editing a page voids its earlier second-agent check and human review (the banner says so), which is why the pull request needs a person to run node scripts/review.mjs on pages that matter.
node scripts/check-stale.mjs again: the pages you re-verified should be gone from the report. If one is still listed, you either did not re-stamp it or the cause is
something else (read the reason).
Update CHANGELOG.md: convert ## Unreleased into a dated entry (and start a fresh empty ## Unreleased above it):
## 2026-11-15 - refresh (app-repo a1b2c3d, design-doc)
- Updated `kb/flows/place-order.md`: payment now retries once; evidence still Verified.
- Corrected `kb/system/map.md`: the notifier is a separate service as of this commit.
- Retired `kb/system/legacy-cron.md` (removed from the code in a1b2c3d).
- Still open: `kb/delivery/release.md` could not be re-verified (no access to the deploy config).
Say what changed in the team's understanding, in terms a reader catching up would care about, not which files were edited.
4. Package for review
The workspace is a git repository, and a refresh is meant to be a pull request that a current team member reviews.
- Offer to create a branch
atlas/refresh-<date> and commit the changes with a message summarising the changelog entry.
- Do not push, open the pull request or merge unless the user explicitly asks. If they do, open the PR with the changelog entry as its description and ask for a review from
someone who knows the affected areas (the people in the commit history of those paths).
- Tell the user what you re-verified, what you changed, what you could not re-verify and why.
What the weekly workflow does (and does not)
The weekly GitHub workflow runs check-stale in CI, where the team's code repositories are not checked out. It can therefore report: pages whose source documents changed after
they were verified, pages whose repo commit differs from the manifest's commit (as "possibly stale"), pages citing unknown sources, and pages not verified for a long time. It cannot see new
commits in a code repo that nobody has re-ingested. That is why a person (or you) re-ingests repos before a refresh, and why a quiet weekly report is not proof that nothing changed.
For the same reason lint-kb in CI reports code citations as unchecked (it cannot open the code), not as passed: run node scripts/lint-kb.mjs --require-checked locally with your clones registered to resolve them. Citations to documents, transcripts and PRs are checked in CI, including against edits
to the normalized files.
1---2name: atlas-refresh3description: Refreshes the team knowledge base by finding which pages are stale, re-verifying only those pages against current code and sources, updating verified_at, regenerating the index and adding a CHANGELOG entry, ready for review as a pull request. Use when check-stale or the weekly freshness report lists pages, when sources have changed, or when someone asks to refresh, update or re-verify the knowledge base.4disable-model-invocation: true5metadata:6 source: https://skillmd.com/skills/chauthehienp3c1/atlas-refresh7---89# Atlas refresh1011The knowledge base is only useful while it is true. Sources move (code changes, docs get edited, new transcripts appear) and each page records what it was12checked against (`verified_at` and `sources[].paths`), so we can tell which pages might be wrong without re-reading everything. This skill does the re-checking,13only where it is needed, and packages the result as a change a teammate can review, because a refresh is itself a claim that things are still true.1415`AGENTS.md` governs the standards. In particular: re-verification means looking at the code (or the source) again, not rereading the page and agreeing with it. Concretely, every statement on a refreshed page is **re-cited**: its footnote is rewritten from the current source (new commit, new lines, a quote copied from the current text), and a second16agent (`atlas-verify`) checks the result. Changing a citation's commit number without re-reading the code is the cheap way to make a stale page look fresh; the verifier exists to catch it, and you are not allowed to be that verifier.1718## 1. Get the report19201. Make sure sources are current: run `node scripts/sync-sources.mjs` (add `--pull` only if the user asks you to pull their clones; a fetch or pull is theirs to decide). It records each registered clone's commit, fetches pull requests again, re-ingests export files that changed, says plainly what it could not do, and ends with the report below. Anything it lists as "cannot" (a Confluence or OneDrive export, a recording) needs the user to export it again into `sources/exports/` under the same name; then run `node scripts/ingest.mjs folder` and sync again. Do not pretend such a source is current. Full steps: `.atlas/docs/refresh.md`.212. The report is the end of the sync output (or run `node scripts/check-stale.mjs`). Exit status 2 means there are findings. It groups pages as:22 - **Stale**: confirmed. Files under the page's `paths` changed since its `verified_at.commit`, or a non-repo source changed after the page was verified.23 - **Possibly stale**: it could not confirm (no local clone, or the page's commit is missing from the clone). Treat as stale until you check.24 - **Cites a source that is not in the manifest**: fix the citation or ingest the source.25 - **Aging**: not re-verified for a long time even though no change was detected. Spot-check these rather than rewrite them.26 The report lists what it could not see. Read that section: a clean report from a run without local clones proves less than it looks.2728## 2. Re-verify only the affected pages2930For each page in the report, in order of how many readers depend on it (use the `roles` field and `kb/index.md`):31321. **See what changed.** For repo sources: `git -C <clone> diff <old-commit>..HEAD -- <paths>` (and `git log` for intent: commit messages and PRs tell you why).33 For documents: compare the new normalized file with what the page says.342. **Re-check each statement the changes could touch** against the code or source, as you would when writing the page fresh, using `node scripts/cite.mjs` to find the current lines. Keep the page's structure; change only what is35 now wrong or incomplete. A statement whose citation no longer resolves (the quote is gone, the lines moved, the file was deleted) is not "stale wording": the source no longer says it.363. **Update the evidence.** If a statement is no longer supported by a source, **remove it** or move the question to `kb/open-questions.md`; do not leave it standing, and do not weaken it to "was". If a statement now rests only on a doc, the page becomes `documented-only`. A statement that no longer holds is37 corrected; one that vanished is removed. Never turn a gap into an inference to keep a page whole: the gap is a question.384. **Re-stamp** `verified_at` with today's date and the repo's current commit (`git -C <clone> rev-parse HEAD`) **only when you re-checked the whole page**, and re-cite every code citation at that commit (the linter requires it). If you only checked part of it, leave39 the stamp, and say in the page which part is newly checked. A stamp is a promise that the page was checked at that point; do not make it cheaply.405. If a page's subject was removed from the system, retire the page (delete it, and note it in the changelog) rather than leaving a description of something that no longer exists.41 Fix links to it.426. If the update reveals the page contradicts a doc or an approved artifact, do not quietly rewrite the page to one side. File a finding with both sides cited (`node scripts/findings.mjs new ...`; `node scripts/findings.mjs list` first). If you hit a question only a person can answer, put it on43 `kb/open-questions.md` with someone to ask.4445Do not touch pages that are not in the report unless you notice they are wrong; then fix them, and say so.4647## 3. Regenerate and record48491. Run the `atlas-verify` skill on every page you changed (a separate agent checks the new text against the sources; you may not check your own refresh). Then `node scripts/sync-status.mjs`, `node scripts/build-index.mjs` and `node scripts/lint-kb.mjs`; fix everything reported.50 Editing a page voids its earlier second-agent check and human review (the banner says so), which is why the pull request needs a person to run `node scripts/review.mjs` on pages that matter.512. `node scripts/check-stale.mjs` again: the pages you re-verified should be gone from the report. If one is still listed, you either did not re-stamp it or the cause is52 something else (read the reason).533. Update `CHANGELOG.md`: convert `## Unreleased` into a dated entry (and start a fresh empty `## Unreleased` above it):5455 ```markdown56 ## 2026-11-15 - refresh (app-repo a1b2c3d, design-doc)5758 - Updated `kb/flows/place-order.md`: payment now retries once; evidence still Verified.59 - Corrected `kb/system/map.md`: the notifier is a separate service as of this commit.60 - Retired `kb/system/legacy-cron.md` (removed from the code in a1b2c3d).61 - Still open: `kb/delivery/release.md` could not be re-verified (no access to the deploy config).62 ```63 Say what changed in the team's understanding, in terms a reader catching up would care about, not which files were edited.6465## 4. Package for review6667The workspace is a git repository, and a refresh is meant to be a pull request that a current team member reviews.68691. Offer to create a branch `atlas/refresh-<date>` and commit the changes with a message summarising the changelog entry.702. Do **not** push, open the pull request or merge unless the user explicitly asks. If they do, open the PR with the changelog entry as its description and ask for a review from71 someone who knows the affected areas (the people in the commit history of those paths).723. Tell the user what you re-verified, what you changed, what you could not re-verify and why.7374## What the weekly workflow does (and does not)7576The weekly GitHub workflow runs `check-stale` in CI, where the team's code repositories are **not checked out**. It can therefore report: pages whose source documents changed after77they were verified, pages whose repo commit differs from the manifest's commit (as "possibly stale"), pages citing unknown sources, and pages not verified for a long time. It cannot see new78commits in a code repo that nobody has re-ingested. That is why a person (or you) re-ingests repos before a refresh, and why a quiet weekly report is not proof that nothing changed.79For the same reason `lint-kb` in CI reports code citations as **unchecked** (it cannot open the code), not as passed: run `node scripts/lint-kb.mjs --require-checked` locally with your clones registered to resolve them. Citations to documents, transcripts and PRs are checked in CI, including against edits80to the normalized files.