{"kind":"Skill","metadata":{"namespace":"community","name":"thinking-occams-razor","version":"0.1.0"},"spec":{"description":"Apply parsimony principle to prefer simpler explanations with fewer assumptions. Use for hypothesis selection in debugging, architecture decisions, and choosing between competing approaches.","files":{"SKILL.md":"---\nname: thinking-occams-razor\ndescription: Apply parsimony principle to prefer simpler explanations with fewer assumptions. Use for hypothesis selection in debugging, architecture decisions, and choosing between competing approaches.\n---\n\n# Occam's Razor (Parsimony Principle)\n\n## Overview\n\nOccam's Razor, attributed to 14th-century philosopher William of Ockham, states: \"Entities should not be multiplied beyond necessity\" (entia non sunt multiplicanda praeter necessitatem). When multiple explanations fit the evidence equally well, prefer the simplest one—the one with the fewest assumptions.\n\n**Core Principle:** Among competing hypotheses that explain the data equally well, select the one with the fewest assumptions.\n\n**Einstein's Corollary:** \"Everything should be made as simple as possible, but no simpler.\"\n\n## When to Use\n\n- Debugging: Multiple hypotheses could explain a bug\n- Architecture: Choosing between design approaches\n- Root cause analysis: Several causes seem plausible\n- Code review: Evaluating implementation complexity\n- Technical decisions: Selecting between tools or patterns\n- Incident response: Narrowing down failure causes\n\nDecision flow:\n\n```\nMultiple explanations exist? → yes → Do they explain the evidence equally? → yes → APPLY OCCAM'S RAZOR\n                                                                          ↘ no → Prefer better explanation\n                           ↘ no → Use available explanation\n```\n\n## The Process\n\n### Step 1: Enumerate Competing Hypotheses\n\nList all plausible explanations for the observed behavior:\n\n```\nBug: Users intermittently can't log in\n\nHypotheses:\nA. Session token expiration edge case\nB. Race condition in auth service\nC. Database connection pool exhaustion\nD. Cosmic rays flipping bits in memory\nE. Complex interaction between CDN cache, load balancer, and session service\n```\n\n### Step 2: Count the Assumptions\n\nFor each hypothesis, list required assumptions:\n\n| Hypothesis | Assumptions Required |\n|------------|---------------------|\n| A. Token expiration | 1. Token validation has edge case |\n| B. Race condition | 1. Concurrent requests possible, 2. Shared mutable state exists |\n| C. DB pool exhaustion | 1. Pool is undersized, 2. Connections are leaking |\n| D. Cosmic rays | 1. Hardware failure, 2. No ECC memory, 3. Perfect timing |\n| E. Complex interaction | 1. CDN caches auth, 2. LB sticky sessions fail, 3. Session sync delayed |\n\n### Step 3: Verify Explanatory Power\n\nEnsure simpler hypotheses actually explain the evidence:\n\n```\nEvidence: Failures correlate with high traffic periods\n\nHypothesis A (token edge case): \n  - Doesn't explain traffic correlation ❌\n  \nHypothesis C (DB pool exhaustion):\n  - Explains traffic correlation ✓\n  - Fewer assumptions than E\n  - PREFERRED by Occam's Razor ✓\n```\n\n### Step 4: Test Simplest First\n\nInvestigate hypotheses in order of simplicity:\n\n```\n1. Check DB connection pool metrics (simplest)\n2. Review token validation code (simple)\n3. Analyze race condition potential (moderate)\n4. Instrument complex service interactions (complex)\n5. Check for hardware issues (last resort)\n```\n\n### Step 5: Escalate Complexity Only When Needed\n\nIf simple explanations are ruled out, move to complex ones with new evidence.\n\n## Complexity Assessment Framework\n\n### Counting Complexity\n\n| Factor | Complexity Cost |\n|--------|-----------------|\n| Each independent assumption | +1 |\n| Each component involved | +1 |\n| Each external dependency | +2 |\n| Timing-dependent behavior | +2 |\n| Requires rare conditions | +3 |\n| \"Perfect storm\" scenarios | +5 |\n\n### Example Comparison\n\n```\nSolution A: Add caching layer\n- New component (Redis): +1\n- Cache invalidation logic: +1  \n- New failure mode: +1\nTotal: 3\n\nSolution B: Optimize existing query\n- Query modification: +1\nTotal: 1\n\n→ Prefer Solution B unless evidence shows it's insufficient\n```\n\n## When Simplicity Yields to Complexity\n\nOccam's Razor is a heuristic, not an absolute law. Prefer complexity when:\n\n### 1. Evidence Demands It\n\n```\nSimple hypothesis: Single bug in auth service\nEvidence: Failures only occur when Feature X AND Feature Y are both enabled\n\n→ Complex interaction hypothesis now has supporting evidence\n→ Accept complexity that explains the evidence\n```\n\n### 2. Domain Complexity Is Irreducible\n\n```\nProblem: Distributed consensus\nSimple solution: Single leader (but single point of failure)\nReality: Distributed systems require complex solutions (Raft, Paxos)\n\n→ Some domains have irreducible complexity\n→ Don't oversimplify beyond what's correct\n```\n\n### 3. Future Requirements Are Known\n\n```\nCurrent need: Store user preferences\nSimple: JSON file\nFuture need: Multi-device sync, conflict resolution\n\n→ Database is more complex but necessary\n→ Known future needs justify upfront complexity\n```\n\n### 4. Simplicity Introduces Technical Debt\n\n```\nSimple now: Copy-paste code in 5 places\nSimpler long-term: Extract shared function\n\n→ Local simplicity vs. systemic simplicity\n→ Prefer systemic simplicity\n```\n\n## Application Examples\n\n### Debugging Example\n\n```\nBug: API returns 500 errors sporadically\n\nHypothesis A: Null pointer in rare code path\n  Assumptions: 1\n  \nHypothesis B: Memory pressure causes GC pauses that timeout requests\n  Assumptions: 3 (memory issues + GC behavior + timeout settings)\n  \nHypothesis C: Race condition between cache refresh and request handling\n  Assumptions: 4 (concurrent access + shared state + timing + cache implementation)\n\nOccam's Razor: Start with Hypothesis A\nAction: Search logs for null pointer exceptions\nResult: Found! NPE in user profile edge case\n```\n\n### Architecture Example\n\n```\nRequirement: Service needs to call another service\n\nOption A: Direct HTTP call\n  Components: 1 (HTTP client)\n  Assumptions: Target available, network reliable\n  \nOption B: Message queue with retry\n  Components: 3 (queue, producer, consumer)\n  Assumptions: Need async, need retry, need decoupling\n  \nOption C: Service mesh with circuit breaker, retry, timeout\n  Components: 5+ (sidecar, control plane, observability)\n  Assumptions: At scale, need observability, need traffic management\n\nOccam's Razor: Start with Option A\nEscalate to B/C only when evidence shows need for resilience\n```\n\n### Code Implementation Example\n\n```python\n# Complex (unnecessary assumptions)\ndef is_even(n):\n    binary = bin(n)\n    last_bit = binary[-1]\n    return last_bit == '0'\n\n# Simple (minimal assumptions)  \ndef is_even(n):\n    return n % 2 == 0\n\n# Occam's Razor: Prefer the modulo approach\n# Fewer concepts, fewer operations, same result\n```\n\n### Root Cause Analysis Example\n\n```\nSymptom: Deployment failed\n\nComplex hypothesis:\n\"The CI server's Docker daemon ran out of disk space because \na cron job that cleans old images was disabled when we upgraded \nthe server OS last month, and nobody noticed because the monitoring \nalert was routed to a deprecated Slack channel.\"\n\nSimple hypothesis:\n\"The build script has a typo in the new environment variable name.\"\n\nOccam's Razor: Check the build script first\nResult: Typo found. DATABSE_URL instead of DATABASE_URL\n```\n\n## Common Anti-Patterns\n\n| Anti-Pattern | Description | Correction |\n|--------------|-------------|------------|\n| Rube Goldberg | Complex solution to simple problem | Ask \"what's the minimum needed?\" |\n| Premature abstraction | Abstracting for hypothetical cases | Wait for evidence of need |\n| Resume-driven development | Using complex tech to learn it | Match tool to problem |\n| Cargo culting | Copying complex patterns blindly | Understand why patterns exist |\n| Conspiracy thinking | Assuming coordinated complex causes | Check simple causes first |\n\n## Verification Checklist\n\n- [ ] Listed all plausible hypotheses/solutions\n- [ ] Counted assumptions required for each\n- [ ] Verified simpler options have equal explanatory power\n- [ ] Investigated in order of simplicity\n- [ ] Escalated to complexity only with evidence\n- [ ] Confirmed solution is \"as simple as possible, but no simpler\"\n- [ ] Checked for domain-irreducible complexity\n- [ ] Considered systemic vs. local simplicity\n\n## Combining with Other Models\n\n- **First Principles**: Reduce to fundamentals, then apply Occam's to solutions\n- **Inversion**: \"What would make this unnecessarily complex?\"\n- **Debiasing**: Watch for complexity bias (assuming complex = sophisticated)\n- **Pre-Mortem**: Would a simpler approach have fewer failure modes?\n\n## Key Questions\n\n- \"What's the simplest explanation that fits all the evidence?\"\n- \"How many things have to be true for this hypothesis to hold?\"\n- \"Am I adding complexity to handle cases I haven't seen?\"\n- \"Would a junior engineer understand this solution?\"\n- \"If I explained this to a non-technical person, how many steps would it take?\"\n- \"What's the minimum change that could fix this?\"\n- \"Am I solving the problem I have, or a problem I might have?\"\n\n## Ockham's Warning\n\n\"Plurality must never be posited without necessity.\"\n\nThe simplest solution isn't always correct, but it should always be tested first. Complexity should be earned through evidence, not assumed through speculation. When you find yourself building elaborate explanations, step back and ask: \"What's the minimum hypothesis that explains what I'm seeing?\"\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-occams-razor"}},"content_hash":[152,73,136,90,151,46,54,81,244,17,75,26,245,136,244,245,215,130,89,165,3,246,170,249,172,244,73,215,159,102,190,213],"trust_level":"unsigned","yanked":false}