# Atlas Shape

> Shortens a long, repetitive or AI-generated original (a requirements document, epic, feature, user story or meeting notes) into a one-screen work artifact in which every line cites the original word for word, lists what was left out, and files a finding when the original contradicts the code or the knowledge base; or, in gate mode, reviews a draft artifact for clear scope before the team approves it. Use when someone asks to slim, trim, simplify or shape a requirement, epic, feature or story, to turn a long document into a short one, or to check that a draft artifact is ready to approve.

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

---


# Atlas shape

People own intent and decisions; you produce a shorter version and check it. The test of your work: **the owner reads less and decides more clearly, and nothing they needed was lost or made up.**
Read `WORKING-AGREEMENT.md` (one page) and the "Work artifacts" section of `AGENTS.md` first.

There are two modes. Ask which one if it is not clear.

## Slim mode: shorten an original

Input: an original that is ingested as a source (`sources/manifest.yaml`). If it is not ingested yet, use the `atlas-ingest` skill first; do not paste its text anywhere else.

1. **Read the whole original** (`node scripts/cite.mjs show <source-id>` shows it with line numbers). Do not skim: the one rule that matters is often in the middle of a section about something else.
2. **Pick the kind and the ID with the user**, then scaffold: `node scripts/work.mjs new <kind> <ID> --owner "<name>" --origin <source-id> --derived-from <source-id> [--parent work/<ID>/<parent-kind>.md] [--tier small|medium|high]`.
   Work IDs and kinds are validated; do not create files in `work/` by any other route. The kinds and their sections are in `atlas.config.yaml` (`lifecycle`) or the engine defaults; read the template the script created.
3. **Fill the sections with what the original says, and nothing else.**
   - Every line states **one** thing the original states and carries a footnote with a verbatim quote and its lines: `[^1]: [<source-id>] L63-63 "exact words from the original"`. A short quote of the key words is enough.
   - Keep every number, limit, time, condition and exception exactly as the original gives it. Never make a rule stronger, weaker or more general ("should" stays "should").
   - Do not add a requirement, a risk, a metric, an assumption or an "obvious" edge case. Do not fill a gap. A gap or an unclear point is an **open question** for the owner.
   - **Out of scope** holds only what the original says is out of scope. If it says nothing, write exactly `Not stated in the original.` and nothing else; do not invent exclusions.
   - **Acceptance criteria**: one numbered line per condition a person could check yes or no, each citing the original. If the original repeats a condition, say it once and cite both places. A vague wish ("delightful", "timely", "best practice") that nobody could check is not a criterion: leave it for the left-out list, where the owner will see it.
   - **Say each thing once.** The objective is one sentence; *In scope* names what changes in a few words and does not restate the objective; the criteria say how it is checked and do not restate *In scope*.
   - Boilerplate (vision, stakeholders, "delight the customer", generic risks and definitions of done) is left out, **but only after you have looked for a rule hidden in it**. Do not decide that a line with a "must", a limit or a number is boilerplate: carry it, or leave it for the owner to see in the left-out list.
4. **When the original contradicts something that exists** (the code at a commit, a `kb/` page, another approved artifact): do not pick a side and do not edit either. First run `node scripts/findings.mjs list` to see whether it is already filed, then raise it:
   `node scripts/findings.mjs new --title "..." --expected "<one sentence>" --expected-cite "<citation>" --observed "<one sentence>" --observed-cite "<citation>" --affects work/<ID>/<kind>.md`.
   Both sides must be cited. Add an open question to the artifact that points to the finding, and carry the original's wording faithfully; the owner decides. A gap with only one side to cite is an open question instead.
   This holds for any two sources that disagree (the original and a meeting transcript, the original and a `kb/` page), whatever their trust tier: if both sides can be cited, it is a finding, and the open question only points to it. Do not cite a second source in the artifact itself except in such a question.
5. **Propose a tier** (feature and story): say which trigger from `WORKING-AGREEMENT.md` the original matches, citing it, or why none does. Write it into the artifact's `tier:`; the owner's approval is what confirms it. High calls for a design note by a person.
6. **Check it mechanically**: `node scripts/lint-work.mjs` (fix every error; a warning about size means cut more, or the owner gives a `budget_reason`), then `node scripts/sync-status.mjs`.
7. **List what you left out**: `node scripts/left-out.mjs work/<ID>/<kind>.md`. Read the three piles. Everything in the first pile (a rule, limit or number) must either be in the artifact or be named to the user as left out on purpose, with the line number. Do not add anything to `CHANGELOG.md`: it records `kb/` pages, not work artifacts.
8. **Have it checked by someone who did not write it.** Run the completeness check in the `atlas-verify` skill (a separate agent judges every uncited block as covered, not relevant or missing). A `missing` verdict means the artifact is incomplete: add the line with its citation, or ask the owner. Do not argue a block into "not relevant".
9. **Tell the user**: words before and after (`node scripts/work.mjs list` shows the artifact's words against its budget; the original's size is in the left-out list), how many blocks were left out and how many of those look like rules, the findings you raised, the open questions, the tier you propose and why, and that the artifact is **not approved**: the owner reads it and runs `node scripts/work.mjs approve work/<ID>/<kind>.md` themselves. Never run it, and never write an `approval`.

## Gate mode: review a draft before approval

Input: a draft artifact (written by a person or an agent). You do not edit it; you report.

1. `node scripts/lint-work.mjs`. Report each error and warning in plain words.
2. Read the artifact and its parent. Report, each with the line it is about: scope that is not explicit; a criterion that no one could check yes or no; a criterion that repeats the parent; an open question that blocks starting; a tier that looks too low for what the text says (name the trigger); a design note missing for a high tier.
3. Check each claim about the existing system against the code or `kb/`. Where it disagrees, file a finding (step 4 above) rather than telling the author to change it.
4. End with a short verdict the owner can act on: ready to approve, or the specific things to settle first. You are one reader's opinion: say what you could not check.

## What this skill cannot do

It cannot tell whether a requirement is right, and it cannot see what the original left out of its own text (something nobody wrote down is not in any list). The mechanical list and the second agent catch a dropped block, not a wrong one. The owner's approval is the only thing that stands behind the artifact.

