aio-mental-models

name	aio-mental-models
description	Decision and reasoning advisor — picks 2-3 relevant mental models, walks through applying each, and synthesizes a recommendation. Use proactively when facing a hard trade-off, an ambiguous decision, or any "should we do X or Y" question where structured reasoning beats gut feeling.
when_to_use	mental model, decision, trade-off, think through, evaluate options, structured reasoning, first principles, inversion, second-order thinking, opportunity cost, which model, problem-solving framework, help me decide, analyze options, problem solving, stuck on decision, which option, decision framework
argument-hint	Decision or problem to think through
effort	medium

Mental Models Decision Advisor

"The quality of our thinking is largely influenced by our mental models." — Shane Parrish

Workflow: How to Use This Skill

When this skill is triggered, follow these five steps. Do NOT just dump model descriptions — actively guide the user through their specific problem.

Step 1: ASK — Understand the Decision

Before selecting any models, ask the user (if not already clear):

• What specific decision or problem are you facing?
• What are the options you're considering?
• What constraints or context matter (timeline, resources, stakes, reversibility)?
• What have you already tried or considered?

If the user's message already contains enough context, proceed directly to Step 2.

Step 2: SELECT — Pick 2-3 Relevant Models

First, run semantic search with the user's problem as the query to find the most relevant models. Then cross-reference with the routing table below to ensure coverage.

npx tsx "$MM/search-models.ts" "<user's problem description>" --top 5 --json

Read the full markdown file for each top result before proceeding. Use the routing table as a secondary guide:

Context	Start With
Not understanding the real problem	First Principles, Map vs Territory, Circle of Competence
Making a big decision	Second-Order Thinking, Inversion, Probabilistic Thinking, Opportunity Cost
Evaluating options	Occam's Razor, Trade-offs, Margin of Safety
Dealing with people conflicts	Hanlon's Razor, Incentives, Cooperation
System not working as expected	Feedback Loops, Bottlenecks, Emergence
Starting something new	Activation Energy, Leverage, Critical Mass
Growth/Scaling challenges	Compounding, Diminishing Returns, Scaling
Risk assessment	Margin of Safety, Fat-tailed Curves, Redundancy
Change management	Inertia, Activation Energy, Equilibrium
Innovation/Disruption	Creative Destruction, First Principles, Niches

State which models you selected and why they fit this situation.

Step 3: APPLY — Walk Through Each Model

For each selected model, apply it directly to the user's situation:

• Name the model and its core principle (one sentence)
• Show what it reveals about the user's specific problem
• State the concrete insight or implication

Step 4: SYNTHESIZE — Combine Into a Recommendation

Merge the insights from all applied models into:

• A clear recommendation or ranked options
• Key factors that tipped the balance
• Conditions under which the recommendation changes

Step 5: CHALLENGE — Stress-Test With an Opposing Model

Pick one model that argues against the recommendation. Apply it honestly:

• What does this counter-model reveal?
• Does the recommendation survive the challenge, or does it need adjustment?
• State final confidence level and any caveats

---

Scripts

Before calling any script, resolve the scripts directory (version may vary):

MM="${CLAUDE_PLUGIN_ROOT}/skills/aio-mental-models/scripts"

$MM/list-models.sh                    # List all 54 models grouped by volume
$MM/list-models.sh --volume 1         # Filter by volume (1-4)
$MM/list-models.sh --search "thinking" # Search by keyword
$MM/list-models.sh --count            # Quick count

Semantic Search

Find relevant models by meaning, not just keywords. Uses pre-computed embeddings (snowflake-arctic-embed-xs, 384-dim, runs locally).

Search (dependencies auto-install on first run):

npx tsx "$MM/search-models.ts" "how to think about risk and uncertainty"
npx tsx "$MM/search-models.ts" "team dynamics and collaboration" --top 3
npx tsx "$MM/search-models.ts" "startup growth strategy" --json

Options:

• --top N — Number of results (default: 5)
• --json — Output as JSON for programmatic use

---

Important

Always run semantic search first before selecting models. The search uses embeddings to find the most relevant models for the user's specific problem — this is more reliable than guessing from the catalog or your training knowledge. After searching, read the full markdown file for each selected model.

---

Model Catalog

Volumes:

• Volume 1: General Thinking (First Principles, Inversion, etc.)
• Volume 2: Physics, Chemistry & Biology (Leverage, Catalysts, etc.)
• Volume 3: Systems & Mathematics (Feedback Loops, Compounding, etc.)
• Volume 4: Economics & Art (Incentives, Opportunity Cost, etc.)

Volume 1: General Thinking Concepts

Foundational models for clear reasoning and effective decision-making

Model	Core Idea	When to Use
The Map is Not the Territory	Models are simplifications, not reality	When assumptions don't match outcomes
Circle of Competence	Know your knowledge boundaries	Before making decisions outside expertise
First Principles Thinking	Break down to fundamental truths	When conventional solutions fail
Thought Experiment	Explore consequences without real cost	Testing ideas before implementation
Second-Order Thinking	Consider ripple effects	Major decisions with long-term impact
Probabilistic Thinking	Estimate likelihood of outcomes	Decisions under uncertainty
Inversion	Think backward to move forward	Stuck on a problem, avoiding failure
Occam's Razor	Simpler explanations are preferable	Choosing between competing theories
Hanlon's Razor	Assume incompetence before malice	Interpersonal conflicts

Supporting Ideas:

• Falsifiability - Theories must be testable
• Necessity vs Sufficiency - Required vs Enough
• Causation vs Correlation - Don't confuse coincidence with cause

---

Volume 2: Physics, Chemistry & Biology

Models from natural sciences for understanding change, energy, and adaptation

Physics

Model	Core Idea	When to Use
Relativity	Perspective matters	Understanding different viewpoints
Inertia	Objects resist change	Managing organizational change
Friction & Viscosity	Resistance slows movement	Identifying process blockers
Leverage	Small force, big impact	Finding high-impact opportunities
Activation Energy	Energy to start	Building habits, starting projects
Velocity	Speed + Direction	Progress tracking

Chemistry

Model	Core Idea	When to Use
Catalysts	Accelerators without being consumed	Finding force multipliers
Alloying	Combination > Parts	Team building, skill stacking

Biology

Model	Core Idea	When to Use
Natural Selection	Adapt or die	Competitive environments
Red Queen Effect	Run to stay still	Understanding continuous competition
Ecosystems	Complex relationships	Understanding markets, organizations
Niches	Find your unique position	Competitive positioning
Cooperation	Working together wins	Team dynamics

---

Volume 3: Systems & Mathematics

Models for understanding complex systems and mathematical patterns

Systems

Model	Core Idea	When to Use
Feedback Loops	Outputs become inputs	System dynamics, habit loops
Equilibrium	Balance points	Understanding stable states
Bottlenecks	Constraint limits the whole	Process optimization
Scaling	How things change with size	Growth planning
Margin of Safety	Buffer for the unexpected	Risk management
Churn	Healthy vs destructive change	Organizational change
Algorithms	Step-by-step procedures	Creating reliable processes
Critical Mass	Tipping point	Network effects, adoption
Emergence	Whole > Sum of parts	Complex system behavior
Gall's Law	Complex from simple	System design

Mathematics

Model	Core Idea	When to Use
Compounding	Exponential growth	Long-term thinking
Power Laws	80/20 distribution	Resource allocation
Diminishing Returns	More input, less output	Optimization decisions
Regression to Mean	Extremes normalize	Performance evaluation
Distributions	How data spreads	Understanding variability
Multiplying by Zero	One zero kills all	Identifying critical failures

---

Volume 4: Economics & Art

Models for understanding value, markets, and human expression

Economics

Model	Core Idea	When to Use
Scarcity	Limited resources, unlimited wants	Resource allocation
Supply & Demand	Price from interaction	Market dynamics
Opportunity Cost	True cost includes alternatives	Any decision
Trade-offs	Every choice has cost	Decision making
Incentives	People respond to incentives	Designing systems
Comparative Advantage	Specialize in relative strength	Team allocation
Creative Destruction	New destroys old	Innovation strategy
Monopoly & Competition	Market power dynamics	Competitive analysis

Art

Model	Core Idea	When to Use
Audience	Know who you're speaking to	Communication
Narrative	Stories shape perception	Persuasion, culture
Frame	Context shapes meaning	Presentation
Contrast	Difference creates emphasis	Design, communication
Chekhov's Gun	Every element must serve purpose	Editing, design

---

Quick Reference Card

The Top 10 Most Useful Models

1. First Principles - Break it down to fundamentals
2. Second-Order Thinking - Think ahead: "And then what?"
3. Inversion - Avoid failure instead of chasing success
4. Feedback Loops - Understand cause and effect cycles
5. Compounding - Small consistent actions win long-term
6. Margin of Safety - Always have a buffer
7. Opportunity Cost - Consider what you're giving up
8. Leverage - Find maximum impact points
9. Hanlon's Razor - Assume incompetence, not malice
10. Circle of Competence - Know your limits

Daily Checklist

Before any major decision, ask:

• Am I reasoning from first principles or by analogy?
• What are the second and third-order effects?
• What would I do if I wanted this to fail? (Inversion)
• What's the probability of success? What's my confidence level?
• What am I giving up by choosing this? (Opportunity Cost)
• Do I have adequate margin of safety?
• Is this within my circle of competence?

---

Sources & Further Reading

• Farnam Street - The Great Mental Models
• Farnam Street - Mental Models Guide
• James Clear - Mental Models
• ModelThinkers

---

"You only think you know, as a matter of fact. And most of your actions are based on incomplete knowledge and you really don't know what it is all about, or what the purpose of the world is, or know a great deal of other things. It is possible to live and not know." — Richard Feynman