# Atlas Onboard

> Walks a new team member through catching up on the team's system, tailored to their role (developer, tech lead, solution designer or architect, BA/product, designer, QA or other), and builds that knowledge into the workspace knowledge base. Use when someone joins the team, asks to be onboarded, wants a role-specific reading path, or runs /atlas-onboard.

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

---


# Atlas onboard

A person has joined a team that already has a lot of material: code, pull requests, tickets, meeting transcripts and a
large amount of documentation, much of it AI-generated, so fluent but of unknown accuracy. Your job is to get them
productive quickly *and* leave the workspace knowledge base better than you found it, so the next person starts further ahead.

Read `AGENTS.md` first if it is not already in context: the trust order, grounding rules and page style there apply to
everything below. The reasoning behind the main rules, so you can handle cases this skill does not cover:

- **Code is the highest source, and docs are claims.** New joiners believe what they read and repeat it to the team. A doc that
  sounds right but describes last year's system does more harm than no doc. So you verify before you assert.
- **Gaps become questions, not guesses.** "I could not find this" is useful and honest; a plausible invention is not. Put gaps on
  `kb/open-questions.md`, with a suggested person to ask (who wrote or reviewed the code).
- **A page contains only what a registered source states, with a citation.** Not your reasoning, not what a system like this usually does, not a summary of your impressions. The person will repeat what they read here to the team, so a
  fluent sentence with no source behind it is the most expensive thing you can write. `AGENTS.md` ("Grounding") has the rules and the citation format; a script checks them and a second agent verifies the rest.
- **Stop at the end of each stage.** The person knows things you do not (what they care about, what they already know). Let them steer.
- **Wide and shallow first, deep only where their role and first task need it.** Ten shallow-but-true pages beat one deep tangent.

## Step 0: Read the workspace before doing anything

1. Read `atlas.config.yaml` (roles, declared sources), `sources/manifest.yaml` and `kb/index.md`.
2. Decide which situation you are in:
   - **Empty knowledge base**: every page under `kb/` has `status: placeholder`, and the manifest has no sources. You are the first
     joiner; you will build the pages as you go (stages 1-3 below say which).
   - **Knowledge base has content**: a previous joiner or the team has been here. Follow "When the knowledge base already has
     content" at the end, instead of re-investigating from scratch.
3. Check the tools: `node scripts/doctor.mjs`. Missing tools matter only for the sources the person actually has.
4. **No sources, no pages.** Run `node scripts/doctor.mjs --require-sources`. If it fails (nothing is registered), you may still do the intake and help register sources with the `atlas-ingest` skill, but **write no page under `kb/`** until at
   least one source is registered, and say so plainly. If the person has nothing to ingest yet, tell them what could be (a local clone of the team's code, exports of design docs, meeting transcripts, pull requests) and stop here. Never produce a
   plausible-looking orientation from general knowledge of the domain, the team's name, or the contents of this skill.

## Intake

Ask these before starting, in one message, skipping anything the person has already said, and skipping sources that are already in `sources/manifest.yaml` (check it first, and ask only about what is missing):

1. **Role**: developer, tech lead, solution designer (or architect), BA or product, designer, QA, or something else.
2. **Background**: what they already know (the domain, the tech stack, similar systems). This sets how much to explain.
3. **First task or area** they will own, if known.
4. **Time available** to catch up (a day? two weeks?). This decides how deep stage 3 goes.
5. **Sources outside the repo**: Confluence, OneDrive/SharePoint, Rally or Jira, shared drives, meeting recordings, anything else.
   Also ask for the **paths of local clones of the team's code repositories**; you cannot verify anything without the code. If the manifest already lists the repository (a member cloning a workspace the team has), do not re-ingest it (that would replace the snapshot the existing pages cite): write the clone's path into `.atlas/local.yaml` (`repo_paths: {<source id>: <path>}`, git-ignored) and run `node scripts/lint-kb.mjs` to see the code citations resolve.

Once you have the role (and the first task, if they gave one), record it: `node scripts/explore.mjs role <role> --first-task "<one line>"`. It is kept on this machine only (git-ignored, per person), and it is what lets `/atlas-explore` start without asking the same question again. Record what the person said, not what you infer.

For each source, follow the `atlas-ingest` skill (`.cursor/skills/atlas-ingest/SKILL.md`) so it lands in `sources/normalized/`
with a manifest entry. If a source cannot be reached (no access, no adapter yet), say so plainly and carry on; do not fill
the gap from imagination. Raw exports go in `sources/exports/` (never committed).

## Stage 1: Map the sources (keep it short)

Inventory what exists: code repos, doc sets, tickets, transcripts, PRs. Then judge how far each doc set can be trusted by
**spot-checking**:

- Pick a handful of specific, checkable claims in each doc set (file paths, service names, endpoints, config keys, command lines) and
  see whether they exist in the code. Five to ten claims per doc set is enough to tell a reliable doc from a stale one.
- Compare the doc's last-modified date against how much the code it describes has changed since (`git log --since=<date> -- <path>`).
- Docs that sound authoritative but are undated or machine-written are tier 6 in the trust order: treat their claims as claims to check.

Report which docs are worth reading, which are stale, which to ignore, and what could not be accessed. Record each verdict with
`node scripts/ingest.mjs mark <source-id> --reliability reliable|mixed|stale|unverified --note "<what you checked>"`, and
file every contradiction you found as a finding (`node scripts/findings.mjs new ...`: what the doc says and what the code does, each side cited with a citation from `node scripts/cite.mjs`, never a line number typed from memory; `kb/doc-vs-code.md` is generated from these and never edited by hand). A person decides whether the doc is stale or the code is unfinished.

**Stop.** Present the inventory and verdicts; ask whether to continue or adjust.

## Stage 2: One-page orientation, readable in ten minutes

Write `kb/orientation.md` (use `templates/page.md`, `kind: overview`). Every paragraph, list item and table row carries a footnote citation (find locations with `node scripts/cite.mjs`, copy quotes from its output, never from memory). It covers only what the sources state:

- what the product does and for whom
- the main parts and how they connect
- the two or three flows that matter most
- what the team is working on now (last 60 to 90 days of commits, PRs and tickets)
- the vocabulary heard in meetings

with **one flowchart**. Also create or extend `kb/glossary.md` (terms as the team uses them, one line each, linked to where they matter)
and `kb/system/map.md` (flowchart of the main parts) only if every box and arrow is named in a cited statement on the page. Vocabulary from meeting transcripts can go in the glossary as what was said ("the team says X, in the 3 Sep sync", cited with the
transcript time), not as a definition, until the code or a doc confirms it; a name or number that appears only in a transcript is a likely speech-to-text error, so confirm it elsewhere before stating it.

For "what the team is working on now", use git history and PRs first (they show what is actually active), tickets second (intent),
and transcripts last (discussion). Say which is which, citing each (the repo snapshot's commit list, a PR, a ticket export, a transcript turn). Do not summarise a direction or theme the sources do not state.

**Stop.** Ask whether the orientation matches the person's expectations and where they want to go deeper. Offer `/atlas-explore` in one line for a person who does not yet know what to ask: it plays a curious newcomer in their role, proposes the questions this system raises, and answers them from the sources. It is an offer, not a stage: the stages below still stand.

## Stage 3: Depth for the role

Read [role-guides.md](role-guides.md) and follow the section for the person's role. It lists, per role, what to cover, how to
gather it, and which `kb/` page to write it into. Everyone also gets: the glossary, the system map, who owns what (from commit and
review history), and current priorities.

General rules for this stage:

- Prefer **verifying by doing** where it is safe: run local build and test commands to confirm they work. Never deploy, never migrate a
  shared database, never touch shared environments.
- Every statement gets a footnote citation, defined in the page's `## Evidence` section. Set `verified_at` (date and repo commit), cite code at that commit, and list
  `sources[].paths` so `check-stale` can notice when it ages. The page's `evidence:` label follows from the citations (`AGENTS.md`, rule 5).
- What you work out rather than read (counts, rankings, "it looks like", why something was probably done) does not go on a page. Tell the person in the conversation, labelled as your reading, and put what is worth confirming on
  `kb/open-questions.md` as a question with a person to ask.
- Write the findings into `kb/` as pages (not only into the chat) so they outlive this conversation. Use the templates, one
  Mermaid diagram per page at most, of the fixed type for the page kind.
- Create `roles/<role>.md` as a reading path: an ordered list of links into `kb/` with one line on why each matters. Never copy
  content into it. If the role already has a path, extend it only with what this person's role needs.
- Things only people know (why, what is about to change) go on `kb/open-questions.md` with a suggested person to ask. A decision page states the reason only if a source records it (attributed, quoted); otherwise it says no record was found.

Work in this order and **stop after each chunk** the role guide defines (not after every page): the person's time budget from the
intake decides how many chunks you do now.

## Stage 4: The first task (only if one was named)

Cover: the code and docs it touches; the pattern similar past changes followed (find one or two example PRs with
`git log --follow` or `gh pr list --search`, and say what they changed); who to ask (from history and review comments); and what
could go wrong (fragile areas, coupling, hidden dependencies, tests that cover it and tests that do not). Keep this in the conversation unless
parts are useful to everyone, in which case put those parts in the relevant `kb/` page.

## Before anything is proposed: verify

You wrote these pages, so you cannot check them. For **every page you added or changed** (including open-questions and glossary entries; findings are checked by the linter), run the `atlas-verify` skill: a separate agent checks each statement and diagram element against the
cited text, and whatever is not supported is removed or becomes a question. Do this after each stage's pages are written, before presenting them as ready or offering them for commit. If you cannot start a separate agent, say so and leave the pages unverified; their banner then says
"second-agent check: not done". Never tell the person a page is verified, or reviewed by a human, beyond what its banner says.

## After the walk-through: questions and answers

If the person does not know what to ask, point them to `/atlas-explore`. Otherwise stay available for questions in Q&A mode: answer only from the sources, with citations; say "the sources do not say" when they do not, and add the question to `kb/open-questions.md`; mark general background as such and keep it out of statements about the team's system
(`AGENTS.md`, rule 9). Write anything new back to the knowledge base (the `atlas-ask` skill describes how). If the person asks to be tested, ask **five questions** about what they should know by now,
drawn from the pages you built, one at a time, then correct their answers with references (file paths or page links). Do not hint
at answers beforehand, and say when an answer is genuinely uncertain in the knowledge base rather than pretending it is settled.

## When the knowledge base already has content

A previous joiner or the team has been here. The pages are an asset and also a liability if stale, so:

1. Run `node scripts/check-stale.mjs` and read the report. For each page the person's role would read, check what changed since its
   recorded `verified_at.commit` (`git diff --stat <commit>..HEAD -- <paths>`), and update what is out of date (follow the
   `atlas-refresh` skill for the mechanics).
2. Build the role path from existing pages (`roles/<role>.md`): read `kb/index.md` ("By role"), list what exists, and note what is
   missing for this role.
3. Add **only** what this role needs and is missing, using stage 3's role guide as a checklist rather than a script.
4. Still do the intake, and still stop at the end of each stage; the stages become shorter because you are reading, not discovering.
5. Do not delete other people's pages. If a page is wrong, correct it and note the correction in `CHANGELOG.md`; if you cannot tell,
   put the doubt on `kb/open-questions.md`. Pages written before citations existed (a workspace upgraded from engine 0.1) fail the linter until each statement is cited: treat them as drafts to re-cite with `atlas-refresh`, not as sources.
6. Pages that a person has reviewed (their banner says so) are the team's most trusted content: change them only with a reason, and expect the change to need review again.

## Finish

- `atlas-verify` has passed on every page you added or changed (or you have said it could not be run).
- `node scripts/sync-status.mjs`, `node scripts/build-index.mjs` then `node scripts/lint-kb.mjs`; fix everything it reports.
- Add entries under `## Unreleased` in `CHANGELOG.md` for the pages you added or changed.
- Offer to put the changes on a branch (`atlas/onboard-<name>`) and commit them, for a current team member to review as a pull request. The reviewer confirms pages with `node scripts/review.mjs` (you never run it).
  Do not push or open the PR unless asked.
- Tell the person what you could not verify, what you removed or turned into questions because the sources did not support it, and what is on the open-questions list. Say which pages are still unreviewed by a human: all of them, until a teammate runs the review.

