System map — audit a body of work so later agents can edit it

The sixth form. Read this when the repeating unit is a folder someone will change: a repo, a markdown vault, or a mix. The deliverable is not a run and not a company chart. It is a walkable graph: what the nouns are, how they move, and what else moves if you touch one.

Do not restate the ten invariants or the other five forms. Those live in SKILL.md and forms.md.

When to use it

The user wants to work on a tree they do not hold in their head: “map this repo,” “audit this folder,” “what would a change hit,” “make this editable for the next agent.” The tree may be code, markdown, or both.

Do not use this form when they want a repeating production line (Pipeline), a company/team graph (Context map), or a model of how someone thinks (Knowledge bundle).

If the tree is small enough that one CONTEXT.md plus an index answers “what is X” and “what else moves,” stop there. Do not scaffold objects/ / processes/ / effects/ for a dozen files.

What the map is

A record library of nouns plus a short shelf of verbs, plus a change-impact index. The subject tree stays the source of truth. The map cites it. The map never becomes a second spec.

Universe	Meaning
live	In force. Implement and cite against these.
leftover	Still present, no longer the main path. Touch only if that path is in scope.
ghost	Named or filed, not wired (stubs, dead types, docs of functions that do not exist). Do not implement against these.

Product language and file/type names often disagree. State both once in the catalog (“Chat = Incubator”).

Where it lives

Propose before writing. Prefer a map/ shelf next to existing orientation (developer-docs/, docs/, vault root) so the subject’s entry file can add one routing row. Do not drop a map inside src/ or scatter cards through the tree you are mapping.

Entry files: edit CLAUDE.md. Generate AGENTS.md and routing.md as byte-identical twins in the same folder. Never hand-edit the twins. Tools that ignore CLAUDE.md still get the catalog.

Target tree (smallest that carries the work)

map/
├─ CLAUDE.md              L0 catalog (twins: AGENTS.md, routing.md)
├─ CONTEXT.md             how to walk; the universes; name collisions
├─ _meta/schema.md        closed node types
├─ _templates/            object.md, process.md
├─ objects/
│  ├─ CONTEXT.md
│  ├─ _index.md           one line per noun (stub | verified | stale)
│  └─ <cluster>/          cards
├─ processes/             only after nouns exist; only real movements
└─ effects/CONTEXT.md     which cards to open before a change

Do not create processes/ or effects/ empty. Three verified noun clusters beat seven imagined shelves.

Audit pipeline (human-gated slices)

Stop after each slice. A person or a cold walk reads the output before the next slice starts.

0 — Inventory, do not write cards

List the tree. Classify each area: catalog / contract / factory / product / dead (Restructure mode). Infer nouns (types, durable files, note kinds) and verbs (movements that repeat). Mark universe. Present the proposed tree and cluster list. Get approval.

1 — Catalog

Write CLAUDE.md, CONTEXT.md, schema, templates, objects/_index.md with stub lines for every noun you will not invent a body for. Wire one routing row from the subject’s existing entry file. Walk: “where do I go to understand X?” lands in two hops.

2 — Nouns (objects)

One card per type, copied from _templates/object.md. Cluster by how an editor asks, not by folder layout.

Source of truth

• Code: the type / table / module. Cite path:line. If a comment and the code disagree, the code wins and the card says so.
• Markdown / mixed: the file that owns the fact. Cite path. If two notes disagree, pick one home and link.

status: verified only with a date, a branch or commit (or vault revision), and citations. stale is allowed. A confident wrong date is not.

Fill If you change this as Hits / Does not hit. First-order only. “Does not hit” names the obvious next noun that is the wrong one.

Re-verify load-bearing claims against source before calling the slice done. Do not paste an audit report into a card.

3 — Verbs (processes)

Only movements that actually run or are actually followed. Typical code set: auth, publish/push, hydrate/load, run/turn, promote/export. Typical vault set: ingest, revise, publish. Do not invent a sixth.

Each process card: Input → Movement → Output; numbered steps with citations; consumes / produces as links to object cards; Hits / Does not hit.

4 — Change-impact index

effects/CONTEXT.md is a catalog: “if you are changing X, open these cards.” It does not copy waterfalls. If the index and a card disagree, fix the card.

5 — Re-verify

After the first fill, rip the load-bearing claims again (especially Hits / Does not hit). Wrong waterfalls are more expensive than missing cards.

Object card (required sections)

1. One sentence — product name and code/file name if they differ
2. Why this shape — the load-bearing why, not a field tour
3. Shape — keys, constraints, or owning files, with citations
4. Connected to — owns / owned-by / joins / looks-like-but-is-not
5. If you change this — Hits / Does not hit
6. Surfaces — who reads/writes (apps, agents, humans, none)
7. See — the source file; at most one as-built page

Walk test (this form)

A cold agent, no memory of the subject:

1. Open the subject’s entry file. Is the map one hop away?
2. Open map/CLAUDE.md. Can it say what the colliding names mean without opening a card?
3. Open one object card. Does it cite source, state the why, and give a first-order waterfall?
4. From effects/CONTEXT.md, can it name what a stated change hits and what it does not?
5. Follow one See link. Does it land on source, not another essay?
6. Token check: entry + hub + one card stays in the 2k–8k band.

If a step fails, split or move files. Do not add a “how to read this map” novel.

Failure modes

• Mapping FeatureRequests / aspiration as live. Ghost it.
• Copying as-built behaviour into cards. Point at the file that owns it.
• Empty process/effects folders.
• Two hand-edited entry files (CLAUDE.md and AGENTS.md that drift).
• Cards with no citations marked verified.
• Slurping the whole objects/ folder in a later session — the catalog exists so you do not.