# Atlas Refresh

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

- Skill: `chauthehienp3c1/atlas-refresh` (Agent Skill)
- Install (CLI): `npx get-skill add chauthehienp3c1/atlas-refresh`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chauthehienp3c1/atlas-refresh/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-refresh

---


# 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

1. 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`.
2. 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`):

1. **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.
2. **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.
3. **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.
4. **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.
5. 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.
6. 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

1. 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.
2. `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).
3. Update `CHANGELOG.md`: convert `## Unreleased` into a dated entry (and start a fresh empty `## Unreleased` above it):

   ```markdown
   ## 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.

1. Offer to create a branch `atlas/refresh-<date>` and commit the changes with a message summarising the changelog entry.
2. 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).
3. 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.

