Decision Matrix Builder

A structured decision-making skill that helps you evaluate options using weighted criteria scoring, sensitivity analysis, and clear recommendations. Works for any decision from choosing between job offers to selecting a tech stack, buying a car, or picking where to live. Produces a quantified analysis that separates emotion from evidence.

Supported Platforms & Integrations

Platform	Setup Method	Auth Type	Notes
Google Sheets	Service account	OAuth2	Exports the decision matrix as a formatted spreadsheet
Notion	Integration token	OAuth2	Creates a decision database entry with scoring table
Obsidian	Local vault path	None	Saves analysis as a markdown note in your vault
CSV Export	Local file	None	Exports raw matrix data for use in Excel or Numbers
Slack	Webhook URL	Webhook	Shares decision summary with a team channel
Mermaid	Inline rendering	None	Generates visual comparison charts in markdown

When to Use This Skill

• Use this when you are stuck between two or more options and going in circles
• Use this when a decision involves multiple competing criteria that are hard to weigh mentally
• Use this when you need to justify a decision to others with structured reasoning
• Use this when emotional bias might be clouding your judgment on a major life choice
• Use this when you want to understand how sensitive your decision is to changing priorities
• Use this when comparing job offers, apartments, software tools, or investment options
• Consider alternatives when the decision is trivial — spending 30 minutes analyzing lunch options is overkill
• Consider alternatives when the decision is purely emotional or values-based — not everything can be quantified

Quick Start

Copy
# ~/.claude/skills/decision-matrix-builder.yaml
default_scale: 1-10
weighting_method: percentage
include_sensitivity_analysis: true
include_recommendation: true
output_format: terminal
export_to: google_sheets
history_file: ~/.decisions/history.json

First Run Example

Copy
claude skill decision-matrix-builder --decision "Choose between job offers"

Expected Output

Decision Matrix Builder
========================

Decision: Choose between job offers

Step 1: Define your options
  Option A: Startup (Series B, 50 employees)
  Option B: Big Tech (FAANG, established team)
  Option C: Remote Agency (fully distributed)

Step 2: Define your criteria and weights
  Compensation      — Weight: 30%
  Growth Potential   — Weight: 25%
  Work-Life Balance  — Weight: 20%
  Team Quality       — Weight: 15%
  Location/Remote    — Weight: 10%
  Total: 100%

Step 3: Score each option (1-10 scale)

| Criteria          | Weight | Startup | Big Tech | Agency |
|-------------------|--------|---------|----------|--------|
| Compensation      | 30%    | 7       | 9        | 6      |
| Growth Potential  | 25%    | 9       | 6        | 7      |
| Work-Life Balance | 20%    | 5       | 7        | 9      |
| Team Quality      | 15%    | 8       | 8        | 6      |
| Location/Remote   | 10%    | 6       | 4        | 10     |
|-------------------|--------|---------|----------|--------|
| WEIGHTED SCORE    |        | 7.15    | 7.15     | 7.15   |

Result: Scores are remarkably close. Sensitivity analysis needed.

Sensitivity Analysis:
  If Compensation weight increases to 40%:
    Big Tech wins at 7.55 (others drop)
  If Growth Potential weight increases to 35%:
    Startup wins at 7.60
  If Work-Life Balance weight increases to 30%:
    Agency wins at 7.60

Recommendation: The three options are nearly tied overall. Your
decision hinges on which criterion matters MOST to you right now.
  - Choose Startup if career growth is your top priority
  - Choose Big Tech if maximizing compensation matters most
  - Choose Agency if work-life balance is non-negotiable

The sensitivity analysis shows this is a values-driven decision,
not a clear-cut analytical one. Trust your gut on the top priority.

Advanced Configuration

Platform-Specific Setup

Google Sheets Export

Copy
google_sheets:
  enabled: true
  spreadsheet_id: "your-spreadsheet-id"
  tab_name: "Decision Matrix"
  include_charts: true
  conditional_formatting: true
  share_with: []

Notion Decision Database

Copy
notion:
  enabled: true
  database_id: "your-decisions-database-id"
  properties:
    decision_name: "Decision"
    date: "Date"
    options: "Options"
    winner: "Selected Option"
    confidence: "Confidence"
    matrix_link: "Matrix File"

Full Options Reference

Parameter	Type	Default	Description
default_scale	string	1-10	Scoring scale for options against criteria
weighting_method	string	percentage	percentage (must sum to 100) or relative (ranked)
include_sensitivity_analysis	bool	true	Test how weight changes affect the outcome
include_recommendation	bool	true	Generate a natural language recommendation
output_format	string	terminal	terminal, markdown, csv, or json
export_to	string	none	google_sheets, notion, obsidian, or csv file
history_file	string	~/.decisions/history.json	Where to store past decisions for review
max_options	int	6	Maximum number of options to compare
max_criteria	int	10	Maximum criteria to prevent over-analysis
sensitivity_range	float	0.10	How much to shift weights in sensitivity analysis
tie_breaking	string	sensitivity	How to handle tied scores: sensitivity, gut_check, or none
show_normalized_scores	bool	true	Display scores normalized to 0-100 for clarity

Core Concepts

Concept	Purpose	How It Works
Weighted Scoring	Reflects priority differences	Each criterion gets a weight reflecting its importance; scores multiplied by weight
Sensitivity Analysis	Tests decision robustness	Shifts each weight up and down to see if the winner changes
Criteria Independence	Prevents double-counting	Skill checks if criteria overlap and suggests merging correlated factors
Gut Check	Validates the numbers	After scoring, asks if the result feels right — mismatches reveal hidden criteria
Decision Logging	Enables retrospective	Stores decisions for future review to see if the analysis led to good outcomes

Architecture

Decision Input
    |
    v
+-------------------+
| Option Definer    |----> List all options being compared
+-------------------+
    |
    v
+-------------------+
| Criteria Builder  |----> Define and weight evaluation criteria
+-------------------+
    |
    v
+-------------------+
| Scoring Engine    |----> Rate each option on each criterion (1-10)
+-------------------+
    |
    v
+-------------------+     +---------------------+
| Weighted Calculator|---->| Sensitivity Analyzer|
| (scores x weights) |     | (weight perturbation)|
+-------------------+     +---------------------+
    |                           |
    v                           v
+--------------------------------------+
| Recommendation Generator             |
| (clear winner, close call, or split) |
+--------------------------------------+
    |
    v
+-------------------+
| Export + Log      |----> Sheets, Notion, local file
+-------------------+

Workflow Examples

Scenario 1: Apartment Comparison

Input: 3 apartments with different trade-offs

Criteria and weights:
  Monthly Cost: 35% | Commute Time: 25% | Space: 20% |
  Neighborhood: 15% | Natural Light: 5%

Scoring:
  Apt A (downtown studio): Cost 4, Commute 10, Space 3, Neighborhood 9, Light 6
  Apt B (suburban 1BR): Cost 8, Commute 4, Space 8, Neighborhood 6, Light 9
  Apt C (midtown 1BR): Cost 5, Commute 7, Space 7, Neighborhood 8, Light 7

Result:
  Apt B: 6.55 | Apt C: 6.50 | Apt A: 5.95
  Apt B wins narrowly on cost advantage, but Apt C is within 1%.
  Sensitivity: If commute weight rises to 35%, Apt C overtakes Apt B.
  Recommendation: Visit both B and C in person — the numbers cannot decide this.

Scenario 2: Technology Stack Selection

Input: Choosing between React, Vue, and Svelte for a new project

Criteria and weights:
  Ecosystem/Libraries: 25% | Performance: 20% | Learning Curve: 20% |
  Hiring Pool: 20% | Bundle Size: 15%

Scoring:
  React: Ecosystem 10, Perf 7, Learning 5, Hiring 10, Bundle 5
  Vue: Ecosystem 7, Perf 8, Learning 8, Hiring 6, Bundle 7
  Svelte: Ecosystem 5, Perf 10, Learning 9, Hiring 3, Bundle 10

Result:
  React: 7.45 | Vue: 7.15 | Svelte: 7.05
  React wins on ecosystem and hiring, despite lower performance score.
  Sensitivity: If Hiring Pool drops to 10%, Svelte ties with React.
  Recommendation: React for team projects, Svelte for solo/greenfield.

Scenario 3: Revisiting a Past Decision

Input: User runs --review on a job decision made 6 months ago

Processing:
  - Loads the original decision matrix from history
  - Asks user to re-score each criterion based on actual experience
  - Compares predicted vs actual satisfaction

Output:
  Decision Review: Job Offer (made 6 months ago)
  Original winner: Startup (score 7.60)
  Actual satisfaction scores today:
    Compensation: predicted 7, actual 6 (equity less liquid than expected)
    Growth: predicted 9, actual 9 (confirmed — rapid skill development)
    Work-Life: predicted 5, actual 4 (more demanding than anticipated)
  Retrospective: Decision was correct for growth, but underestimated
  work-life impact. Factor this into future weighting.

Best Practices

1. Limit criteria to 5-7 factors — More than seven criteria dilutes the analysis and makes scoring exhausting. If you have 12 criteria, group related ones together. Commute time and location can merge into "accessibility."

2. Score before you see the weighted results — Complete all scoring before the calculation runs. Seeing intermediate results biases you toward adjusting scores to get the outcome you secretly want.

3. Pay attention to your reaction to the result — If the matrix says Option B wins but you feel disappointed, that emotional signal is data. It means you have an unweighted criterion — figure out what it is and add it.

4. Use sensitivity analysis for close calls — When options are within 5% of each other, the sensitivity analysis reveals which single priority shift would change the outcome. This is where the real insight lives.

5. Log decisions for retrospective review — Six months later, re-score based on reality. This feedback loop makes you a better decision-maker over time by calibrating your prediction accuracy.

Common Issues

1. All options score nearly the same — This usually means your criteria are too generic or your scores are clustered around 6-7. Force yourself to use the full 1-10 range and differentiate more sharply between options.

2. Weights do not sum to 100% — The skill will normalize automatically, but it helps to assign weights deliberately. Start by ranking criteria by importance, then distribute percentages top-down.

3. Decision feels wrong despite the numbers — This is valuable information. Add the missing emotional or intuitive criterion explicitly. "Gut excitement" with a 10% weight is a perfectly valid criterion to include.

Privacy & Data Handling

All decision matrices and scoring data are stored locally in ~/.decisions/history.json. No decision content, option names, or criteria are transmitted to external services. Google Sheets and Notion exports write only to your own accounts. If Slack sharing is enabled, only the summary table is sent — not your individual scores or reasoning. You retain full control and can delete all decision history by removing the ~/.decisions/ directory.