From thinking-skills
Verifies code behavior against docs, tests, diagrams, and assumptions by examining actual code and data. Confirms or refutes map-territory mismatches before theorizing.
How this skill is triggered — by the user, by Claude, or both
Slash command
/thinking-skills:thinking-map-territoryThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
"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.
"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.
Decision flow:
Behavior ≠ what the doc/test/diagram/assumption says?
→ Yes → GO VERIFY THE REAL CODE/DATA, then theorize
→ No → Fine, but confirm before high-stakes action
Building a theory on a description rather than the thing itself?
→ Yes → CHECK THE TERRITORY FIRST
When something is surprising, explicitly identify the representation the surprise is measured against:
Surprise: "This function should return the user, but the page is blank."
The map: the function name + a comment saying it returns the user
The territory: what the function body actually does on this input
Be specific about which map you were trusting — the doc, the test name, the variable name, the comment, the architectural diagram, or your own assumption.
Don't reason about what the code probably does. Execute these verification actions:
git log, the deploy, the config changeOnly theorize AFTER you've looked at the territory.
If the code does X and the doc says Y, the code is what ships and what breaks. Update your theory to match the territory — never the reverse.
Map: "The cache makes reads fast"
Territory (measured): 30% hit rate; most reads hit the DB
Conclusion: the mental model was wrong — fix the model, then the caching
Once verified, name the aspects no available map shows — that's where the next bug hides:
Have: the happy-path code, the passing tests
Don't have a map of: the error/timeout paths, contention behavior, the null case
Action: look at those before declaring it correct
Don't re-verify something you already confirmed this session. Trust the verification you just did and move on.
A completed Map-Territory verification produces:
| Anti-Pattern | Symptom | Correction |
|---|---|---|
| Theorizing before verifying | Reasoning about what code probably does without looking | Go to the territory first — read/run/query/reproduce |
| Trusting the map over the territory | "The doc says X, so the code must be wrong" when the code is what ships | The territory wins; update the map |
| Re-verifying known territory | Checking the same code path repeatedly in one session | Trust what you just verified; note it and move on |
| Map-territory on artifacts being edited | Spiral into verification when the doc/diagram IS the thing you're changing | The edited artifact IS the territory for that task |
| Over-applying to authoritative maps | Second-guessing generated types or code-derived schemas | Authoritative/generated maps ARE the territory |
| Verifying irrelevant mismatches | Noting a doc-code gap that can't affect the decision | If it doesn't change your action, note it and move on |
npx claudepluginhub tjboudreaux/cc-thinking-skills --plugin thinking-skillsDiagnoses failures, fixes bugs, and investigates failing tests using systematic debugging: reproduce first, read before changing, assume nothing, find root cause.
Enforces systematic root cause analysis for bugs, test failures, unexpected behavior, and regressions via five-phase workflow: Understand, Reproduce, Isolate, Fix, Verify.
Investigates unfamiliar codebases or problems using the Coordinate Remote Viewing protocol: clearing assumptions before gathering staged observations and managing premature conclusions.