Skill: 0xneosoul/neosoul-decision-agent (version 1.0.0)

--- name: Self-Improving + Proactive Decision Making Agent slug: decision-making version: 1.0.0 homepage: https://clawic.com/skills/decision-making description: "Structured decision support with self-improving memory. Agent learns your decision style, risk profile, and framework preferences over time — and gets better at helping you decide with every interaction. Use when (1) you face a multi-option tradeoff; (2) you need risk/benefit analysis; (3) a decision is high-stakes or time-sensitive; (4) you ask 'what should I do about X'; (5) you want to retrospect on a past decision and update your mental model." changelog: "v1.0.0 — Complete rewrite from self-improving agent, specialized for decision-making domain." metadata: {"clawdbot":{"emoji":"⚖️","requires":{"bins":[]},"os":["linux","darwin","win32"],"configPaths":["~/decision-making/"],"configPaths.optional":["./AGENTS.md","./SOUL.md","./HEARTBEAT.md"]}} --- ## 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`. ``` ~/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 | Topic | File | |-------|------| | Setup guide | `setup.md` | | Decision signals | `decision-signals.md` | | Framework registry | `decision-frameworks.md` | | Decision retrospective format | `decision-retrospective.md` | | Memory operations | `operations.md` | | Security boundaries | `boundaries.md` | | Heartbeat rules | `heartbeat-rules.md` | | Heartbeat state template | `heartbeat-state.md` | | Memory HOT template | `memory-template.md` | | Workspace heartbeat snippet | `HEARTBEAT.md` | | Scaling rules | `scaling.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:** ``` 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: ``` "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 says | Action | |-----------|--------| | "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: ``` ⚖️ 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 | Trap | Why It Fails | Better Move | |------|--------------|-------------| | Picking a framework before understanding the decision | Wrong tool for the job | Ask clarifying questions first | | Inferring risk profile from one decision | Single data point, not a pattern | Wait for 3 consistent signals | | Presenting only one option | Removes user agency | Always show ≥2 options with tradeoffs | | High confidence with missing data | Misleads user | Always label confidence level | | Skipping retrospective after bad outcome | Loses the lesson | Always 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 | Tier | Location | Size Limit | Behavior | |------|----------|------------|----------| | HOT | memory.md | ≤100 lines | Always loaded — risk profile, framework prefs, key rules | | WARM | domains/, types/ | ≤200 lines each | Load on domain/type match | | RECORD | decisions/ | One file per decision | Load on retrospective request | | COLD | archive/ | Unlimited | Load on explicit query | ### 4. Mixed Namespace (Domain × Type) ``` 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`

path: _meta.json
content: slug: decision-making
version: 1.0.0
publishedAt: 1743307200000

path: corrections.md
content: # Decision Reversals Log — Template

> This file is created in `~/decision-making/reversals.md` when you first use the skill.
> Keeps a running log of overturned decisions and the lessons extracted.
> Replaces the original `corrections.md` — the equivalent of corrections for decision-making is a reversal.

## Example Entries

```markdown
# Decision Reversals Log

## 2026-03-20

### 14:32 — Tech / Strategic
- **Decision reversed:** Chose PostgreSQL over SQLite for the MVP
- **Why overturned:** Storage and infra overhead was too high at early scale
- **Lesson:** For MVPs with < 1000 users, SQLite is sufficient; revisit at scale
- **Domain lesson added:** domains/tech.md — "MVP storage: default SQLite, revisit at 1k users"
- **Count:** 1 (first occurrence of this type)

## 2026-03-15

### 09:15 — Product / Tactical  
- **Decision reversed:** Shipped feature X without user research
- **Why overturned:** User adoption was 4%, far below expectations
- **Lesson:** For product features affecting onboarding, always require ≥5 user interviews first
- **Domain lesson added:** domains/product.md — "onboarding-impacting features: require ≥5 interviews"
- **Count:** 2 (second occurrence — watch for 3rd to confirm pattern)
```

## Log Format

Each entry includes:
- **Timestamp** — When the reversal was acknowledged
- **Domain + Type** — Which namespace this belongs to
- **Decision reversed** — What was originally decided
- **Why overturned** — The actual cause (user-stated, not inferred)
- **Lesson** — The extracted reusable rule
- **Domain lesson added** — Whether it was written to a WARM file (and where)
- **Count** — How many times this type of reversal has occurred (for pattern promotion)

## Reversal Types

| Type | Example | Namespace |
|------|---------|-----------|
| Framework mismatch | "We used Pros/Cons but needed a matrix" | global or domain |
| Weight error | "We prioritized speed over quality — wrong call" | domain |
| Missing factor | "We didn't consider exit cost" | domain or type |
| Timing error | "Decided too fast without enough data" | global |
| Scope creep | "What we thought was tactical was actually strategic" | type |
| Assumption failure | "Our cost assumption was off by 3×" | domain |

## Pattern Promotion

After 3 similar reversals of the same type:
```
Agent: "I've noticed a recurring pattern: [description] has led to a reversal 3 times.
        Should I add this as a standing rule to your [domain] decision patterns?
        - Yes, add to domains/{domain}.md
        - Yes, add to memory.md (global)
        - No, keep case by case"
```


path: memory-template.md
content: # HOT Memory — Template

> This file is created in `~/decision-making/memory.md` when you first use the skill.
> Keep it ≤100 lines. Risk profile, framework preferences, and confirmed rules live here.

## Example Entries

```markdown
# Decision Making Memory (HOT Tier)

## Risk Profile
- risk-tolerance: conservative               # conservative / experimental / context-dependent
- regret-style: regret-minimizing            # regret-minimizing / opportunity-seeking
- uncertainty-response: data-first           # data-first / bias-to-action
- reversibility: high priority               # high priority / low priority / domain-dependent

## Framework Preferences
- default: Decision Matrix
- personal decisions: 10/10/10
- high-stakes add-on: Pre-mortem
- output style: structured (not conversational)  # structured / dialogue / direct-recommendation

## Domain Weights
- product: quality > speed; user feedback breaks ties
- tech: reversibility > performance > speed
- business: cost is a hard constraint; ROI must be visible in 6 months
- personal: long-term regret minimization over short-term comfort

## Confirmed Rules
- Always present ≥2 options, never a single recommendation
- Surface second-order effects for any strategic decision
- Never commit to irreversible decisions in the same session they're raised
- Prompt for retrospective 30 days after high-stakes decisions (via heartbeat)
```

## Fields Reference

| Field | What to Fill | Where Learned |
|-------|-------------|---------------|
| `risk-tolerance` | conservative / experimental / context-dependent | Onboarding Q1 |
| `regret-style` | regret-minimizing / opportunity-seeking | Onboarding Q1 |
| `uncertainty-response` | data-first / bias-to-action | Onboarding Q1 + signals |
| `reversibility` | high priority / low priority / domain-dependent | Onboarding Q4 + signals |
| `default framework` | Name of most-used framework | Onboarding Q2 + signals |
| `output style` | structured / dialogue / direct-recommendation | Onboarding Q2 |
| Domain weights | What matters most per domain | Onboarding Q3 + signals |
| Confirmed rules | Only rules the user has explicitly confirmed | After 3 signals + confirmation |

## Usage

The agent will:
1. Load this file at the start of every session
2. Use risk profile + framework preferences as defaults for all decision support
3. Add entries after confirmed signals (3x + user confirmation)
4. Demote unused patterns to WARM after 90 days
5. Never exceed 100 lines (compacts automatically)
6. Always cite source when applying a preference: "Using Decision Matrix (memory.md:12)"


path: operations.md
content: # Memory Operations

## User Commands

| Command | Action |
|---------|--------|
| "Help me decide X" | Load HOT + best-fit domain/type files → select framework → run structured analysis |
| "What frameworks do you recommend?" | Match context to `decision-frameworks.md`, explain why each fits |
| "Show my decision style" | Print risk profile + framework preferences from `memory.md` |
| "Show my [domain] patterns" | Load and display `domains/{domain}.md` |
| "What have I learned from past decisions?" | Show last 10 from `reversals.md` |
| "Retrospect on [topic/date]" | Find decision record, fill in outcome + lessons |
| "Decision stats" | Show tier sizes, retrospective completion rate, reversal count |
| "What's my risk profile?" | Summarize risk-related entries from memory.md |
| "What do you know about X?" | Search all tiers, return matches with sources |
| "Forget my [X] preference" | Remove from all tiers, confirm deletion |
| "Forget everything" | Full wipe with export option |
| "Export memory" | Generate downloadable archive of ~/decision-making/ |

---

## Automatic Operations

### On Session Start
1. Load `memory.md` (HOT — risk profile, framework prefs, confirmed rules)
2. Check `index.md` for context hints
3. If domain detected (product / tech / business / personal) → preload relevant `domains/` file
4. If decision type detected (strategic / tactical / operational) → preload relevant `types/` file

### On Decision Request Received

```
1. Identify decision domain and type from context
2. Load HOT memory.md
3. Load matching domain + type files (≤2 files)
4. Select framework:
   a. Check memory.md for explicit preference
   b. Check decision-frameworks.md domain/type defaults
   c. If ambiguous → default Pros/Cons, offer to go deeper
5. State framework + reason + confidence level
6. Run analysis, present ≥2 options with tradeoffs
7. Do NOT make final decision for user
8. Offer to log decision record if stakes = high
```

### On Decision Signal Received

```
1. Classify signal type (risk / framework / domain-weight / outcome-feedback)
2. Check if duplicate or contradiction in any tier
3. If new:
   - Log with timestamp and confidence
   - Increment signal counter for type
4. If duplicate:
   - Bump counter, update timestamp
   - If counter >= 3: trigger confirmation flow (see decision-signals.md)
5. Determine scope (global / domain / type / one-time)
6. Write to appropriate file
7. Update index.md
```

### On Outcome Feedback Received

```
1. Find the related decision record in decisions/
   (match by topic keyword, date, or user description)
2. If found:
   - Append outcome field
   - Set status to "outcome logged"
   - Trigger retrospective flow
3. If not found:
   - Log to reversals.md directly with best-available context
   - Prompt: "Should I create a decision record for this?"
4. Extract any lesson → propose adding to domains/{domain}.md or memory.md
```

### Weekly Maintenance (Heartbeat)

```
1. Scan decisions/ for records > 30 days without outcome logged
2. Prompt user to retrospect on those decisions
3. Scan domains/ and types/ for entries updated > 90 days ago
4. Move clearly expired patterns to archive/
5. Run compaction if any file > size limit
6. Update index.md
7. Generate weekly digest (optional)
```

---

## File Formats

### memory.md (HOT)

```markdown
# Decision Making Memory

## Risk Profile
- risk-tolerance: conservative / experimental / [domain-specific overrides]
- regret-style: regret-minimizing / opportunity-seeking
- info-style: data-first / bias-to-action

## Framework Preferences
- default: Decision Matrix
- personal decisions: 10/10/10
- high-stakes: Pre-mortem add-on

## Domain Weights
- tech: reversibility > speed
- product: quality > feature count
- business: cost is a hard constraint

## Confirmed Rules
- Never commit to irreversible decisions same-day
- Always surface second-order effects for strategic decisions
```

### reversals.md

```markdown
# Decision Reversals Log

| Date | Decision Topic | Why Overturned | Lesson | Domain |
|------|---------------|----------------|--------|--------|
| 2026-03-01 | Chose vendor A | Hidden migration cost | Always estimate exit cost | business |
```

### decisions/YYYY-MM-DD-slug.md

```markdown
# Decision: [title]

See decision-retrospective.md for full format.

Status: ⏳ pending outcome
```

### domains/{name}.md

```markdown
# Domain: Product

Inherits: global (memory.md)

## Weights
- quality > speed
- user feedback breaks ties

## Patterns
- Use Decision Matrix for feature prioritization
- Always check reversibility before structural changes

## Overrides
- framework: avoid Pre-mortem for small product decisions (too slow)

## History
- Created: 2026-01-15
- Last active: 2026-03-15
- Signals recorded: 8
```

---

## Edge Case Handling

### Contradiction Detected

```
Signal A: "Speed matters most" (operational, confirmed)
Signal B: "Don't rush decisions" (today, same domain)

Resolution:
1. Flag as contradiction
2. Do not overwrite A silently
3. Ask: "You've previously noted speed matters most for [domain].
           Does today's signal change your default, or is this decision-specific?"
```

### Context Ambiguity

```
User says: "Remember I like to see multiple options"

But which scope?
1. Check current decision domain
2. If unclear, ask: "Should this apply to all decisions, or just [domain]?"
3. Default to domain-level, not global, until confirmed
```

### No Matching Decision Record Found

```
User: "That decision about the pricing model was wrong"

Agent:
1. Search decisions/ and reversals.md for "pricing" + recent dates
2. If not found: "I don't have a logged record for that — want me to create one
   now so we can extract the lesson properly?"
3. Log lesson to reversals.md regardless
```


path: setup.md
content: # Setup — Self-Improving + Proactive Decision Making Agent

## First-Time Setup

### 1. Create Memory Structure

```bash
mkdir -p ~/decision-making/{domains,types,decisions,archive}
```

### 2. Initialize Core Files

Create `~/decision-making/memory.md` using `memory-template.md`:

```markdown
# Decision Making Memory (HOT Tier)

## Risk Profile
(filled from onboarding)

## Framework Preferences
(filled from onboarding)

## Domain Weights
(filled from onboarding)

## Confirmed Rules
```

Create `~/decision-making/reversals.md`:
```markdown
# Decision Reversals Log

| Date | Decision Topic | Why Overturned | Lesson | Domain |
|------|---------------|----------------|--------|--------|
```

Create `~/decision-making/frameworks.md`:
```markdown
# Framework Preferences (Active)

(Copy from decision-frameworks.md after onboarding customization)
```

Create `~/decision-making/index.md`:
```markdown
# Decision Making Index

| File | Lines | Last Updated |
|------|-------|--------------| 
| memory.md | 0 | — |
| reversals.md | 0 | — |
| frameworks.md | 0 | — |
```

Create `~/decision-making/heartbeat-state.md`:
```markdown
# Decision Making Heartbeat State

last_heartbeat_started_at: never
last_reviewed_decision_at: never
last_heartbeat_result: never
pending_retrospectives: []

## Last actions
- none yet
```

### 3. Onboarding — Decision Style Profile

Run this onboarding dialogue before doing anything else. Do NOT skip it.

Say to the user:

```
Before I can give you really useful decision support, I'd like to understand
your decision style — this takes about 2 minutes and will make every future
analysis much better calibrated to how you think.
```

Then ask the following questions **one at a time**, waiting for each answer:

**Q1 — Risk tolerance:**
```
"When facing an important decision with incomplete information, do you tend to:
  (a) Wait until you have more data — even if it means a slower choice
  (b) Make a call now and correct course if needed
  (c) It depends heavily on the domain — tell me more"
```

**Q2 — Analysis style:**
```
"When you work through a hard decision, do you prefer:
  (a) A quick pros/cons — fast and rough
  (b) A structured matrix — criteria-weighted and scored
  (c) Talking through the tradeoffs conversationally
  (d) Just give me your best recommendation"
```

**Q3 — Primary decision domains:**
```
"What kinds of decisions do you face most often? Pick all that apply:
  - Product / feature decisions
  - Tech / architecture decisions
  - Business / strategy decisions
  - Personal / career decisions"
```

**Q4 — Stakes threshold:**
```
"At what point does a decision feel 'high stakes' to you?
  (a) Any decision that's hard to reverse
  (b) Decisions with significant financial impact
  (c) Decisions that affect other people
  (d) I just know it when I feel it"
```

After collecting answers, write a risk profile to `~/decision-making/memory.md` using the **memory-template.md** structure. Confirm with the user before saving:

```
"Here's what I've captured as your decision profile:
[show summary]
Does this feel right? I can adjust anything."
```

### 4. Initialize Domain Files

For each domain the user selected in Q3, create `~/decision-making/domains/{domain}.md`:

```markdown
# Domain: [Name]

Inherits: global (memory.md)

## Weights
(from onboarding answers)

## Patterns
(empty — populated from signals)

## History
- Created: [date]
- Signals recorded: 0
```

### 5. Add SOUL.md Steering

Add this section to your `SOUL.md`:

```markdown
**Decision Making**
Structured decision support is part of the job.
Before any decision request, load `~/decision-making/memory.md` and the smallest matching domain or type file.
Apply the user's preferred framework unless the situation clearly calls for something different.
Always tag confidence level. Never make the final call — present options and tradeoffs.
Surface decision points proactively when you notice the user weighing choices without structure.
After high-stakes decisions, prompt for a retrospective when results are visible.
```

### 6. Add AGENTS.md Memory Section (Non-Destructive)

Update `AGENTS.md` by complementing the existing `## Memory` section. Do not replace or remove existing lines.

Add this line in the continuity list:

```markdown
- **Decision making:** `~/decision-making/` (via `decision-making` skill) — decision preferences, risk profile, framework choices, decision history, and retrospective lessons
```

After "Capture what matters...", add:

```markdown
Use `~/decision-making/memory.md` for risk profile and framework preferences (HOT, always loaded).
Use `~/decision-making/domains/` for domain-specific decision weights and patterns.
Use `~/decision-making/types/` for decision-type patterns (strategic/tactical/operational).
Use `~/decision-making/decisions/` for individual decision records and retrospectives.
Before any decision support task, load memory.md, then the smallest relevant domain + type files.
```

### 7. Add HEARTBEAT.md Steering

Add this section to your `HEARTBEAT.md`:

```markdown
## Decision Making Check

- Read `./skills/decision-making/heartbeat-rules.md`
- Use `~/decision-making/heartbeat-state.md` for last-run markers
- If no file inside `~/decision-making/` changed since last reviewed decision, return `HEARTBEAT_OK`
```

## Verification

Run "decision stats" to confirm setup:

```
⚖️ Decision Making Memory

🔥 HOT (always loaded):
   memory.md: 0 entries

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

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

🔄 Reversals logged: 0
❄️ Archive: 0 files
```


path: decision-retrospective.md
content: # Decision Retrospective

Track retrospectives for completed decisions. Each entry captures what the agent and user learned from evaluating a past decision against real-world outcomes.

---

## Format

```markdown
## [Date] — [Decision Slug]

**Decision:** What was actually decided
**When made:** Date of original decision
**Domain:** product / tech / business / personal
**Type:** strategic / tactical / operational
**Stakes:** low / medium / high
**Framework used:** What analysis was applied at the time
**Assumptions made:** Key assumptions that underpinned the decision

**Outcome:** What actually happened
**Expected outcome:** What was predicted
**Match:** ✅ as expected / ⚠️ partial / ❌ different / ⏳ too early to tell

**Quality assessment:**
- Process: sound / flawed / unclear
- Information used: complete / partial / insufficient
- Cognitive biases detected: none / [list specific biases]

**Lesson:** What to do differently next time
**Pattern update:** Was memory.md updated? (yes / no / pending)

**Status:** ⏳ pending outcome | 📋 outcome logged | ✅ lessons extracted | 📦 archived
```

---

## Example Entry

```markdown
## 2026-03-15 — adopt-nextjs-for-product

**Decision:** Migrate frontend stack from CRA to Next.js
**When made:** 2026-02-01
**Domain:** tech
**Type:** strategic
**Stakes:** high
**Framework used:** Decision Matrix (performance / DX / team familiarity / SEO)
**Assumptions made:** Team would adapt within 2 sprints; SEO improvement would be measurable in 60 days

**Outcome:** Migration took 4 sprints; SEO improved by 34% in 45 days
**Expected outcome:** 2 sprints; SEO impact visible within 60 days
**Match:** ⚠️ partial

**Quality assessment:**
- Process: sound — criteria were right, weights were reasonable
- Information used: partial — underestimated team's ramp-up time
- Cognitive biases detected: optimism bias on team velocity

**Lesson:** For tech migrations, add 2× buffer to team ramp-up estimates
**Pattern update:** yes — added to domains/tech.md: "migration timelines: 2× stated estimate"

**Status:** ✅ lessons extracted
```

---

## Cognitive Bias Reference

Use during quality assessment. Common biases in decision-making:

| Bias | Description | Detection Signal |
|------|-------------|-----------------|
| **Confirmation bias** | Seeking info that confirms existing preference | "I already knew this was the right call" |
| **Anchoring** | Over-weighting the first number / option seen | Estimate stayed close to initial figure |
| **Sunk cost** | Continuing because of past investment | "We've come too far to stop now" |
| **Optimism bias** | Underestimating difficulty / overestimating success | Timeline / cost was shorter than actual |
| **Availability heuristic** | Overweighting recent or vivid examples | "It worked for [recent case], so..." |
| **Status quo bias** | Preferring inaction or the default option | Chose the "safe" path without full analysis |
| **FOMO** | Deciding fast due to fear of missing out | Time pressure was artificial |
| **Overconfidence** | Confidence level higher than information warranted | 🟡 or 🔴 confidence felt like 🟢 |

---

## Retrospective Triggers

Log a retrospective when any of the following occurs:

1. User explicitly says the decision was right, wrong, or mixed
2. Heartbeat detects a decision record older than 30 days without an outcome
3. User revisits a past decision by name or date
4. Agent notices a contradiction between a past decision and new information

When triggering via heartbeat, prompt with:
```
"You made a decision about [topic] on [date] — have you seen results yet?
If so, a quick retrospective could sharpen future [domain] decisions."
```

---

## Promotion Rules

After a retrospective is completed:
- If **lesson** is applicable future pattern → add to `domains/{domain}.md` or `types/{type}.md`
- If **bias** appeared for the 2nd time → add bias awareness note to `memory.md`
- If **framework** was misapplied → update `decision-frameworks.md` domain default
- Decision record itself → stays in `decisions/` for 90 days, then moves to `archive/`

---

## Entries

(New retrospective entries are stored in `~/decision-making/decisions/YYYY-MM-DD-slug.md`)

This file is a **format reference only**. Individual decision records live in the `decisions/` directory.


path: heartbeat-rules.md
content: # Heartbeat Rules

Use heartbeat to keep `~/decision-making/` organized, prompt pending retrospectives, and surface aging decisions — without creating churn or losing data.

## Source of Truth

Keep the workspace `HEARTBEAT.md` snippet minimal.
Treat this file as the stable contract for decision-making heartbeat behavior.
Store mutable run state only in `~/decision-making/heartbeat-state.md`.

## Start of Every Heartbeat

1. Ensure `~/decision-making/heartbeat-state.md` exists.
2. Write `last_heartbeat_started_at` immediately in ISO 8601.
3. Read the previous `last_reviewed_decision_at`.
4. Scan `~/decision-making/` for files changed after that moment, excluding `heartbeat-state.md` itself.
5. Scan `~/decision-making/decisions/` for records with status `⏳ pending outcome` that are > 30 days old.

## If Nothing Changed and No Pending Retrospectives

- Set `last_heartbeat_result: HEARTBEAT_OK`
- Append a short "no material change" note
- Return `HEARTBEAT_OK`

## If Something Changed

Only do conservative organization:

- Refresh `index.md` if counts or file references drift
- Compact oversized files by merging duplicates or summarizing repetitive entries
- Move clearly misplaced notes to the right namespace only when the target is unambiguous
- Preserve confirmed rules, risk profile, and explicit domain weights exactly
- Update `last_reviewed_decision_at` only after the review finishes cleanly

## Retrospective Prompts (Decision-Specific)

If any `decisions/*.md` file has `status: ⏳ pending outcome` and was created > 30 days ago:

1. List those decisions in `heartbeat-state.md` under `pending_retrospectives`
2. On next session start, surface this prompt:
   ```
   "📋 A few decisions are waiting for retrospectives:
    - [slug] (made on [date])
    Would you like to log outcomes now? A quick retrospective can sharpen future [domain] decisions."
   ```
3. Do NOT auto-fill outcomes — wait for user input

## If Patterns Are Stale (90-day check)

- Scan `domains/*.md` and `types/*.md` for entries not referenced in 90 days
- Move stale entries to `archive/` with a dated archive block
- Log in heartbeat-state.md: `archived: {file}: {entry_summary} — unused 90 days`
- Do NOT delete — archive only

## Safety Rules

- Most heartbeat runs should do nothing
- Prefer append, summarize, or index fixes over large rewrites
- Never delete data, empty files, or overwrite uncertain text
- Never reorganize files outside `~/decision-making/`
- If scope is ambiguous, leave files untouched and record a suggested follow-up instead
- Never auto-complete retrospectives — only prompt, never fill

## State Fields

Keep `~/decision-making/heartbeat-state.md` simple:

- `last_heartbeat_started_at`
- `last_reviewed_decision_at`
- `last_heartbeat_result`
- `pending_retrospectives` — list of decision slugs awaiting outcome
- `last_actions`

## Behavior Standard

Heartbeat exists to keep the memory system tidy and decisions accountable.
If no rule is clearly violated and no retrospective is pending, do nothing.


path: HEARTBEAT.md
content: ## Decision Making Check

- Read `./skills/decision-making/heartbeat-rules.md`
- Use `~/decision-making/heartbeat-state.md` for last-run markers and pending retrospective list
- If no file inside `~/decision-making/` changed since the last reviewed decision, and no retrospectives are pending, return `HEARTBEAT_OK`


path: boundaries.md
content: # Security Boundaries

## Never Store

| Category | Examples | Why |
|----------|----------|-----|
| Credentials | Passwords, API keys, tokens, SSH keys | Security breach risk |
| Financial specifics | Card numbers, bank accounts, exact salaries | Fraud / privacy risk |
| Medical | Diagnoses, medications, conditions | Privacy, HIPAA |
| Biometric | Voice patterns, behavioral fingerprints | Identity theft |
| Third parties | Other people's preferences, decisions, constraints | No consent obtained |
| Location patterns | Home/work addresses, travel routines | Physical safety |

## Store with Caution

| Category | Rules |
|----------|-------|
| Business context | Decay after project ends, never share cross-project |
| Emotional state signals | Only if user explicitly connects them to decision style; never infer |
| Relationship roles | Roles only ("manager", "co-founder"), no personal details |
| Financial constraints | Budget ranges OK ("budget is tight"), no exact figures |

## Decision-Specific Boundaries

### NEVER
- Make the final decision for the user — present analysis, not orders
- Express high confidence (🟢) when key inputs are missing or unverified
- Hide uncertainty — if data is incomplete, say so clearly
- Recommend an option that conflicts with the user's stated values
- Auto-complete a retrospective — the user must confirm outcomes, not the agent
- Store another person's decision patterns as if they were the user's

### ALWAYS
- Tag every decision output with a confidence level (🟢 / 🟡 / 🔴)
- Present at least two options — never a single "right answer"
- State assumptions explicitly before the analysis
- Separate your analysis from the user's choice: "Based on this, Options A and B are strongest — the call is yours"
- Prompt for a retrospective on high-stakes decisions after results become visible

## Transparency Requirements

1. **Audit on demand** — "What do you know about my decision style?" → full export of memory.md + domains + reversals
2. **Source tracking** — Every applied pattern tagged with when/how learned
3. **Explain actions** — "I used Decision Matrix here because you prefer structured analysis for product decisions (memory.md:8)"
4. **State assumptions** — Always surface assumptions at the top of the analysis
5. **Confidence visible** — Never omit confidence level
6. **Deletion verification** — Confirm item removed, show updated state

## Red Flags to Catch

If you find yourself doing any of these, STOP:

- Recommending a single option without showing tradeoffs
- Expressing certainty when key inputs are missing
- Filling in a retrospective outcome without user confirmation
- Inferring risk tolerance from a single high-pressure decision
- Storing third-party preferences ("your manager wants X") as the user's own
- Building a psychological profile from decision patterns
- Applying a domain weight silently in the wrong domain
- Keeping data the user asked to forget

## Kill Switch

User says "forget everything":
1. Export current `~/decision-making/` to a ZIP file (so they can review)
2. Wipe all decision memory, risk profile, framework preferences, reversals, decision records
3. Confirm: "Decision memory cleared. Starting fresh with a clean profile."
4. Do not retain ghost preferences in behavior

## Consent Model

| Data Type | Consent Level |
|-----------|---------------|
| Explicit risk profile (onboarding) | Explicit opt-in |
| Framework preferences from usage | Implied by 3 consistent signals → confirm |
| Domain weights stated explicitly | Implied by explicit statement |
| Decision records | Ask before creating for each high-stakes decision |
| Cross-session patterns | Explicit confirmation required after 3 signals |


path: memory.md
content: # HOT Memory — Template

> This file is created in `~/self-improving/memory.md` when you first use the skill.
> Keep it ≤100 lines. Most-used patterns live here.

## Example Entries

```markdown
## Preferences
- Code style: Prefer explicit over implicit
- Communication: Direct, no fluff
- Time zone: Europe/Madrid

## Patterns (promoted from corrections)
- Always use TypeScript strict mode
- Prefer pnpm over npm
- Format: ISO 8601 for dates

## Project defaults
- Tests: Jest with coverage >80%
- Commits: Conventional commits format
```

## Usage

The agent will:
1. Load this file on every session
2. Add entries when patterns are used 3x in 7 days
3. Demote unused entries to WARM after 30 days
4. Never exceed 100 lines (compacts automatically)


path: scaling.md
content: # Scaling Patterns

## Volume Thresholds

| Scale | Entries | Strategy |
|-------|---------|----------|
| Early | < 20 signals | Single memory.md, minimal namespacing |
| Growing | 20–100 | Split into domains/, basic indexing |
| Established | 100–500 | Full domain × type hierarchy, compaction |
| Mature | > 500 | Archive yearly decisions, summary-only HOT |

## Namespace Structure: Domain × Type

Both dimensions exist simultaneously. A single decision can match both a domain and a type.

```
HOT: memory.md (global risk profile + framework prefs)
  │
  ├── DOMAIN warmth (product / tech / business / personal)
  │     → Load when domain detected in conversation
  │     → Provides: weights, framework defaults, domain-specific patterns
  │
  └── TYPE warmth (strategic / tactical / operational)
        → Load when decision type detected
        → Provides: depth of analysis, recommended add-ons, time horizons
```

**How to handle conflicts:** Domain wins for preference (what to care about); Type wins for process (how deep to go).

## When to Split a New Namespace File

Create a new `domains/{name}.md` when:
- A domain has 10+ domain-specific signals
- User explicitly separates contexts ("for product decisions..." / "when it comes to my personal life...")
- Domain file exceeds 200 lines

Create a new `types/{name}.md` when:
- A decision type has 10+ type-specific patterns
- User distinguishes decision depth explicitly ("quick call" = operational, "long-term bet" = strategic)

## Compaction Rules

### Merge Similar Signals
```
BEFORE (3 entries):
- [03-01] "Reversibility matters" (tech decision)
- [03-05] "Can we undo this?" (tech decision)
- [03-10] "What's the exit strategy?" (tech decision)

AFTER (1 entry):
- tech: prioritize reversibility (confirmed 3x, 03-01 to 03-10)
```

### Summarize Verbose Retrospective Lessons
```
BEFORE:
- When evaluating new technology, we underestimated the team ramp-up,
  we were too optimistic about timeline, and we didn't account for
  integration complexity with existing systems.

AFTER:
- New tech adoption: 2× timeline buffer; check integration complexity early
```

### Archive Decision Records
When moving to COLD:
```
## Archived [YYYY-MM]

### Decision: [slug] (made [date], archived [date])
- Domain: tech
- Outcome: ⚠️ partial
- Key lesson: archived to archive/YYYY.md
- Reason: 90 days elapsed, lessons extracted to domains/tech.md
```

## Index Maintenance

`index.md` tracks all active namespaces:
```markdown
# Decision Making Index

## HOT (always loaded)
- memory.md: 42 lines, updated 2026-03-15

## WARM Domain (load on domain match)
- domains/product.md: 34 lines
- domains/tech.md: 67 lines
- domains/business.md: 22 lines

## WARM Type (load on type match)
- types/strategic.md: 45 lines
- types/tactical.md: 28 lines

## Decision Records (load on retrospective)
- decisions/: 8 files

## COLD (archive)
- archive/2025.md: 134 lines

Last compaction: 2026-03-01
Next scheduled: 2026-04-01
```

## Recovery Patterns

### Context Lost
If agent loses context mid-session:
1. Re-read memory.md (HOT)
2. Check index.md for relevant namespaces
3. Ask user: "What domain and type is this decision? (product/tech/business/personal + strategic/tactical/operational)"
4. Load matching files and continue

### Contradiction Recovery
If memory entries contradict each other:
1. Surface both to user: "I have two conflicting preferences recorded for [domain]. Which is current?"
2. Archive the outdated one with timestamp
3. Confirm the current one remains active
4. Log reversal in reversals.md

### Decision Record Not Found
If a user references a decision that has no record:
1. Try to reconstruct from reversals.md and domains/ patterns
2. Create new record with best-available context
3. Mark as "reconstructed" — do not treat reconstructed info as confirmed


path: decision-frameworks.md
content: # Decision Frameworks

This file is the **framework index**. It does NOT store step-by-step instructions — the agent generates those at runtime. It stores which frameworks exist, when to reach for them, and what the user prefers.

---

## Framework Registry

| Framework | Best For | Decision Type | Stakes Level | User Preference |
|-----------|----------|---------------|--------------|-----------------|
| **Pros / Cons** | Simple binary choices | Any | Low–Medium | — |
| **Decision Matrix** | Multi-criteria, multiple options | Tactical / Operational | Medium | — |
| **MECE Tree** | Decomposing complex problem space | Strategic | High | — |
| **Pre-mortem** | Stress-testing a plan before committing | Strategic / Tactical | High | — |
| **10 / 10 / 10** | Personal decisions with emotional weight | Personal | Any | — |
| **Second-Order Thinking** | Long-term consequence mapping | Strategic | High | — |
| **OODA Loop** | Fast-moving, iterative, time-pressured | Tactical / Operational | Variable | — |
| **Cost of Delay** | Prioritization across competing options | Product / Tech | Medium–High | — |
| **Reversibility Test** | Deciding how much analysis a decision warrants | Any | Any | — |
| **Weighted Scoring** | Quantifying qualitative tradeoffs | Tactical | Medium | — |
| **Devil's Advocate** | Challenging an already-leaning conclusion | Any | High | — |
| **Regret Minimization** | Long-horizon personal or career decisions | Personal / Strategic | High | — |

---

## Domain → Framework Defaults

> Populated from user signals. Initial values are reasonable defaults; update after 3 confirmed signals.

| Domain | Default Framework | Fallback |
|--------|------------------|---------|
| Product | Decision Matrix | Pros / Cons |
| Tech | Reversibility Test → Decision Matrix | MECE Tree |
| Business | Second-Order Thinking | Weighted Scoring |
| Personal | 10 / 10 / 10 | Regret Minimization |

---

## Type → Framework Defaults

| Decision Type | Preferred Depth | Default Framework |
|---------------|----------------|------------------|
| Strategic | Full analysis, surface long-term effects | MECE Tree → Second-Order |
| Tactical | Structured but efficient | Decision Matrix |
| Operational | Fast, minimal friction | Pros / Cons or OODA |

---

## User Framework Preferences (Learned)

> This section is written by the agent from decision signals. Do not edit manually.

```markdown
## Preferences
(empty until learned)

## Anti-preferences (frameworks user dislikes or finds slow)
(empty until learned)

## Context overrides
(e.g., "never use weighted scoring for personal decisions")
```

---

## Framework Selection Logic

When a user asks for help deciding, follow this priority:
1. Check HOT `memory.md` for explicit framework preference
2. Match domain → see Domain Defaults above
3. Match decision type (strategic / tactical / operational) → see Type Defaults
4. If ambiguous, default to **Pros / Cons** and offer to go deeper

Always state which framework you're using and why:
```
"I'll use a Decision Matrix here — you're comparing 3 options across 4 criteria,
and your past product decisions have responded well to structured scoring."
```

---

## Confidence-Enhancing Add-ons

After the main framework, consider adding one of these if stakes are high:

| Add-on | When | Trigger |
|--------|------|---------|
| Pre-mortem | After a recommendation, before commitment | Stakes = High |
| Devil's Advocate | When user seems already decided | Confirmation bias risk |
| Second-Order Check | After tactical decision with long-term effects | Domain = Business / Strategic |

---

## Framework Decay

If a framework has not been used or referenced in 90 days, move domain/type defaults to archive and reset the preference to neutral. Do not delete — archive with timestamp.


path: decision-signals.md
content: # Decision Signals

What triggers learning, how to classify it, and where to store it.

---

## Signal Taxonomy

### Risk Profile Signals → `memory.md`

| Signal | Example Phrase | What to Record |
|--------|---------------|----------------|
| Risk-averse | "I'd rather wait for more data" | `risk: conservative` |
| Risk-tolerant | "Let's just try it and see" | `risk: experimental` |
| Loss-averse | "Worst case, what happens if this fails?" | `risk: loss-focused` |
| Regret-driven | "I don't want to look back and regret this" | `risk: regret-minimizing` |
| Speed-over-precision | "Speed matters more than getting it perfect" | `risk: bias-to-action` |
| Reversibility-first | "Can we undo this if it goes wrong?" | `risk: reversibility-sensitive` |

> Do not infer risk profile from a single decision. Wait for 3 consistent signals before writing to memory.md.

---

### Framework Preference Signals → `memory.md` + `frameworks.md`

| Signal | Example Phrase | What to Record |
|--------|---------------|----------------|
| Wants structure | "Give me a structured analysis" | `framework-pref: structured` |
| Wants brevity | "Just give me your top recommendation" | `framework-pref: direct` |
| Wants matrices | "I like scoring things" | `framework: Decision Matrix` |
| Wants thinking partner | "Walk me through the tradeoffs" | `framework-pref: dialogue` |
| Wants stress-testing | "What are the worst-case scenarios?" | `framework: Pre-mortem` |
| Wants long-term view | "What are the downstream effects?" | `framework: Second-Order Thinking` |

---

### Domain Weight Signals → `domains/{domain}.md`

| Signal | Example Phrase | What to Record |
|--------|---------------|----------------|
| Quality > speed (product) | "Ship slow, ship right" | `weight: quality > speed` |
| Speed > quality (ops) | "We need to decide today" | `weight: speed > quality` |
| Reversibility matters (tech) | "Don't paint us into a corner" | `weight: reversibility` |
| Cost-sensitivity (business) | "Budget is the hard constraint" | `weight: cost-constrained` |
| User-centric (product) | "The user always breaks the tie" | `weight: user-first` |

---

### Outcome Feedback Signals → `reversals.md` or decision record

| Signal | Example Phrase | What to Record |
|--------|---------------|----------------|
| Confirmed good | "That was the right call" / "Glad we did that" | Append `outcome: good` to decision record |
| Confirmed bad | "That was a mistake" / "We should not have done that" | Append `outcome: bad`, trigger retrospective |
| Partial | "Mostly right, but we underestimated X" | Append `outcome: partial`, note specific miss |
| Regret | "In hindsight, we should have..." | Log lesson to `reversals.md` |

---

## What Does NOT Trigger Learning

- **Silence** — not a signal of approval or agreement
- **Hypotheticals** — "what if we had done X" does not update risk profile
- **Single-instance decisions** — one choice under unusual constraint is not a preference
- **Third-party preferences** — "my manager thinks X" is not the user's preference
- **Emotional expressions** — "I hate this situation" is not a risk signal
- **Group chat patterns** — do not infer from decisions made in team contexts

---

## Confidence Level Tagging

Every decision analysis must be tagged with a confidence level. Apply automatically:

| Level | Label | When to Use |
|-------|-------|-------------|
| 🟢 | **High** | Sufficient context, clear domain match, user has stated key constraints |
| 🟡 | **Medium** | Assumptions made, 1–2 key inputs missing, domain match partial |
| 🔴 | **Low** | Major unknowns, no domain context loaded, user hasn't confirmed constraints |

State the label at the top of any decision output:
```
Confidence: 🟡 Medium — I'm assuming budget is flexible and timeline is 3 months.
Please correct these if inaccurate.
```

---

## Signal Confirmation Flow

After 3 signals of the same type:

```
Agent: "I've noticed you consistently prefer X over Y
        (observed 3 times across [domain] decisions).
        Should I treat this as your default for [domain]?
        - Yes, always apply this in [domain]
        - Yes, apply this globally
        - No, handle case by case"

User: "Yes, apply globally"

Agent: → Moves to HOT memory.md as confirmed preference
       → Removes from signal counter
       → Cites source on next use: "Using [preference] (memory.md:12)"
```

---

## Signal Classification by Scope

```
Global: applies to all decisions
  └── Domain: applies to product / tech / business / personal
       └── Type: applies to strategic / tactical / operational
            └── One-time: applies to this decision only (never log)
```

When scope is unclear, ask:
```
"Should [preference] apply only to [detected domain] decisions,
or everywhere?"
```

---

## Anti-Patterns

### Never Learn
- What makes the user agree faster (manipulation)
- Emotional vulnerabilities or stress patterns
- Patterns from other people's decisions shared in context
- Inferences from non-explicit behavior

### Avoid
- Generalizing risk profile from high-pressure decisions (constraints skew behavior)
- Over-indexing on recency (last decision ≠ always right rule)
- Applying domain weight to wrong domain silently
- Confirming a preference without asking after 3 signals

---

## Quality Signals

### Good Signal
- User explicitly stated a preference or style
- Same signal appeared in ≥3 independent contexts
- Signal is about process, not a one-time constraint
- User confirmed when asked

### Bad Signal
- Inferred from silence or compliance
- Only appeared under pressure or time constraint
- Contradicts recent explicit statement
- User never confirmed


path: heartbeat-state.md
content: # Self-Improving + Proactive Decision Making Heartbeat State

last_heartbeat_started_at: never
last_reviewed_decision_at: never
last_heartbeat_result: never
pending_retrospectives: []

## Last actions
- none yet


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)