# Atlas Ask

> Answers a question about the team's system with evidence and labels, checking the knowledge base first and the sources second, then writes what was learned back into kb/ so the knowledge base grows from use. Use when someone in a team knowledge-base workspace asks how something works, why something is the way it is, who knows about something, or what the team has decided or built.

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

---


# Atlas ask

Someone on the team has a question about the system. Answer it in a way they can trust and repeat, and make sure the next person
who asks the same thing gets the answer from the knowledge base instead of from another investigation. This is the main way the knowledge
base grows after onboarding: every good answer is a page waiting to be written.

`AGENTS.md` (trust order, grounding rules, page style) governs everything below. The reason for the order of work: the knowledge base is
cheaper and already organised, but may be stale; the sources are authoritative but expensive. So you use the first to find your way and the
second to check it.

**The rule that matters most here: answer from the sources, never from what you know.** The person will act on and repeat your answer. If the registered sources (and the pages built from them) do not contain the answer, the correct answer is
"the sources I have do not say", plus a question on `kb/open-questions.md`. A confident answer assembled from general knowledge of how such systems work is the failure this repository exists to prevent. Before answering anything team-specific, confirm there are sources:
`node scripts/doctor.mjs --require-sources`; if none are registered, say so and point to `atlas-ingest` instead of answering.

## 1. Consult the knowledge base first

1. Read `kb/index.md`. Open only the pages that look relevant; the index is there so you do not read everything.
2. For each page you rely on, look at its `evidence`, `verified_at` and `sources`. A page may be stale: run
   `node scripts/check-stale.mjs` and see whether it is listed. If it is, tell the user, and either re-verify the part you rely on (step 2)
   or say that the answer comes from a page that may be out of date.
3. If a page is a placeholder (`status: placeholder`), it holds no knowledge. Treat the question as unanswered by the knowledge base.
4. Read each page's review banner under its title and repeat it: a page that no human has reviewed is an agent draft, and one whose second-agent check is missing or out of date has not had its citations judged. Say which, in a few words, when you rely on it.

## 2. Consult the sources if the kb does not settle it

Go in trust order (code, tests, config and CI first; then git history and PRs; tickets; transcripts; human docs; AI-generated or undated docs last).

- **Code lives outside the workspace.** Find the local clone in `.atlas/local.yaml` (`repo_paths`) or ask the user where it is. Read it in place;
  do not copy it into the workspace.
- **Everything else** is in `sources/normalized/`, listed in `sources/manifest.yaml` with a trust tier and a reliability verdict. A source marked
  `stale` or `unverified` is a claim to check against the code, not a fact.
- A doc that disagrees with the code: the code is the evidence for what exists today, but do not pick a side or edit either. Say in the answer that they disagree and what each says, and file a finding (see below); the team decides which is wrong.
- A meeting transcript that says something was decided: confirm it against code, a PR or a ticket before saying it happened.
- If you can run something locally to check (a test, a build), that is stronger than reading; never touch shared environments or deploy.

## 3. Answer, with citations

Give the answer first, in plain language, then the support: for each statement, a citation the person can open (file and lines at a commit, a page, a PR number, a transcript time) with a short verbatim quote for anything that is not code. Say whether each rests on
code or git history (**verified**) or only on a document or transcript (**documented only**). Stay close to what the source says: do not strengthen it, widen it, or add a reason it does not give. A name, number or product term that appears only in a transcript is
quoted as what was said, because speech-to-text mangles them; confirm it in another source before stating it as fact.

If the sources do not say, write "the sources I have do not say this", not an answer. Do not fill the gap with what is usual for such systems. If you notice something that looks true but no source states it ("it looks like X because of Y"), do not state it as an answer: put it on
`kb/open-questions.md` as a question ("it looks like X because of Y; confirm with Z"), and tell the person it is a question. For anything that lives in people's heads (why a decision was made, what is about to change), name a person worth asking and why, drawn from who wrote or reviewed the relevant code
(`git log -- <path>`, `git blame`, PR reviewers) and cite that.

**General background** can help a newcomer (what a message queue is). Give it only when it helps, in a separate paragraph that begins **General background (not about this team):**, and never mix it into a sentence about how this team's system works. It does not go into `kb/` pages.

## 4. Write what you learned back

Do this in the same turn, unless the question was trivial or personal (for example, "where is my local clone?"):

- **New page** when the answer is a topic someone will look up again and no page covers it: copy the right template from `templates/` (`page.md`,
  `flow.md`, `component.md` or `decision.md`), keep it to about five minutes of reading, one diagram at most, a footnote citation on every statement, definitions in the evidence section at the bottom.
  Set `verified_at` to today's date and the repo's current commit (`git -C <clone> rev-parse HEAD`), cite code at that commit, and list the `sources[].paths` the claims rest on.
  Only what you could cite goes in; the rest of your answer stays in the conversation or becomes a question.
- **Update an existing page** when it covers the topic but was incomplete or wrong. Change only what you checked, keep its structure, and re-stamp
  `verified_at` **only if you re-checked all of the page's statements**; otherwise leave the stamp and say in the page which parts are newly checked. Any edit invalidates the page's earlier second-agent check and human review (their banner will say so).
- **A finding** for each contradiction you found: `node scripts/findings.mjs new --title "..." --expected "..." --expected-cite "<citation>" --observed "..." --observed-cite "<citation>"` (both sides cited; `node scripts/findings.mjs list` first, to avoid a duplicate). `kb/doc-vs-code.md` is generated from the findings; never edit it by hand. Only a person closes a finding.
- **`kb/open-questions.md`** for each gap or unconfirmed observation (the question, why it matters, who to ask).
- **`kb/glossary.md`** for a term the team uses that the glossary lacks, defined only as a source defines it.
- If a page was a placeholder, replace its placeholder text and remove `status: placeholder`; the page then needs `sources`, `verified_at`, `evidence` and a citation on every statement.

Then run the `atlas-verify` skill on every page you added or changed (you cannot check your own work; if you cannot start a separate agent, say so and leave them unverified). After it passes, run `node scripts/sync-status.mjs`, `node scripts/build-index.mjs` and
`node scripts/lint-kb.mjs`, fix what they report, and add a line under `## Unreleased` in `CHANGELOG.md` (`Added`, `Updated` or `Corrected`, with the page path).
The linter and the verifier do not make a page true: say what the page's banner says, no more.

Tell the user which pages you added or changed, and that none is reviewed by a human yet. Offer to commit them on a branch for a teammate to review (they run `node scripts/review.mjs`); do not push or open a pull request unless asked.

## Judgement calls

- **Evidence label of a page** follows from its citations (`AGENTS.md`, rule 5): `verified` only if every statement cites code or git history/PRs. If one statement rests on a doc or transcript, put it on a separate page or mark the page `documented-only`. Inferences are not a label here: they are questions.
- **Unsure whether to create a page?** If the answer took you real investigation (more than a quick lookup), someone will need it again: write it.
- **The question is about people or process** that no source records (for example, "who approves releases?"): do not invent an answer; record the question
  and who might know.
- **Never copy secrets, credentials or personal data** into a page, even if you saw them while investigating. Say where they are configured.

