Decide

## Architecture

Decision state lives in `~/decide/`. If that folder is missing or empty, run `setup.md`.

```text
~/decide/
├── memory.md        # Durable decision rules, approval boundaries, and confirmed defaults
├── decisions.md     # Major decisions with question, components, chosen option, and outcome
└── domains/         # Domain-specific decision components, overrides, and exceptions
```

## When to Use

Use when the agent faces a consequential choice that can change architecture, workflow, cost, publish behavior, vendor selection, or long-term project direction.

This skill is for branching decisions, not for generic preferences or execution lessons. It should stay compatible with `self-improving`: `self-improving` learns how to work better, while `decide` learns how to choose safely when the choice has lasting consequences.

## Quick Reference

| Topic | File |
|-------|------|
| Setup guide | `setup.md` |
| Memory template | `memory-template.md` |
| Migration guide | `migration.md` |
| Decision components | `components.md` |
| Confidence calibration | `confidence.md` |
| Exceptions and always-ask cases | `exceptions.md` |

Use those files as a decision safety stack: first know the structure, then calibrate confidence, then verify exceptions before reusing any past choice.

## Decision Workflow

1. Frame the decision as a real question, not as a vague feeling.
2. Gather the components that materially affect the answer.
3. Read `~/decide/memory.md`, then the smallest relevant file in `~/decide/domains/`, then check `~/decide/decisions.md` for a materially similar record.
4. Reuse a past choice only if the question, the key components, and the exception boundaries still line up.
5. If anything important is missing or changed, ask first and log the answer once the human decides.

## Core Rules

### 1. Default Conservative on Consequential Choices
- Frameworks, architectures, migrations, vendors, publish paths, spending, and irreversible branches should default to asking the human.
- Safer failure means asking one question too many, not silently picking the wrong branch.
- A recommendation is good; an unvalidated autonomous choice is not.

### 2. A Decision Requires Components, Not Vibes
- Every major decision should be framed as a question plus the components that materially affect the answer.
- Components can include product surface, client type, reversibility, budget, timeline, team size, project constraints, and long-term maintenance cost.
- If the needed components are missing, the decision is not ready for autonomy.

### 3. Reuse Only When the Context Materially Matches
- A stored rule is reusable only when the question and the key components match closely enough to make the same choice still rational.
- Matching one signal is not enough. "Same framework choice" is weak if client, surface, constraints, or risk changed.
- If there is any serious mismatch, ask first.
- Exceptions beat defaults. A confirmed default is still invalid when a domain override or high-stakes exception changes the branch.

### 4. Promote Patterns Only After Human Confirmation
- Repeatedly seeing the same decision in the same context makes a candidate rule, not an autonomous permission.
- After enough similar decisions, ask: "When this is true plus this plus this, should I default to X?"
- Only promote the pattern after explicit confirmation.

### 5. Log the Full Decision, Not Just the Outcome
- Store the question, components, chosen option, rationale, confidence, and outcome.
- A naked note like "use React Native" is too weak; it must say when and why.
- Good logs prevent false autonomy later.

### 6. Keep Workspace Routing Non-Destructive
- Use setup to add small AGENTS and SOUL snippets that force decision retrieval before major choices.
- Show the exact snippet and wait for explicit approval before writing any workspace file.
- The routing must make it hard to skip the decision log when a consequential branch appears.

### 7. Never Let Decision Memory Shadow Other Skills
- Use `self-improving` for execution quality, corrections, and reusable work habits.
- Use `escalate` for ask-vs-act boundaries across actions broadly.
- Use `decide` only for major branching choices where the structure of the context determines the answer.

## Common Traps

These failures usually come from pattern-matching too early or from collapsing a major decision into a shallow preference.

| Trap | Why It Fails | Better Move |
|------|--------------|-------------|
| Reusing a rule because the question sounds similar | Important components may have changed | Compare question plus key components before reusing |
| Treating one-off emergency choices as defaults | Stress decisions rarely generalize well | Log them, but keep them unconfirmed unless repeated |
| Autodeciding after reading only memory.md | Exceptions and domain overrides get missed | List domains, read the smallest relevant override, then check decisions |
| Turning execution preferences into decision rules | Blurs compatibility with `self-improving` | Keep major branching choices in `decide`, workflow lessons elsewhere |
| Applying a framework or vendor rule across clients blindly | Client and surface often change the optimal answer | Ask again when client, platform, scope, or constraints differ |

## Data Storage

Local state lives in `~/decide/`:

- durable decision rules, approval boundaries, and confirmed defaults in `~/decide/memory.md`
- major decision records in `~/decide/decisions.md`
- domain-specific component models, overrides, and exceptions in `~/decide/domains/`

The packaged guides `components.md`, `confidence.md`, and `exceptions.md` stay in the skill itself and act as references, not as the user's live memory.

## Security & Privacy

- This skill stores local decision notes in `~/decide/`.
- It may read workspace steering files such as the AGENTS file and SOUL file so that decision retrieval happens before major choices.
- It may suggest small non-destructive edits to those files during setup, but it must show the snippet and wait for explicit approval before any write.
- It should prefer asking to guessing whenever a decision can affect money, production, publishing, deletion, contracts, or long-term architecture.
- It never modifies its own `SKILL.md`.

## Related Skills
Install with `clawhub install <slug>` if user confirms:

- `escalate` - Control broad ask-vs-act boundaries around risky actions
- `self-improving` - Learn execution lessons without conflating them with decision rules
- `memory` - Keep broader long-term context and user continuity
- `proactivity` - Push the next step while respecting confirmed decision defaults

## Feedback

- If useful: `clawhub star decide`
- Stay updated: `clawhub sync`