thinking-map-territory

Map Territory

Docs, tests, diagrams, metrics, comments, and mental models are maps. Running code and actual data are the territory. When they disagree, verify territory and update the model — never force reality to match the description.

When to Use

• Observed behavior contradicts a doc, test expectation, diagram, comment, dashboard, or prior assumption.
• A claim about the system rests on a secondary source rather than current code or data.
• Tests pass but production or manual behavior is wrong.
• You are about to theorize why something happens before inspecting what happens.
• A decision depends on whether a model, schema, or metric is still current.

When NOT to Use

• The map is the artifact you are asked to edit (doc, diagram, spec) — that artifact is the task territory.
• Same path already verified this session — reuse that observation.
• Map is authoritative and generative (codegen types, derived schema) with no claimed drift.
• The mismatch cannot change the decision — note and move on.
• Competing causal hypotheses after territory is confirmed — switch to scientific-method.
• Security exploit construction — use red-team; this skill only settles model-versus-observation.

Procedure

1. Name the map. State the exact representation trusted: which doc, test, metric, diagram, comment, or assumption. Quote the claim, not a paraphrase.
2. Name the territory check. Specify the observation that would prove or disprove the claim: code path, runtime value, query, reproduction, recent change, or live metric.
3. Verify source and freshness. Confirm origin of the map (author, generator, last update) and whether it could be stale relative to deploy, config, or data change. Prefer primary current sources over summaries.
4. Observe the territory. Read the real code path, run or instrument it, query real data, or reproduce the behavior. Do not predict from signatures or names alone.
5. Record the delta and update. If territory contradicts the map, territory wins for shipped behavior. Document the gap, revise the model, then decide the fix (code, map, or both). Note unmapped paths — likely next failure sites.
6. Stop when settled. Once the claim is confirmed or overturned with a concrete observation, stop re-checking the same path.

Output

Map: <claim + source + freshness>
Territory check: <what was inspected/run/queried>
Observation: <concrete result, not interpretation>
Delta: <aligned | map wrong | territory incomplete>
Updated model: <corrected understanding>
Action: <fix code | update map | no decision impact>
Uncovered: <paths no map covers>

Verification

• Falsify if you reasoned from the map without a territory observation, trusted a stale secondary source, or forced code to match a wrong doc without checking either.
• Stop when the contradiction is resolved or irrelevant to the decision.
• Over-application guard: do not re-verify the whole system when editing the map, when the map is the generative source of truth, or when the gap cannot change the next action.