naveedharri/benai-skills/decision-toolkit

Decision Toolkit

Overview

Create structured decision support materials that help humans think through significant choices systematically. This skill produces interactive tools, not just analysis — empowering the decision-maker rather than deciding for them.

Philosophy

Principles

1. Guide, don't decide — Tools illuminate the decision space; humans choose
2. One thing at a time — Reduce cognitive load through progressive disclosure
3. Multiple lenses — Same decision viewed through different frameworks reveals blind spots
4. Biases visible — Make cognitive biases explicit and checkable
5. Actionable output — End with concrete next steps, not abstract conclusions

Accessibility First

• Support screen readers (semantic HTML, ARIA labels)
• Keyboard navigable (tab order, focus states)
• High contrast by default (WCAG AA minimum)
• Reduced motion option
• Works without JavaScript (graceful degradation)
• Mobile-friendly touch targets (44px minimum)

Cognitive Inclusivity

Different people process decisions differently:

When to Use

Invoke this skill when user faces:

• Collaboration/partnership decisions
• Career or job changes
• Investment of significant time/money
• Project prioritization
• Technology/tool selection
• Any choice with multiple factors and uncertainty

Not for: Trivial decisions, emergency responses, or when user just needs information.

Decision Types

Type 1: Opportunity Evaluation

Should I pursue this opportunity?

• Partnership, job offer, investment, project

Type 2: Resource Allocation

Where should I invest my time/money/attention?

• Prioritization, budgeting, focus areas

Type 3: Risk Assessment

What could go wrong and is it worth it?

• New ventures, changes, experiments

Type 4: Trade-off Navigation

Which option among alternatives?

• Tool selection, hire decisions, strategic choices

The Decision Journey

Nine steps, each focused on one dimension:

┌─────────────────────────────────────────────────────────────┐
│  1. CONTEXT         What is the decision?                   │
│  2. FIRST PRINCIPLES Does this solve a real problem?        │
│  3. TIMING          Is now the right moment?                │
│  4. STAKEHOLDERS    Who else is involved? Are they stable?  │
│  5. BIASES          What might cloud my judgment?           │
│  6. OPPORTUNITY COST What am I giving up?                   │
│  7. SCENARIOS       What could happen?                      │
│  8. QUESTIONS       What do I still need to learn?          │
│  9. SYNTHESIS       Summary + decision                      │
└─────────────────────────────────────────────────────────────┘

Output Formats

1. Interactive HTML Guide (Primary)

Step-by-step wizard with:

• Progress indicator
• One question per screen
• State persistence across steps
• Final summary aggregating all inputs
• Keyboard navigation
• Print-friendly CSS

2. Markdown Framework

For offline/text-based use:

• Structured prompts
• Checkbox-style bias audit
• Fill-in-the-blank templates

3. Voice Summary

For audio consumption:

• 5-7 paragraph executive summary
• Orpheus TTS markup for emotional texture
• Key decision + rationale

4. PDF Report

For documentation/sharing:

• Professional formatting
• All frameworks applied
• Appendix with raw analysis

Frameworks Reference

First Principles Test

1. What problem does this solve?
2. Can I solve it myself?
3. Is this the best solution?
4. What assumptions am I making?
5. If starting fresh today, would I choose this?

Bias Checklist

□ FOMO — Am I afraid of missing out?
□ Sunk Cost — Am I factoring past investment?
□ Authority — Am I deferring to credentials?
□ Social Proof — Am I following the crowd?
□ Commitment — Do I feel locked in by past statements?
□ Optimism — Am I assuming problems will resolve?
□ Recency — Am I overweighting recent events?
□ Confirmation — Am I seeking validating info only?
□ Shiny Object — Is novelty distracting me?
□ Loss Aversion — Am I overweighting potential losses?

Opportunity Cost Calculator

Hours/week × Weeks × Hourly rate = Direct cost
+ What else could those hours produce?
+ What relationships/opportunities might suffer?
= True opportunity cost

Scenario Matrix

| Scenario | Probability | Outcome | Expected Value |
|----------|-------------|---------|----------------|
| Worst    | X%          | ...     | ...            |
| Bad      | X%          | ...     | ...            |
| Neutral  | X%          | ...     | ...            |
| Good     | X%          | ...     | ...            |
| Best     | X%          | ...     | ...            |

Pre-mortem

Imagine it's [future date]. This decision failed. Why?
 
Possible causes:
1. ...
2. ...
3. ...
 
Which causes are within my control?
Which warning signs should I watch for?

10-10-10 Framework

How will I feel about this decision in:
- 10 minutes?
- 10 months?
- 10 years?

Regret Minimization

Imagine you're 80 looking back.
Would you regret doing this?
Would you regret NOT doing this?

Implementation Guide

Step 1: Gather Context

Ask user for:

• What is the decision?
• What are the options?
• What's the timeline?
• What's at stake?
• Any relevant background?

Or extract from existing documents (meeting transcripts, notes).

Step 2: Choose Output Format

Based on user preference and context:

• Complex decision + time available → Interactive HTML
• Quick analysis → Markdown framework
• On-the-go consumption → Voice summary
• Need to share with others → PDF report

Step 3: Generate Tool

Use templates in templates/ directory:

• decision-guide-template.html — Full interactive wizard
• decision-framework.md — Text-based analysis
• decision-voice-summary.md — Audio script template

Step 4: Customize

Replace placeholders:

• {{DECISION_TITLE}} — What's being decided
• {{CONTEXT}} — Background information
• {{OPTIONS}} — Available choices
• {{STAKEHOLDERS}} — People/teams involved
• {{TIMELINE}} — Relevant dates
• {{FACTORS}} — Key evaluation criteria

Step 5: Apply Branding (Optional)

If using Agency brand:

• Import brand-agency skill CSS variables
• Use neobrutalism styling
• Apply Geist/EB Garamond typography

Accessibility Implementation

Semantic HTML

<main role="main" aria-label="Decision Guide">
  <nav aria-label="Progress">
    <ol role="list">...</ol>
  </nav>
  <section aria-labelledby="step-title">
    <h1 id="step-title">...</h1>
  </section>
</main>

Keyboard Navigation

// Ensure all interactive elements are focusable
// Tab order follows visual order
// Enter/Space activate buttons
// Arrow keys navigate options

Screen Reader Announcements

<div role="status" aria-live="polite" id="announcer">
  <!-- Announce step changes, selections, results -->
</div>

Color Contrast

/* Minimum 4.5:1 for normal text, 3:1 for large text */
--text-on-light: #000000;  /* 21:1 on white */
--text-on-dark: #ffffff;   /* 21:1 on black */
--text-on-primary: #ffffff; /* Check each color */

Reduced Motion

@media (prefers-reduced-motion: reduce) {
  * {
    animation: none !important;
    transition: none !important;
  }
}

Cultural Considerations

Individualist Framing

• "What do YOU want?"
• Personal goals and values
• Individual opportunity cost

Collectivist Framing

• "How does this affect your team/family?"
• Relationship implications
• Group harmony considerations

Power Distance Awareness

• Some cultures defer to authority figures
• Bias check should include "Am I deferring inappropriately?"
• Include stakeholder perspectives explicitly

Uncertainty Tolerance

• Some prefer detailed scenario analysis
• Others find it anxiety-inducing
• Offer both detailed and simplified views

Example Invocations

From Meeting Transcript

User: Analyze this meeting transcript and create a decision toolkit
Claude: [Extracts decision, stakeholders, options from transcript]
        [Generates interactive HTML guide]
        [Creates voice summary]

From Scratch

User: I need to decide whether to take a new job offer
Claude: [Asks clarifying questions]
        [Generates decision framework]
        [Customizes for career decision type]

Quick Analysis

User: Help me think through this partnership decision, just give me the frameworks
Claude: [Provides markdown framework]
        [Skips interactive tool]
        [Focuses on key questions]

Files

• SKILL.md — This file
• templates/decision-guide-template.html — Interactive wizard template
• templates/decision-framework.md — Text-based analysis template
• templates/decision-voice-summary.md — Audio script template
• references/bias-encyclopedia.md — Detailed bias descriptions
• references/framework-deep-dives.md — Extended framework explanations

Integration

Works well with:

• brand-agency — Apply visual branding
• transcript-analyzer — Extract decisions from meetings
• pdf-generation — Create shareable reports
• elevenlabs-tts — Generate audio summaries

Learnings

2026-01-09

Context: Initial skill creation from Synthius decision session

Key Insight: Dashboard-everything-at-once overwhelms. Step-by-step wizard with one concept per screen dramatically improves usability.

Architecture: 9-step journey covering all major decision dimensions. State object persists selections across steps. Summary aggregates everything.

Accessibility Note: High contrast neobrutalism actually helps accessibility — clear borders, distinct states, no subtle gradients.