Teardown Atlas

---
name: teardown
description: Tears down a whole subject the way its professionals see it and renders the result as an interactive 3D exploded view to browse. It starts from the finished product as people meet it, splits it into named parts, knobs, loops and catalogues, and lets the reader open any part to the next level down, so a newcomer finds the questions they did not know to ask. Use when someone starts something new ("I want to make a game", "I want to bake bread"), asks how a kind of thing works or is made, or wants a subject's vocabulary and building blocks. Also use to grow an existing teardown from one of its parts: "go deeper on <part>", "expand <part>", "go wider on <topic>". This skill makes the teardown; to use it on a project, use teardown-lookup, teardown-apply or teardown-audit.
---

# Teardown

A professional looks at a finished thing and sees its parts: what each part does, which knobs move it, how it fails, and which patterns repeat across the subject. This skill tears a subject down into that view for a newcomer and renders it as an exploded view. The reader starts at the finished product, splits it apart, and opens any part as far down as they want: turtles all the way down. Search answers a question the reader can already ask; a teardown is for browsing, to find the questions they could not.

Organise by **deep structure**: the parts, knobs and loops that every instance of the subject shares. Put **surface features** (style, genre, vessel, device) in catalogues the reader can swap, so a swap shows what changes and what stays. A growth engine is a growth engine in any genre. Time and temperature shape every loaf, from sandwich bread to sourdough.

The teardown is the subject's, not the user's. Write in no name, number or formula from the user's own project, even when you know it: the reader of a shared teardown has a different project. Browsing helps the reader discover questions. Holding the teardown against the user's own project is the work of the skills in [Use the map](#use-the-map).

## Steps

1. **Survey.** Before you design anything, aggregate what the subject's practitioners say to read and whom to follow. One search returns the same few popular pages, so triangulate. Collect 8 or more independent **lists**, with no more than a third from any one kind: named practitioners' recommended reading, course syllabi, a community's curated reading list, the bibliography of a standard text, awards, a conference's best-known talks. Independent means different authors: a list copied from another counts once. Courses and listicles favour introductions, so look for the "what to read next" lists experienced practitioners write for each other too. Tally every work the lists name. A work named by 3 or more lists is **canon**; so is a work 2 courses assign. Then survey each **specialism** on its own: practitioners' job titles and conference tracks name them. Each specialism has its own short canon that the subject-wide lists outvote, so a work 2 lists name for one specialism is canon too. Subject-wide lists rank popularity, so the book that defines a narrow topic, or a new one, rarely reaches them. So survey each **topic** the same way: a topic is a part practitioners name, in the subject's own words (for bread: "dough fermentation", not a chapter title). Take topics from the canon's tables of contents now, and from the tree's parts after step 4. Search each topic's term with "book" and with "best books", and tally the topic's own lists: its reading lists, its courses, its practitioners' recommendations, the bibliographies of its books. A work 2 topic lists name is canon for that topic, even if it is too new for older books to cite. Then find the **voices**: practitioners with shipped, recognised work who teach in public. Search each channel on its own (conference talks and postmortems, blogs and newsletters, video channels, podcasts, social threads), because each has its own stars. Record what each voice made and where they post. Write the lists and voices to `survey.md`, and each canon work to `works/` with its `canon` entry ([SCHEMA.md](SCHEMA.md)); a topic's canon uses `specialism` for the topic's name. Done when the tally covers 8 or more lists from 3 or more kinds, every specialism and every topic in the canon's contents has been searched, every canon work names its lists and has an `isbn` if it is a book in print, and the voices span 3 or more channels.
2. **Root.** Start where people meet the product: a loaf on the table, a game on a phone, a scene on a cinema screen. Pick a typical instance. Make the surface it arrives on a catalogue (vessel, device), and the instance too if it varies (style, genre, scene). Done when the root has a look and at least one catalogue.
3. **Explode.** Split the root into 5–10 parts a practitioner names first: what it is made of, then what makes it. For each part write the practitioner term, the newcomer's words, what it does for the whole, and the question a practitioner asks about it. Each specialism from the survey works on some part of the whole, so give each one a part or a branch. Done when no part is a surface feature in disguise and every specialism has a home.
4. **Go down.** Under each part add what controls it: the knobs you set, the measures you read, the process that makes it, and how it goes wrong. Stop where a practitioner acts directly: a setting, a reading, a named rule. Then run the topic survey from step 1 for each part, so each part has its own canon before you cite it. Done when every branch ends in something you can set, measure or look up, and every part's topic has been surveyed. A first pass is 40–80 nodes.
5. **Loops and patterns.** Find the feedback loops: reinforcing (growth, snowball) and balancing (brake, thermostat). Find the cycles too: a sequence that repeats without growing by itself (a play loop, a turn, a bake day). Make each a `loop` node with its chain of parts. When a structure repeats across the subject or across subjects (an engine with a brake, an ecology of parts that limit each other), make one `pattern` node and point every instance at it. Done when every loop names its type and chain.
6. **Catalogues.** Wherever practitioners choose between interchangeable options (vessels, formulas, curves, styles, off-flavours), make a catalogue. If the options are numbers, add a `plot` so the reader compares them on one chart. Give an item a `why` when a newcomer could mistake what makes an instance this item: the feature every instance shares, and the surface trait (setting, platform, brand, subject) that is not the reason. Done when every "which one?" choice is a catalogue, not a sentence.
7. **Flatpack.** Write the assembly order: which parts join into which larger system, step by step, until the product. Use the order practitioners work in. Done when the last step makes the root.
8. **Visuals.** Things you can see get a `look` the reader can name with its label covered: a substance is a sample of it (a droplet, a small glass), a property is samples that differ (swatches pale to dark), a process is its equipment, a knob is the tool you set it with (a thermometer at dough temperature), a measure is the instrument you read it on, a device has the details that tell it apart (a stand, buttons, rounded corners). A child's `at` point is a real feature of its parent's look, where that child lives: the screen, the controls, the bar in the HUD. Never add parts only to mark an `at` point. Ideas you cannot see get a `feel`: a bouba/kiki body whose roundness, motion, weight, warmth and grain carry the idea's character, plus one line on why. Things a reader can see or hear on a real instance (the product, a part on the screen or the page, a process you can watch, a reading on an instrument) also get `cues`: 2–4 signs to look for that show the node is there and how it is set, so the reader can find it in the next game, book or robot they meet. Done when every node has a look, feel, loop or plot, no thing you can see is a bare ball or a felt body, and every node a reader can see or hear has its cues.
9. **Sources.** Cite a page you opened for every node: the canon first, then the voices, makers' documents, standards. Prefer book pages and named people. Each work gets one file in `works/`, with its label (author, title), kind, home page and a book's `isbn`, so the page's Sources view lists it once with a link to find a copy; a citation names its work and adds the chapter and pages in `page`. A book's work covers only the book's own text: a preview, a sample chapter, an excerpt, the publisher's page. An article, talk or course by the same author is a separate work with its own title and no `isbn`. Copy into `quote` the words on the page that support what the node says. If you cannot find such words, the page does not support the node: do not cite it there. A table of contents or a blurb names a topic and supports no claim. When the user gives you a book's text from their own copy, read the chapters that cover the map's nodes, cite them with `copy: true`, the printed page and the quote, and save the text as `raw/<work>.txt` (or `.md`, `.pdf`) so `verify` can check the quotes. Mark a node with no supporting page `unverified`; an honest gap is worth more than a padded citation. Sources also widen the map: when a source names a work the survey lacks, tally it; when it names a concept the tree lacks, add the concept ([Go wider](#go-wider)). Done when every node has quoted sources or an `unverified` note.
10. **Build, check and verify.** Write the teardown as a folder, `<slug>/`, to [SCHEMA.md](SCHEMA.md), next to the user's work or in their teardowns repository. If a script writes the teardown, it may write the compiled `teardown.json` instead: keep the script in `<slug>-gen/` beside the JSON, with paths relative to the script; the script is then the source for every later change. `node <skill>/kit/split.mjs teardown.json <slug>` turns a JSON into a folder when the script's work is done. Then run, with `<skill>` as the folder that holds this file and `<slug>` as the folder or JSON:
   ```sh
   node <skill>/kit/build.mjs <slug>
   node <skill>/kit/verify.mjs <slug>
   node <skill>/kit/check.mjs <slug>.html
   ```
`build` lists file and schema errors, books without an `isbn`, and canon no node cites. `check` opens the page in headless Chrome, clicks through root, explode, focus, catalogue, sources, search and flatpack, and saves screenshots. That tour opens only a few subtrees, so run `check` again with `--open id,id,...` listing every node that has children. Read every screenshot. `verify` opens every cited page and reports pages that are gone, quotes not on their page or in the user's copy, quotes too short to show support, citations with no quote, pages that never name their node, and book labels on pages that are not the book; it reads PDFs once you run `npm ci` in `<skill>/kit/src`. In a folder it keeps each page's text in `raw/web/`, so the next run checks the same text; `--fresh` fetches again. A script cannot tell whether a quote supports its node, so hand the verify report and the teardown to a reader who did not write the citations: a subagent, told to open each page, keep each citation only where its quote supports what the node says, and remove or replace the rest. Whoever writes a citation wants the node covered; the reader only wants the page to say it. Last, add an entry to `log.md`: what changed, what the reader dropped, what is still open. Done when `build` and `verify` report no errors, each screenshot shows the part it names, the reader has checked every citation, and the log says what is open.

## Read a teardown

A teardown is mostly drawings and citations: about 90,000 tokens for 80 nodes. To discuss a teardown or change it, start from the map, not the files:

```sh
node <skill>/kit/map.mjs <slug>                 # outline: every node on one line, as a tree, then the flatpack steps
node <skill>/kit/map.mjs <slug> <id> [<id>]     # nodes in full, without drawings, with the files that hold them
node <skill>/kit/map.mjs <slug> --find <words>  # every node and catalogue item holding all the words
```

Then edit the files the map names: `nodes/<id>.md` for a node's words, tree and sources, `looks/<id>.json` for its drawings, `works/<id>.md` for a work's label or canon entry. Each node is its own file, so agents working on different nodes do not overwrite each other. For a JSON teardown, `--json <id>` prints a node's raw JSON, drawings included. A published teardown's URL (`https://teardownatlas.com/chess/`) also works as `<slug>`, to read only. The page's Index runs the same search: press `/` and type.

## Use the map

This skill makes the map. Three skills use it on the user's own project, and take the map as an index of terms and source leads, never as a verdict:

| Question | Skill | Ends in |
|---|---|---|
| "Is this on the map? What is it called?" A goal or symptom in the user's words. | [teardown-lookup](../teardown-lookup/SKILL.md) | the subject's name for it, the established approaches, one decision and a test |
| "How does this part apply to my project?" A node or branch the reader picked. | [teardown-apply](../teardown-apply/SKILL.md) | the part held against the project: what is there, what is missing, what to change |
| "How does my whole project measure up?" | [teardown-audit](../teardown-audit/SKILL.md) | a diagnosis, a guiding policy and coherent actions |

Every node's panel has a Copy button under "Use it on your project" that gives the request: `teardown-apply: hold "<term>" (<id>) from the teardown at <slug> against my project`, or `teardown-audit: …` on the root. `<slug>` is the path on a local page and the URL on a public one.

A use that searches past the teardown grows it. Each use records its **misses**: the user's words that found no node, and teardown-level concepts its outward search found that the teardown lacks. After answering the user, in the same session, write each miss back:

- The user's words for a concept the map has become `aka` on that node.
- A missing concept becomes a node, a branch or a catalogue item where it belongs, to the same standard as any [Go wider](#go-wider) addition, with one exception: its topic survey (step 4) can wait. Cite the pages the search already opened, with their quotes, and add a line to `log.md` naming the concept and the survey still to run. When a statement in the map is now too narrow (a definition that leaves the new concept out), widen it.
- A concept outside the subject is noted in `log.md` with the subject it belongs to.

Write the teardown's view only: no name, number or detail from the user's project. Then run `build` and `verify`. When the teardown is only a published page, list the misses for its author.

## Go deeper

When the reader asks to open or expand a part ("go deeper on oven spring", "expand oven spring"), run steps 3–10 on that node inside the same teardown: in its folder, or in `<slug>-gen/` when a script writes the teardown. Keep every existing `id`. The `deeper` field on a leaf says what the next level would hold. The Copy button on a leaf gives the request as `teardown: go deeper on "<term>" (<id>) in <path to the teardown>`.

## Go wider

A teardown is never finished. When a source, a canon chapter or the reader names a concept the tree lacks, add it where it belongs: a new part, a new branch, a catalogue item. When a work turns up that the survey lacks, tally it, and if it reaches canon, read it for concepts too. `build` lists canon works that no node cites: each is either a branch the tree is missing or a work outside the subject, so add the branch or say why in the work's `canon.why`. Then run steps 3–10 on the new nodes. A request like "go wider on level design" means this.

## Share

Every node has its own link. Served from a folder URL, a node is `<folder><id>`. Opened as a file, or by a URL that ends in `.html`, a node is `#<id>`.

For the web, build a folder: `node <skill>/kit/build.mjs --public=<folder URL> <slug> <out-dir>`, then `node <skill>/kit/cover.mjs <out-dir>`. The folder has one page per node (`index.html` for the root, `<id>.html` for the rest), each with its own title, description, canonical link, link preview and the node's text for readers and search engines without script; the viewer loads over it from the shared `viewer.js` and `teardown.json`. `cover.mjs` serves the folder locally, splits the root apart in headless Chrome and saves `cover.jpg` (1200 × 630), the picture link previews show, and fails on any page error. The pages leave out the path of your teardown: their Copy prompts name the teardown by its URL, and Go deeper links to this skill. The server must answer `<folder><id>` with `<id>.html` and any other path in the folder with `index.html`, and redirect the folder without its final `/` to the folder with it. Caddy: `@page { path_regexp ^/[a-z0-9-]+/[a-z0-9-]+$` and `file {path}.html }`, then `rewrite @page {path}.html`.

Every page, local or public, ends each panel with a note that an AI agent wrote the map. Add `--legal=<URL of the site's legal page>` to the public build to link that note to the page where the site says who publishes it and how to report a problem. Add `--home=<URL of the site's home page>` to put a mark at the top left of every page that leads back to it.

To offer a finished teardown to [Teardown Atlas](https://teardownatlas.com), run [teardown-upload](../teardown-upload/SKILL.md): it opens a pull request on the public [teardowns](https://github.com/iqrow/teardowns) repository for review.

## Examples

Published teardowns are on [Teardown Atlas](https://teardownatlas.com): fiction writing starts from a novel, robotics from a mobile robot, content creation from a video post. Open one to see the target, and its Sources view to see the citation standard.