map-project

Produce a document another model can rebuild the system's logic and functionality from, holding nothing but that document. Every line is an observation about the code, cited to a file, function/struct, and variable.

That standard sets the detail level everywhere. A responsibility in one line describes; a signature with its error cases, an invariant, and the ordering rule inside a loop reconstructs. When a passage would leave a reimplementer guessing, it is not done.

Scope

Read-only, with one exception: the approved copy to docs/technical-spec.md in §3. Subagents may read, grep, and run the existing test suite. Nothing else edits, stages, or commits. Load the code-standards skill for enhanced understanding of enforced structure and procedures. Be extremely thorough and comprehensive; this doc will become the foundation for upcoming analysis and implementation.

1. Scout, before dispatching anything

Do this inline. It is cheap and the fan-out shape depends on it.

• Read the root: manifest (Cargo.toml, package.json, pyproject.toml), the test config, and the entry points it names.
• List the real subsystems. Group by concern, not by file type, and follow the repo's own layout rather than imposing one.
• Get the commit (git rev-parse --short HEAD) and whether the tree is dirty. The map is only true for one commit, and it says which.

A repo with no manifest and no tests still maps. Say so in Unknowns and work from the entry points.

2. Fan out

One agent per subsystem, plus the three fixed roles below, all dispatched in a single message so they run concurrently. Every dispatch passes an explicit model. Read these at minimum: README.md, the Notes document at $VAULT/projects/<Name>.md, every file in src/, docs/, tests/, and appropriate files in output/. That is the bar; read more files or git history outside that if necessary.

More than 8 subsystems means grouping the smallest ones together rather than raising the cap.

Each subagent gets: the repo path, its scope, the return shape, and a reminder that its final text is the return value rather than a message to a human. Tell it to cite specific files and symbols, and to report what it could not determine instead of filling the gap.

3. Synthesize

You write code-map.md in the session scratchpad, not a subagent. Dedupe overlapping findings, resolve contradictions between two readers by opening the file yourself, and investigate anything no agent could evidence (drop if inaccurate or useless). An evidenced finding that fits no heading gets its own heading; fit is never the reason something gets cut.

When finished, report the path. On a standalone invocation, use AskUserQuestion to ask whether to overwrite docs/technical-spec.md with its content. When resolve-project invoked this skill, stop at the path and skip that question: it writes the spec itself in §2.1, after its resolutions are approved, and asking here would land the write before the audit is read.

Output

Sections are numbered throughout, so an agent can cite §7 and a human can jump.

# {project}: technical specification

`{commit}` · {clean|dirty} · {date}

## 1. What the system is
What it does and the mechanism it uses, in 3-6 sentences.

## 2. Design invariants
What holds everywhere, stated so a violation is recognizable. The rules a reimplementation is wrong without.

## 3. Vocabularies
Closed sets with exact counts: states, event kinds, error variants, commands. Name every member.

## 4. Data model
Every type that persists or crosses a boundary: fields, types, units, defaults, and what makes an instance invalid. Include on-disk formats, schemas, and serialization.

## 5. Build and run
Toolchain, dependencies with versions and what each is for, build and run commands, entry points, environment variables.

## 6 to N. {one section per subsystem, named for the domain}
Per subsystem, in this order: its contracts (signature, what it promises, error and edge cases, invariants), the non-obvious logic in enough detail to reimplement (ordering rules, tie-breaks, state transitions, numeric methods, concurrency and locking), and what it exposes to a consumer byte for byte (CLI flags, wire messages, event shapes, file paths, exit codes). Pseudocode wherever prose would be ambiguous.

## N+1. Data flow
Entry point to output, naming the real stages, the IO boundaries crossed, and the state persisted. Draw the graph when execution branches or fans out.

## N+2. Module map
| Path | Owns | Public surface | Depends on |

## N+3. Configuration
| Key | Type | Default | Effect |

## N+4. Test evidence
The suite as conformance criteria: what each suite proves, the command, and the real output from this run. A rebuild is correct when these pass.

## N+5. Defects
| Symptom | File:line | Trigger |
Where the code does something other than what it intends. Rebuild the intent, not the defect.

## N+6. Dead surface
Unreachable code, unused exports, config nothing reads. A rebuild leaves these out.

## N+7. Limits
The honest ceiling: what the system cannot do, where it degrades, and what extending it would take.

## N+8. Unknowns
What no agent could determine, and what would settle it. Every entry is a hole in the reconstruction.

Subsystem sections carry the weight, one per concern from the scout, named for the domain rather than the file path. A spec that stops at the module map has skipped what a maintainer needs most.

Defects, Dead surface, and Unknowns are fixed, by name: they hold what a reader would otherwise never learn, and resolve-project reads Defects by heading. Everything above them is a starting shape. Add a section for what this repo has that the list does not cover (a wire protocol, a plugin system, a build that generates code), add a column to a table or drop the table when prose carries it better, and scale the whole document to the size of the repo. Mine run 13k to 70k characters; under 10k is a README wearing a spec's title.

Rules

• Write for a reimplementer. The test for any passage: could a model holding only this document produce code that behaves the same? Detail scales with how much a reader would otherwise have to guess.
• Cite or drop it. Every claim names a file, a symbol, or a line. An unattributed claim gets cut. Broad analysis can cite a specific, grounded chain of reasoning based in files or real-world facts.
• Report the tests you ran. Paste the real output. A suite that fails is a result about the repo, not a reason to stop mapping.
• Report what you could not determine. A stated unknown beats a confident guess, and Unknowns is where it goes.