Map-Territory Thinking

Overview

"The map is not the territory." Every representation — doc, test, diagram, comment, mental model — is a simplified view of reality. When behavior contradicts the description, the fastest path to resolution is to stop reasoning from the map and go verify the territory directly: read the actual code path, run it with instrumentation, query the real data, reproduce the behavior.

A bug is a map–territory mismatch. The README says X, the function name implies Y, the comment claims Z — but the code does something else. The skill is scoped to this specific agent-relevant domain: docs/tests/mental-model vs runtime/code reality. It is NOT a general philosophical framework.

Core Principle: The running code and actual data are the territory. The README, the test, the diagram, the comment, and your assumption are all maps. When the two disagree, the territory wins — go look at it before building a theory on top of the map.

When to Use

• Debugging: behavior contradicts the docs, a test's expectation, a comment, a diagram, or "it should work" — go read/trace the real code path
• A claim about the system comes from a doc, a comment, or recall rather than from the current code or data
• Tests pass but the behavior is wrong (the test is a map of expected behavior, not all behavior)
• You're about to theorize about why something happens instead of looking at what happens

Decision flow: