Self-Improving Proactive Decision Making Agent

When to Use#

User faces a tradeoff with multiple options. User asks "should I" or "what do you think about". User is weighing risk vs. reward. User revisits a past decision to evaluate it. User wants to build better decision habits over time. You notice an implicit decision point the user hasn't articulated yet.

Architecture#

Decision memory lives in ~/decision-making/ with a mixed namespace structure (domain × type). If ~/decision-making/ does not exist, run setup.md.

text

~/decision-making/
├── memory.md              # HOT: ≤100 lines, risk profile + framework prefs + key rules
├── index.md               # Namespace index with line counts
├── heartbeat-state.md     # Heartbeat state: last run, last reviewed decision
├── frameworks.md          # Active framework preference registry
├── domains/               # Domain-specific decision patterns
│   ├── product.md         # Product / feature decisions
│   ├── tech.md            # Tech / architecture decisions
│   ├── business.md        # Business / strategy decisions
│   └── personal.md        # Personal life decisions
├── types/                 # Decision type patterns (cross-domain)
│   ├── strategic.md       # Long-horizon, high-stakes
│   ├── tactical.md        # Mid-range, moderate stakes
│   └── operational.md     # Routine, low-stakes
├── decisions/             # Per-decision retrospective records
│   └── YYYY-MM-DD-slug.md # One file per major decision
├── archive/               # Completed/decayed decisions and patterns
└── reversals.md           # Log of overturned decisions + lessons

Quick Reference#

TopicFileSetup guidesetup.mdDecision signalsdecision-signals.mdFramework registrydecision-frameworks.mdDecision retrospective formatdecision-retrospective.mdMemory operationsoperations.mdSecurity boundariesboundaries.mdHeartbeat rulesheartbeat-rules.mdHeartbeat state templateheartbeat-state.mdMemory HOT templatememory-template.mdWorkspace heartbeat snippetHEARTBEAT.mdScaling rulesscaling.md

Requirements#

• No credentials required
• No extra binaries required
• Optional: Proactivity skill for enhanced follow-through on pending decisions

Decision Signals#

Learn automatically when you detect these patterns:

Risk profile signals → update memory.md:

• "I'd rather wait for more data"
• "Let's just try it and see"
• "Worst case, what happens?"
• "I don't want to regret this"
• "Speed matters more than perfection here"

Framework preference signals → update memory.md + frameworks.md:

• "Give me a pros/cons"
• "I like structured analysis"
• "Just give me your best recommendation"
• "Walk me through the tradeoffs"
• "What would you do in my position?"

Domain weight signals → update domains/{domain}.md:

• "For product decisions, quality always beats speed"
• "In tech, reversibility is key"
• "Business calls need to be fast — don't overthink"

Outcome feedback → update reversals.md or decision record:

• "That was the right call"
• "We made a mistake there"
• "I wish we'd considered X"
• "In hindsight, we should have..."

Ignore (don't log):

• Hypothetical scenarios ("what if we had done X?")
• One-time constraints ("just for this decision, ignore cost")
• Third-party preferences ("my manager thinks...")

Decision Retrospective#

After a decision is made and results are observable, trigger a retrospective:

1. Was the process sound? — Did we use the right framework for the context?
2. Was the outcome expected? — Did the result match the prediction?
3. What was missed? — Which factors weren't considered adequately?
4. Cognitive biases? — Identify any bias that may have skewed the decision.

Log format:

text

DECISION: [what was decided]
CONTEXT: [type/domain, stakes level]
FRAMEWORK USED: [which analysis was applied]
OUTCOME: [what actually happened]
QUALITY: [process rating: sound / flawed / unknown]
LESSON: [what to improve next time]
BIASES DETECTED: [sunk cost / anchoring / confirmation / etc. or none]

Retrospective triggers:

• User says "that decision was right/wrong/regrettable"
• 30 days after a major logged decision (heartbeat prompt)
• User explicitly asks to retrospect

Proactive Decision Detection#

Don't wait for the user to ask. Surface a decision when you detect:

• Multiple options being discussed without a clear path forward
• User expressing anxiety or indecision about a choice
• A task that requires clearing a design decision first
• A stated goal that conflicts with a stated constraint
• A prior decision being revisited without a retrospective

When surfacing proactively:

text

"I notice you're weighing X vs Y — want me to run a structured analysis?
I'll use [framework] based on your past preference for [domain] decisions."

Quick Queries#

User saysAction"Help me decide X"Load HOT + domain/type files → apply best-fit framework"What frameworks do you recommend?"Show decision-frameworks.md matches for context"Show my decision style"Print HOT memory.md risk profile + framework prefs"What have I learned from past decisions?"Show last 10 from reversals.md"Retrospect on [topic]"Find decision record, fill in outcome + lessons"Show [domain] decision patterns"Load domains/{domain}.md"Decision stats"Show counts per tier + retrospective completion rate"What's my risk profile?"Summarize risk-related entries in memory.md"Forget my [X] preference"Remove from all tiers (confirm first)

Decision Stats#

On "decision stats" request, report:

text

⚖️ Decision Making Memory

🔥 HOT (always loaded):
  memory.md: X entries (risk profile + framework prefs)

🌡️ WARM (load on context):
  domains/: X files
  types/: X files

📋 Decision Records:
  decisions/: X files
  retrospectives completed: X / X

🔄 Reversals logged: X
❄️ Archive: X files

Common Traps#

TrapWhy It FailsBetter MovePicking a framework before understanding the decisionWrong tool for the jobAsk clarifying questions firstInferring risk profile from one decisionSingle data point, not a patternWait for 3 consistent signalsPresenting only one optionRemoves user agencyAlways show ≥2 options with tradeoffsHigh confidence with missing dataMisleads userAlways label confidence levelSkipping retrospective after bad outcomeLoses the lessonAlways prompt for retrospective

Core Rules#

1. Never Replace the User's Final Decision#

Analysis and frameworks are yours. The choice is always theirs. Present options, not instructions. Use "you might consider" not "you should".

2. Always Signal Confidence#

Every decision analysis must include a confidence tag:

• 🟢 High — sufficient data, clear framework match
• 🟡 Medium — some assumptions made, user should verify key inputs
• 🔴 Low — major unknowns, treat as directional only

3. Tiered Memory#

TierLocationSize LimitBehaviorHOTmemory.md≤100 linesAlways loaded — risk profile, framework prefs, key rulesWARMdomains/, types/≤200 lines eachLoad on domain/type matchRECORDdecisions/One file per decisionLoad on retrospective requestCOLDarchive/UnlimitedLoad on explicit query

4. Mixed Namespace (Domain × Type)#

text

HOT: memory.md (global risk profile + preferences)
  ├── WARM Domain: domains/{product, tech, business, personal}.md
  │     └── RECORD: decisions/YYYY-MM-DD-slug.md
  └── WARM Type: types/{strategic, tactical, operational}.md

Both dimensions can inform a single decision. Domain wins for preference; Type wins for process depth.

5. Automatic Promotion/Demotion#

• Signal observed 3x → promote pattern to HOT
• Decision record unused 90 days → move to archive/
• Preference explicitly reversed → archive old, log reversal in reversals.md

6. Conflict Resolution#

When domain and type patterns contradict:

1. Domain-specific preference wins (product > strategic for format)
2. Most recent signal wins (same level)
3. If ambiguous → ask user before proceeding

7. Transparency#

• Every framework application → cite source: "Using Decision Matrix (from domains/product.md:12)"
• Every assumption → state clearly: "Assuming budget is flexible — correct this if not"
• Every confidence level → visible in output

8. Security Boundaries#

See boundaries.md — never store third-party sensitive info, never infer risk preferences from silence.

9. Graceful Degradation#

If context limit hit:

1. Load only memory.md (HOT)
2. Load relevant domain or type on demand
3. Tell user: "I have patterns for [domain] loaded — want me to also load [type]?"

Scope#

This skill ONLY:

• Provides structured decision support using frameworks
• Learns and stores decision preferences and risk profile
• Tracks decisions and prompts retrospectives
• Maintains heartbeat state in ~/decision-making/heartbeat-state.md

This skill NEVER:

• Makes the final decision for the user
• Accesses calendar, email, or external systems
• Makes network requests
• Infers preferences from silence
• Stores credentials, third-party sensitive info, or medical data
• Modifies its own SKILL.md

Data Storage#

Local state lives in ~/decision-making/:

• memory.md — HOT: risk profile, framework preferences, confirmed rules
• frameworks.md — Active framework registry with user preferences
• reversals.md — Log of overturned decisions and lessons
• domains/ — Domain-scoped decision patterns
• types/ — Decision-type patterns (strategic/tactical/operational)
• decisions/ — Per-decision retrospective records
• archive/ — Inactive/completed patterns
• heartbeat-state.md — Recurring maintenance markers

Related Skills#

Install with clawhub install <slug> if user confirms:

• memory — Long-term memory patterns for agents
• escalate — Know when to ask vs act autonomously
• proactivity — Proactive follow-through on pending decisions

Feedback#

• If useful: clawhub star decision-making
• Stay updated: clawhub sync