{"kind":"Skill","metadata":{"namespace":"community","name":"thinking-map-territory","version":"0.1.0"},"spec":{"description":"Recognize limits of mental models and diagrams. Use when models diverge from reality, debugging expectation mismatches, or questioning abstraction accuracy.","files":{"SKILL.md":"---\nname: thinking-map-territory\ndescription: Recognize limits of mental models and diagrams. Use when models diverge from reality, debugging expectation mismatches, or questioning abstraction accuracy.\n---\n\n# Map-Territory Thinking\n\n## Overview\n\nMap-Territory thinking, originated by Alfred Korzybski and popularized in general semantics, reminds us that **\"the map is not the territory.\"** Every representation—mental model, diagram, metric, specification, or abstraction—is a simplified view that necessarily loses information. Confusing the map with the territory leads to flawed decisions, debugging dead-ends, and misaligned expectations.\n\n**Core Principle:** All models are wrong; some are useful. The question is: how wrong, and useful for what?\n\n## When to Use\n\n- Debugging when behavior doesn't match expectations\n- Evaluating whether documentation/specs match implementation\n- Questioning metrics that seem to tell the \"full story\"\n- Architecture decisions based on diagrams or models\n- When a \"perfect plan\" meets messy reality\n- Resolving disagreements where parties hold different mental models\n- Analyzing why estimates consistently miss reality\n\nDecision flow:\n\n```\nExpectation ≠ Reality? → yes → Are you trusting a model/abstraction? → yes → CHECK MAP-TERRITORY FIT\n                                                                    ↘ no → Model exists but isn't explicit\n                    ↘ no → Model may be accurate (verify anyway)\n```\n\n## Key Concepts\n\n### 1. Maps Are Abstractions\n\nEvery representation omits details:\n\n| Territory (Reality) | Map (Representation) | What's Lost |\n|---------------------|----------------------|-------------|\n| Running code | Architecture diagram | Timing, error paths, state |\n| User behavior | Analytics dashboard | Context, emotion, edge cases |\n| System performance | SLO metrics | Tail latencies, correlations |\n| Team dynamics | Org chart | Informal influence, trust |\n| Customer need | User story | Nuance, unstated assumptions |\n\n### 2. Multiple Maps, One Territory\n\nThe same reality can have many valid representations:\n\n```\nTerritory: E-commerce checkout flow\n\nMaps:\n├── Sequence diagram (shows interactions)\n├── State machine (shows transitions)\n├── User journey (shows experience)\n├── Data flow (shows information movement)\n├── Code (shows implementation)\n└── Metrics (shows performance)\n\nEach map reveals AND conceals different aspects\n```\n\n### 3. Map-Territory Confusion\n\nWhen we mistake the map for the territory:\n\n```\nConfusion: \"The tests pass, so the code works\"\nReality: Tests are a map of expected behavior, not the territory of all behavior\n\nConfusion: \"The architecture diagram shows this is simple\"\nReality: The diagram omits error handling, edge cases, and race conditions\n\nConfusion: \"Our metrics show users are happy\"\nReality: Metrics measure what we chose to measure, not satisfaction itself\n```\n\n### 4. Abstraction Leakage\n\nEven good abstractions eventually break:\n\n```\nAbstraction: \"The network is reliable\"\nLeak: Timeout, partition, packet loss\n\nAbstraction: \"Memory is infinite\"\nLeak: OOM, cache eviction, GC pause\n\nAbstraction: \"The database is ACID\"\nLeak: Connection pool exhaustion, replication lag\n```\n\n## The Map-Territory Alignment Process\n\n### Step 1: Identify Your Maps\n\nList all representations you're relying on:\n\n```\nDecision: Scaling the payment service\nMaps in use:\n- Architecture diagram (last updated 6 months ago)\n- Performance benchmarks (from staging, not prod)\n- Capacity planning spreadsheet (based on assumptions)\n- Team's mental model (from building v1)\n```\n\n### Step 2: Assess Map Freshness\n\nFor each map, determine:\n\n| Map | Last Updated | Created From | Drift Risk |\n|-----|--------------|--------------|------------|\n| Arch diagram | 6 months | Original design | High |\n| Benchmarks | 2 months | Staging env | Medium |\n| Capacity sheet | 1 month | Extrapolation | High |\n| Mental model | 2 years | Building v1 | Very High |\n\n### Step 3: Check Correspondence\n\nFor critical maps, verify against territory:\n\n```\nTest: Does the architecture diagram match the code?\nMethod: Trace a request through actual code, compare to diagram\n\nTest: Do benchmarks reflect production?\nMethod: Run production traffic sample through benchmark setup\n\nTest: Do metrics capture what matters?\nMethod: Interview users, compare their experience to metric story\n```\n\n### Step 4: Identify Missing Maps\n\nWhat aspects of the territory have no map?\n\n```\nExisting maps: Sequence diagrams, API specs, test coverage\nMissing maps:\n- Failure modes and recovery paths\n- Implicit dependencies\n- Performance under contention\n- Operational runbooks\n```\n\n### Step 5: Calibrate Confidence\n\nAdjust trust in maps based on verification:\n\n```\nMap: Test suite\nVerification: Tests pass, but manual testing found 3 bugs\nCalibration: Tests cover happy path, not edge cases\nAction: Add edge case tests, reduce confidence in \"green = good\"\n```\n\n## Map-Territory Mismatches by Domain\n\n### Documentation vs. Code\n\n```\nMap: README says \"run npm install\"\nTerritory: Requires Node 18+, specific npm version, env vars\nMismatch: Documentation abstracts away prerequisites\n\nVerification: Try setup from scratch on clean machine\nFix: Document actual requirements, automate verification\n```\n\n### Specs vs. Implementation\n\n```\nMap: Spec says \"API returns user object\"\nTerritory: Sometimes returns 404, sometimes 500, sometimes times out\nMismatch: Spec describes happy path only\n\nVerification: Test error cases, edge cases, failure modes\nFix: Spec error responses, add contract tests\n```\n\n### Metrics vs. Outcomes\n\n```\nMap: \"DAU increased 20%\"\nTerritory: Users signing up but churning within a week\nMismatch: DAU doesn't capture retention quality\n\nVerification: Add cohort retention, engagement depth metrics\nFix: Choose metrics closer to actual business outcomes\n```\n\n### Estimates vs. Reality\n\n```\nMap: \"This will take 2 weeks\"\nTerritory: Took 6 weeks due to unforeseen complexity\nMismatch: Estimate was based on mental model, not investigation\n\nVerification: Time-box investigation before estimating\nFix: Add uncertainty buffers, track estimate accuracy\n```\n\n### Mental Models vs. Systems\n\n```\nMap: \"The cache makes reads fast\"\nTerritory: Cache has 30% hit rate, most reads hit DB\nMismatch: Mental model assumed better cache performance\n\nVerification: Measure actual cache hit rates\nFix: Update mental model, improve caching strategy\n```\n\n## Map Quality Indicators\n\n### Signs of a Good Map\n\n- Explicitly states what it omits\n- Has a clear purpose and audience\n- Recently verified against territory\n- Includes uncertainty ranges\n- Acknowledged as a model, not truth\n\n### Signs of a Dangerous Map\n\n- Treated as complete truth\n- No update mechanism\n- Created by someone who never saw the territory\n- Optimistic without error cases\n- No validation feedback loop\n\n## Integration with Systems Thinking\n\nMap-Territory thinking complements systems thinking:\n\n```\nSystems Thinking asks: What are the feedback loops and emergent behaviors?\nMap-Territory asks: Is my systems diagram actually capturing those dynamics?\n\nCombined approach:\n1. Draw the system map (feedback loops, stocks, flows)\n2. Verify: Does measured behavior match predicted behavior?\n3. Iterate: Where does the map fail? What's the territory really doing?\n4. Update: Refine the map or accept its limitations\n```\n\n## Verification Checklist\n\n- [ ] Listed all maps/models being relied upon\n- [ ] Assessed freshness of each map\n- [ ] Identified highest-risk map-territory gaps\n- [ ] Verified at least one critical map against reality\n- [ ] Acknowledged what the maps don't capture\n- [ ] Calibrated confidence based on verification results\n- [ ] Documented map limitations for others\n\n## Key Questions\n\n- \"What representation am I trusting here?\"\n- \"When was this model last verified against reality?\"\n- \"What does this abstraction hide from me?\"\n- \"How would I know if this map is wrong?\"\n- \"What would I see if I looked at the territory directly?\"\n- \"Who created this map, and did they see the actual territory?\"\n- \"What happens in the territory that this map can't represent?\"\n\n## Korzybski's Reminders\n\n1. **The map is not the territory** — The word \"water\" won't quench thirst\n2. **The map doesn't cover all the territory** — No model is complete\n3. **The map is self-reflexive** — We can make maps of maps (meta-models)\n\n## Practical Mantras\n\n- \"All models are wrong, some are useful\" — George Box\n- \"The menu is not the meal\"\n- \"The org chart is not the organization\"\n- \"The test suite is not correctness\"\n- \"The metric is not the goal\"\n- \"The estimate is not the timeline\"\n\nWhen the map and territory diverge, update the map or change your navigation—but never insist the territory is wrong because your map says so.\n"},"import":{"commit_sha":"a31e22d4445ad8fef7cd771d32af537aebb68c49","imported_at":"2026-05-22T21:14:39Z","license_text":"MIT License\n\nCopyright (c) 2025 TJ Boudreaux\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","owner":"tjboudreaux","repo":"tjboudreaux/cc-thinking-skills","source_url":"https://github.com/tjboudreaux/cc-thinking-skills/tree/a31e22d4445ad8fef7cd771d32af537aebb68c49/skills/thinking-map-territory"}},"content_hash":[93,35,213,146,74,5,153,82,232,70,172,148,195,202,75,137,235,174,50,10,236,63,2,218,139,43,33,50,128,214,151,61],"trust_level":"unsigned","yanked":false}