map-then-territory · diff
git:20260716.3be8260 to git:20260717.43fbdbb
89 added, 50 removed. Audit A to A.
---
name: map-then-territory
- description: Draw and maintain a directed route map — waypoints as human-verifiable states, edges carrying transition logic — from a known start to a desired destination, then drive agents through the territory edge by edge. Use when (1) the user knows the start and destination of an endeavor but cannot draw the path between them, or asks to create or revise a map bundle (maps/<slug>/ or a project's map/); (2) turning an approved map into per-edge launch prompts; (3) writing execution results, deviations, or verification verdicts back into a map.
+ description: Map scattered ideas into a human-approved DAG of verifiable states, then drive fresh agents through it edge by edge. Use when the user has a destination or idea fragments but lacks the domain knowledge to identify or sequence the route; when revising a map bundle; when compiling approved edges into launch prompts; or when recording execution evidence, deviations, and human verification.
---
# Map Then Territory
- The map is the human's representation of the work to be done; the territory is where the work actually happens. This skill serves the human who knows the start and the destination but — because the route crosses tech stacks they do not know — cannot draw the directed lines between them. Division of labor: **the human owns the points, the agent owns the lines**, and every line must end at a state the human can verify without understanding the implementation.
-
- ## Contract
-
- Scope:
- - Survey a territory and co-draw a route map: a DAG of verifiable-state waypoints joined by edges that carry transition logic.
- - Assemble each approved edge into a launch prompt a fresh session can run.
- - Keep the map alive during execution: write-backs, tiered deviations, dual verification, and trust calibration.
- - Grow the human's cognition along the way: pre-teach directional choices, post-teach executive ones on demand.
+ Turn human intent into a map before changing the territory. The human owns the
+ intent, values, directional choices, and final verification. The agent surveys
+ the unfamiliar domain, preserves the human's idea fragments, proposes the
+ missing points and lines, and executes approved lines. A point is ready only
+ when the human can verify it without understanding the implementation.
- Inputs:
- - The human's start, destination, and any waypoints they can already name.
- - The territory: the codebase, documents, or environment where the work must happen.
- - The existing map bundle when revising, prompting, or writing back.
+ ## Core model
- Outputs:
- - A map bundle at the territory root — `index.md` (Mermaid overview plus waypoint and edge ledgers), `tutorials/`, `prompts/` — per [references/map-schema.md](references/map-schema.md).
- - One provenance-annotated launch prompt per assembled edge.
- - Execution records: evidence, `agent_verdict`/`human_verdict` pairs, deviations, post-mortems, and a calibration ledger.
+ - **Idea fragment** — the human's original input, preserved verbatim until the
+ map records its disposition.
+ - **Waypoint** — a verifiable state of the world, phrased as what is true rather
+ than work to perform. A
+ **directional** waypoint can redraw the route and requires an informed human
+ choice before execution; an **executive** waypoint allows any implementation
+ that passes its human-runnable acceptance check.
+ - **Edge** — one clean agent session of action, with transition logic explaining
+ why it moves the territory from one waypoint to another.
+ - **Map** — the human-approved Markdown and Mermaid DAG; its `index.md` is the
+ single source of route state.
+ - **Territory** — the repository, documents, or environment changed by agents
+ traversing approved edges.
- Limitations:
- - Not for trivial or single-session tasks with an obvious path — do those directly.
- - A waypoint whose acceptance check the human cannot run is not thought through; split or rework it rather than weaken the check.
- - Requires the `grilling`, `human-cognition-cache`, and `writing-great-prompt` skills.
+ ## Branches
- ## Core Model
+ - **Mapping ideas or revising a route** → read
+ [references/map-schema.md](references/map-schema.md) before editing.
+ - **Compiling an edge prompt** → read
+ [references/edge-prompt-assembly.md](references/edge-prompt-assembly.md)
+ before assembling.
+ - **Traversing an edge or writing back its result** → read
+ [references/execution-loop.md](references/execution-loop.md) before changing
+ territory or route state.
- - **Waypoint** — a verifiable state of the world ("paper-wiki exists: the agent can store, retrieve, and classify papers; the human can read them"), never a task. Each carries an **acceptance check** the human can run without knowing the tech stack, and a type:
- - **directional** — choosing wrong redraws the map (architecture, irreversible moves, taste). Requires an informed human choice, pre-taught.
- - **executive** — any competent implementation that passes the check is fine. Agent-autonomous.
- - **Edge** — the action that moves the territory from one waypoint to another, carrying its **transition logic** (why this action reaches that state) and sized to one clean agent session.
- - **Map** — a Markdown + Mermaid DAG bundle, the single source of truth. Any rendered HTML view is generated and disposable.
+ For an existing bundle, enter at the requested branch and treat completed
+ earlier steps as repository evidence. Treat each branch as one session arc:
+ mapping ends with an approved map, compilation ends with ready prompts, and
+ traversal ends with one edge's write-back or one human verdict.
- ## Branches
+ ## Map
- - **Drawing or revising a map** → read [references/map-schema.md](references/map-schema.md) before editing.
- - **Assembling edge prompts** → read [references/edge-prompt-assembly.md](references/edge-prompt-assembly.md) first.
- - **Execution write-back and verification** → read [references/execution-loop.md](references/execution-loop.md) first.
+ ### 1. Capture intent and survey the territory
- Load only the reference the active branch reaches.
+ Establish the territory, known start, desired destination, and every idea
+ fragment the human supplies. Preserve each fragment verbatim in the idea ledger
+ before interpreting it. Treat the destination as provisional until the human
+ confirms that it describes success. Survey the relevant code, documents, and
+ prior art; answer from territory evidence before asking the human. Use
+ `grilling` one question at a time for intent, preferences, or directional
+ ambiguity that evidence cannot resolve.
- ## Steps
+ Complete when the draft map names the territory, start, and destination; every
+ supplied fragment has a stable ledger row; and the evidence needed to propose a
+ route is gathered or its absence is explicit.
- ### 1. Survey before drawing
+ ### 2. Draw and approve the route
- Elicit the start (what exists now), the destination (what must become true), and every waypoint the human can already name — record them verbatim before improving them. Then survey the territory: read the relevant code, documents, and prior art the route must cross. Complete when the start, destination, and known waypoints are written down and the territory evidence needed to propose a route has been gathered — without asking the human anything the territory can answer.
+ Convert the idea ledger and survey evidence into a trunk route. Propose the
+ missing waypoints as well as the edges between them, including both when the
+ human supplies only fragments. Give every ledger row a disposition to the
+ destination, one or more waypoint or edge IDs, or a human-approved out-of-scope
+ rationale.
- ### 2. Propose the trunk map
+ For each directional waypoint, present two or three contrasting options with
+ real trade-offs and a recommended default, then resolve them one at a time with
+ `grilling`. When the human lacks the concepts needed to choose, teach from
+ territory evidence in `tutorials/` via `human-cognition-cache` before asking.
- Propose one trunk map: the missing waypoints and directed edges, each edge with its transition logic. At every **directional** waypoint, present 2–3 contrasting options with real trade-offs — never silently pick one — and resolve them one at a time using `grilling`'s single-question format (question, why it matters, evidence, recommended default). Where the human cannot yet make an informed choice, write a tutorial into `tutorials/` (artifact-grounded teaching via `human-cognition-cache`) before asking them to choose. Escalate to multiple full candidate maps only when the survey shows the whole approach is contested, and declare why.
+ Complete when every idea has a final disposition; every waypoint has a state,
+ human-runnable acceptance check, type, and status; every edge has an action and
+ transition logic; every in-scope waypoint lies on a coherent route; the DAG
+ contains a complete start-to-destination trunk; and the human approves the
+ route. Record approval as bundle status `approved`, then end the mapping arc.
- Complete when every waypoint has a state description, an acceptance check the human confirmed they can run, a type, and a status; every edge has transition logic; and the human has approved the map — record that as bundle status `approved`.
+ ## Territory
- ### 3. Assemble edge prompts
+ ### 3. Compile ready edges
- For each edge on the approved map whose source waypoint is `verified` (or is the start), assemble a launch prompt with `writing-great-prompt`, annotating every section with the map field that produced it, per [references/edge-prompt-assembly.md](references/edge-prompt-assembly.md). Complete when each such edge has a prompt file under `prompts/` that a fresh session can execute without access to this conversation, and — after human review for edges into directional waypoints — is marked `ready`.
+ For the requested approved edge—or each currently reachable edge when the user
+ requests a batch—assemble a provenance-annotated prompt with
+ `writing-great-prompt` according to
+ [references/edge-prompt-assembly.md](references/edge-prompt-assembly.md).
- ### 4. Drive the territory, keep the map alive
+ Complete when every requested edge has a prompt under `prompts/` that a fresh
+ session can execute without the authoring conversation, and each prompt is
+ `ready` after any required human review. End the compilation arc before
+ territory execution.
- Run the loop of [references/execution-loop.md](references/execution-loop.md): launch `ready` edges into fresh sessions, collect write-backs and dual verdicts, and redraw when the territory contradicts a directional choice. Complete when the destination waypoint is `verified`, or the map has been consciously redrawn or set to `paused`/`abandoned` with its record — an abandoned map with no record is the only failure state.
+ ### 4. Traverse, verify, and learn
- ### 5. Grow the human
+ Run one edge through [references/execution-loop.md](references/execution-loop.md).
+ Let the executing agent self-verify and write evidence; reserve `verified` for
+ the human's acceptance run. Pre-teach directional choices and offer executive
+ explanation after delivery on demand; record delivered cognition growth through
+ `human-cognition-cache`.
- At verification time, offer the executive-tier tutorial on demand; record evidence-backed cognition growth through `human-cognition-cache`. Complete when every directional choice the human made has an evidence-backed cognition entry recorded via `human-cognition-cache`, and every executive tutorial offered at verification was either delivered into `tutorials/` or explicitly declined.
+ Complete the execution arc when the selected edge reaches `done` and its target
+ is `delivered`, or when it returns to `ready` with the blocker or deviation
+ recorded. Complete a human-verdict arc when the verdict, resulting statuses, and
+ calibration entry agree. Repeat through fresh sessions until the destination is
+ `verified` or the map is explicitly `paused` or `abandoned` with its record.
## Boundaries
- - Write map, tutorial, and prompt content in the human's working language; keep field names and statuses in English so tooling stays stable.
- - `verified` is a human-only transition; the agent never flips it.
- - Map history is cognition history: keep dead waypoints, deviations, and post-mortems in the map — they record what the human learned.
- - Before publishing a map bundle outside the repository, warn that tutorials and post-mortems expose the human's cognition state.
+ - Write map, tutorial, and prompt prose in the human's working language; keep
+ field names and statuses in English for stable tooling.
+ - Keep dead waypoints, deviations, and post-mortems: map history is cognition
+ history.
+ - Before publishing a bundle, warn that tutorials and post-mortems can expose
+ the human's cognition state.
- _Original, Pengqian Han. Inspired by Thariq Shihipar's "A Field Guide to Claude Fable 5: Finding Your Unknowns" (the map–territory framing)._
+ _Original, Pengqian Han. Inspired by Thariq Shihipar's "A Field Guide to Claude
+ Fable 5: Finding Your Unknowns" (the map–territory framing)._