# Atlas Brief

> Generates the detail one role needs to pick up an approved story or feature (developer, QA, designer, analyst or any other role the team defines) from what exists today, cited to code or sources, plus clearly labelled agent proposals, the files expected to change, and open questions. Use when someone is about to start work on a story and asks for a brief, a task breakdown, implementation notes, test ideas or what they need to know to start.

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

---


# Atlas brief

The story stays short on purpose; the detail is generated now, for the person who is starting, and is thrown away or regenerated when the work changes. This is the **one place** where you may write something no source says, and only under the label "Proposed".
Read `WORKING-AGREEMENT.md` and the "Work artifacts" section of `AGENTS.md` first.

## Steps

1. **Find the inputs.** The story (or feature) the user names, its parent chain and its design note, if any. Run `node scripts/lint-work.mjs`: fix nothing in an artifact you do not own, but tell the user about errors in the story, and say plainly if it is **not approved** (its banner says so), because the brief then rests on a draft.
2. **Ask which role** if it is not stated. Use the team's role names (`roles/`, `atlas.config.yaml`); do not assume the reader is a developer.
3. **Scaffold**: `node scripts/work.mjs new brief <ID> --role <role> --owner "<name>" --origin agent --parent work/<ID>/story.md`. The brief is `work/<ID>/brief-<role>.md`; add `paths:` to its frontmatter (see step 6).
4. **Read what exists**, for this role: the `kb/` pages on its reading path, the code at the commit of the registered clone (`.atlas/local.yaml`), the ingested sources the story cites. Read the code the story is about, not only the knowledge base: pages can be stale (`node scripts/check-stale.mjs`).
5. **Write the sections** (about 600 words at most; shorter is better):
   - **Goal**: one or two lines in the words of the story's acceptance criteria, with a link to the story. Do not restate the story.
   - **What exists today**: facts only, and only those this role needs to start (not a tour of the system). Each line cites code at a commit (`[repo@sha] path:lines`), or an ingested source with a verbatim quote. It is linted exactly like a `kb/` page and checked by a second agent. If you cannot cite it, it is not a fact: put it under Open questions.
   - **Proposed**: starts with the label line already in the template (*Agent proposal. Not fact, not approved by anyone, and never copied into kb/.*). Suggested approach, examples, edge cases, test ideas for this role. Keep each item short and phrased as a suggestion. Never present a proposal as how the system works, and never invent a requirement: a proposal that goes beyond the story is a suggestion for the owner to take or leave.
   - **Scope**: the files or folders expected to change, matching `paths:` in the frontmatter, and what the brief does not cover. `paths:` is what `scope-check` compares the change with, so name folders the work really needs and no more.
   - **Open questions**: what the sources do not answer, as questions, with a person to ask where git or the sources show one.
6. **When the story contradicts what exists** (the code does not match, a status or field is named differently, a rule is already implemented some other way): do not adjust the story and do not hide it in the brief. File a finding (`node scripts/findings.mjs new ...`, both sides cited; list first to avoid a duplicate) and mention it under Open questions.
7. **Check it**: `node scripts/lint-work.mjs`, `node scripts/sync-status.mjs`, then the `atlas-verify` skill on the brief (a separate agent checks that each cited line supports the statement). A proposal is not checked as a fact, only that it is labelled.
8. **Tell the user** what the brief rests on (`node scripts/work.mjs list` shows its words against the budget) (approved story or draft), how many of its lines are cited facts and how many are proposals, the findings and questions you raised, and that nothing in the brief has been copied into `kb/`. If something here is worth recording as knowledge, it goes through `atlas-refresh` with its own citations, never by copying from a brief.

A brief is not approved by anyone. Do not write `approval`, and do not link to a brief from a `kb/` page: the linter rejects it.

