The missing layer in the AI agent stack. Teach your agent how you decide. Generates a portable DECISION.md from research-backed preference elicitation.
SaferSkills independently audited decision (Agent Skill) and scored it 83/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 4 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 4 flagged
The text {match} tells the agent to skip the normal "ask the user first" gate. Used adversarially it removes the human-in-the-loop check before destructive or sensitive actions, turning a normally-gated agent into a fire-and-forget executor.
The text {match} tells the agent to skip the normal "ask the user first" gate. Used adversarially it removes the human-in-the-loop check before destructive or sensitive actions, turning a normally-gated agent into a fire-and-forget executor.
The text {match} tells the agent to skip the normal "ask the user first" gate. Used adversarially it removes the human-in-the-loop check before destructive or sensitive actions, turning a normally-gated agent into a fire-and-forget executor.
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
The missing layer in the AI agent stack.
SOUL.md tells your agent who it is. SKILL.md tells it what it can do. DECISION.md tells it how to choose.
your-agent/
├── SOUL.md ← Who your agent is (personality, voice, boundaries)
├── STYLE.md ← How your agent communicates
├── SKILL.md ← What your agent can do (procedures, capabilities)
├── MEMORY.md ← What your agent remembers
├── AGENTS.md ← Project-specific rules and constraints
└── DECISION.md ← How your agent chooses under uncertainty ✨ NEWAI agents are getting incredibly capable. But when your agent faces a tradeoff — speed vs. thoroughness, cost vs. quality, risk vs. reward, ask you vs. just act — it has no framework for choosing.
It either defaults to generic behavior, or it interrupts you for every decision.
| Layer | What it defines | Exists? |
|---|---|---|
| Identity | Who the agent is | ✅ SOUL.md |
| Rules | Project constraints | ✅ AGENTS.md |
| Skills | What it can do | ✅ SKILL.md |
| Judgment | How it chooses | ❌ Nothing — until now |
This isn't a future problem. Right now, today, your agent doesn't know whether to book the cheap flight or the direct one. Whether to send that email immediately or save it as a draft for your review. Whether 70% confidence is enough to act, or it should ask you first. A clear threshold like "act without asking if cost < $50 and reversible" would change how it operates in every session.
As agents become more autonomous, the judgment gap becomes the bottleneck.
| Scenario | Soul Document | SOUL.md | DECISION.md |
|---|---|---|---|
| "Should my agent be honest?" | ✅ | — | — |
| "Should it sound casual or formal?" | — | ✅ | — |
| "Book the cheap flight or the direct one?" | ❌ | ❌ | ✅ |
| "Accept this meeting or protect my focus time?" | ❌ | ❌ | ✅ |
| "Push back when I'm overcommitting?" | ❌ | ❌ | ✅ |
| "70% confident — act or ask me?" | ❌ | ❌ | ✅ |
Anthropic's model specification defines Claude's universal values, safety principles, and honesty norms. It's comprehensive about who Claude is. But it repeatedly says "use good judgment" without defining what good judgment looks like for you. A risk-tolerant startup founder and a risk-averse accountant receive the same generic judgment defaults.
The soul document gave agents a conscience. SOUL.md gave them personality. DECISION.md gives them judgment.
Read the full analysis: docs/soul-document-positioning.md
A portable, human-readable markdown file that codifies your personal decision-making philosophy. It teaches your AI agent how you think — your risk tolerance, your tradeoff priorities, when to act autonomously vs. when to ask, what biases to watch out for, and how to handle decisions across different domains.
This repository defines the open DECISION.md format: the template, examples, elicitation questions, validation guidance, and integration notes. DecisionOS is one implementation of that format.
The most important section is the one most people wouldn't think to write: Anti-Patterns — documenting the things you do wrong. Your agent doesn't need to know your strengths. It needs to catch your weaknesses: the anchoring, the sunk cost reasoning, the overcommitting, the anxiety-driven over-research. Document your bugs, not just your features.
DECISION.md.# DECISION.md — Sarah's Decision Framework
## Meta
- Format version: 0.2.0
- Last updated: 2026-03-21
- Source: Manual
## Decision Identity
Bias-to-action generalist who values learning over optimization.
Comfortable with calculated risk in career and creative domains,
conservative with financial and health decisions. Would rather
make a fast reversible mistake than deliberate endlessly.
## Risk Profile
- Overall: Moderate-Aggressive
- Career: Aggressive — willing to take asymmetric bets
- Financial: Conservative — never risk >5% on a single position
- Health: Ultra-conservative — always consult a professional
- Creative: Aggressive — try weird things, fail fast
## Autonomy Rules
- Act without asking if: cost < $50, reversible, low stakes
- Always ask if: involves other people, irreversible, cost > $500
- Escalation: Any legal, medical, or financial commitment
## Decision Speed
- Default: Bias-to-action
- Reversible decisions: Decide in <5 minutes
- Irreversible decisions: Sleep on it, minimum 24 hours
- Tripwire: If deliberating >30 min on a reversible decision, just decide
## Tradeoff Hierarchy
When values conflict, prioritize in this order:
1. Integrity / keeping commitments
2. Learning and growth
3. Speed and momentum
4. Financial optimization
5. Social harmony
## Kill Criteria Defaults
- Review cadence: Monthly
- Default walk-away test: "Would I start this today, knowing what I know now?"
- Sunk cost override: Always active — past investment is irrelevant
## Calibration Profile
- Overconfident about: Time estimates (multiply by 1.5x), social predictions
- Underconfident about: Technical ability, creative work
- Debiasing: Always get a second data point before committing to a number
## Anti-Patterns
Things I do wrong — catch me when you see these:
- "I say yes to too many things" → Push back on new commitments
- "I anchor on the first number I see" → Always seek a second reference
- "I avoid difficult conversations" → Flag when I'm procrastinating on people issues
- "I over-research when I'm anxious" → Name it and nudge me to decide
## Domain Rules
### Work
- Default to async communication
- Protect deep work blocks — decline meetings during focus time
- When in doubt, ship and iterate
### Personal
- Prioritize relationships over productivity
- Don't optimize leisure — spontaneity matters
### Financial
- Never make investment decisions after 10pm
- Always wait 48 hours on purchases over $500
## Meta-Rules
- When in doubt: Bias toward action
- Confidence threshold for autonomous action: 85%
- Update frequency: Re-evaluate quarterly or after major life changes| Good | Bad |
|---|---|
| "Act without asking if cost < $50 and reversible" | "Use your best judgment" |
| "I anchor on first numbers — always seek a second data point" | "I try to be rational" |
| "Financial: Conservative. Never risk >5% on a single position" | "I'm moderate with money" |
| "If deliberating >30 min on a reversible decision, just decide" | "I like to think things through" |
| "Career: Aggressive — willing to take asymmetric bets on learning" | "I'm open to opportunities" |
| "I say yes to too many things — push back on new commitments" | "I value helping others" |
| "Multiply my time estimates by 1.5x" | "I'm sometimes overconfident" |
| "When in doubt, ship and iterate" | "I prefer action" |
The test: your agent should be able to make a decision you'd agree with, without asking you. If it can't predict which way you'd lean on a new tradeoff, the DECISION.md is too vague.
Key principles:
A DECISION.md isn't a one-time personality quiz — it's a living calibration system. Each time your agent makes a decision using your profile, you can verify whether it got it right. Over time, this feedback loop tightens:
The calibration profile tracks where you're overconfident and underconfident — and updates as you do. This is the compounding advantage: every decision your agent makes becomes training data for better future decisions. The profile doesn't just describe how you decide today — it evolves into the most accurate model of your judgment that exists.
This is what separates a structured elicitation from a conversation with a chatbot. A chat generates a snapshot. DECISION.md generates a trajectory.
No profile can anticipate every decision. When your agent hits a tradeoff that isn't covered — the cucumbers aren't fresh, should it buy them anyway? — instead of guessing or interrupting you blindly, the agent:
Every gap becomes a learning opportunity. Every resolved gap makes the profile more complete. Over months, the gaps get rarer and the agent gets closer to deciding exactly how you would.
Full protocol specification: docs/specification.md
Visit [decisionos.app](https://decisionos.app) — 35 research-backed tradeoff scenarios across 10 decision dimensions: 30 core questions plus 5 cross-dimension tradeoff questions. No account, no API key, nothing to install.
What makes the interactive experience different from just chatting with an LLM:
Copy the DECISION.md.template and fill it in manually. The sections:
Drop your DECISION.md into a Claude Project, or paste it into custom instructions.
Place it in your soul folder alongside SOUL.md:
.soul/
├── SOUL.md
├── STYLE.md
├── SKILL.md
└── DECISION.mdPlace it in your project root alongside AGENTS.md:
your-project/
├── AGENTS.md
├── DECISION.md
└── ...Paste it into the system prompt or custom instructions of any AI tool.
Include it as context in your agent's initialization prompt.
DECISION.md isn't a personality quiz. Every component is grounded in decision science research that has been validated across decades of study.
The elicitation mechanic — pairwise comparison — comes from conjoint analysis (Luce & Tukey, 1964), the gold standard methodology in marketing, healthcare, and policy research for understanding how people actually make tradeoffs. When you're forced to choose between two options, you reveal preferences you can't articulate when asked directly. This is why we don't ask "how risk-tolerant are you on a scale of 1-10" — we present scenarios that force tradeoff behavior.
Response time as a heuristic signal is inspired by the Drift-Diffusion Model (Ratcliff, 1978), which demonstrates that response time and choice are jointly informative about decision difficulty. We use response time as a practical design heuristic — fast responses likely indicate strong preferences, slow responses suggest genuine value conflicts — to enrich the profile. The questions that took you longest reveal exactly where you need explicit rules.
The "resulting" framework — separating decision quality from outcome quality — comes directly from Annie Duke's work (Thinking in Bets, 2018). This is why the stress test and tracking features score process and outcome independently. A good decision can have a bad outcome due to luck.
Kill criteria and pre-commitment draw on Duke's Quit (2022) and Katy Milkman's How to Change (2021). Setting specific, observable benchmarks before you're emotionally invested is one of the most effective debiasing techniques in the literature.
The calibration profile follows Philip Tetlock's superforecasting methodology (Superforecasting, 2015). His Good Judgment Project demonstrated that forecasting accuracy improves by up to 60% with training — and that the core of good forecasting is knowing where you're overconfident and where you're underconfident.
Anti-patterns map to the cognitive bias literature (Kahneman, Thinking, Fast and Slow, 2011; Tversky & Kahneman, 1974). Anchoring, sunk cost, confirmation bias, planning fallacy — these are predictable, documented patterns. Documenting your specific biases lets the agent actively counteract them.
| Component | Research Foundation |
|---|---|
| Binary tradeoffs | Conjoint analysis / pairwise comparison (Luce & Tukey, 1964) |
| 3-layer questioning | PAPRIKA method (Hansen & Ombler, 2008) |
| Response time tracking | Drift-Diffusion Model (Ratcliff, 1978) |
| Risk profiling | Prospect Theory (Kahneman & Tversky, 1979) |
| Kill criteria | Pre-commitment research (Duke, 2022; Milkman, 2021) |
| Calibration profile | Superforecasting (Tetlock, 2015) |
| Anti-patterns | Cognitive bias literature (Kahneman, 2011) |
| Process vs. outcome | "Resulting" framework (Duke, 2018) |
| Revealed preferences | Samuelson (1938); behavioral economics |
| Mental time travel | Hershfield (2023) |
Full research framework with all citations: docs/research.md
decision/
├── README.md ← You're here
├── DECISION.md.template ← Blank template to fill in
├── examples/
│ ├── startup-founder.md ← Example: risk-tolerant founder
│ ├── conservative-exec.md ← Example: careful executive
│ ├── creative-freelancer.md ← Example: creative professional
│ ├── new-grad.md ← Example: early career
│ └── structured-profile.json ← Example structured profile
├── docs/
│ ├── research.md ← Full research framework with citations
│ ├── soul-document-positioning.md ← Why DECISION.md completes the stack
│ ├── specification.md ← The DECISION.md format specification
│ ├── integration-guide.md ← How to use with different platforms
│ ├── behavior-demo.md ← Before/after agent behavior demo
│ └── validation.md ← Validation guidance for implementers
├── elicitation/
│ ├── seed-questions.md ← 35 questions across 10 dimensions
│ ├── system-prompts/ ← Claude API prompts for adaptive questioning
│ └── dimensions.md ← The 10 decision dimensions we elicit
├── evals/
│ └── behavior-cases.json ← Minimal scenarios for before/after testing
├── schemas/
│ └── decision.schema.json ← Machine-readable structured profile schema
├── scripts/
│ ├── lint-decision-md.mjs ← Dependency-free Markdown profile linter
│ └── validate-structured-profile.mjs ← Dependency-free structured profile validator
├── .github/
│ └── ISSUE_TEMPLATE/ ← Issue templates for examples, integrations, and spec fixes
├── CODE_OF_CONDUCT.md ← Community participation guidelines
├── CONTRIBUTING.md ← How to contribute examples, docs, and integrations
└── CHANGELOG.md ← Version historyDECISION.md isn't just for individuals. Any entity that has an AI agent making decisions on its behalf needs a judgment layer.
Teams can share a DECISION.md: an engineering team's deployment risk tolerance, a support team's refund thresholds, a marketing team's spend approval limits.
Products can ship with a default DECISION.md that defines how their AI features behave — and let customers override it. A customer support bot's escalation rules. A scheduling assistant's booking preferences. A procurement agent's approval thresholds.
Organizations can layer DECISION.md files: the product sets sensible defaults, the company sets compliance boundaries, and individual users customize within those boundaries. Rules inherit downward; the higher layer wins on conflicts.
Product DECISION.md → Default behavior for all users
↓ overridden by
Org DECISION.md → Company compliance, risk tolerance, approval limits
↓ overridden by
User DECISION.md → Individual preferences (where org permits)This means every B2B application with AI features could benefit from a DECISION.md — not as a nice-to-have, but as the configuration layer that determines how the AI actually behaves for each customer.
Full specification for organizational DECISION.md: docs/specification.md
We're building an open standard. Contributions welcome:
Is this different from SOUL.md? Yes. SOUL.md defines personality — voice, tone, expertise, boundaries. DECISION.md defines judgment — how to choose when facing tradeoffs, uncertainty, and competing priorities. They're complementary, not competing.
How many questions do I need to answer? The interactive experience has 35 curated questions: 30 core questions covering 10 dimensions, plus 5 cross-dimension tradeoff questions. You can stop and download at any point — even after 3 questions, you'll have a useful DECISION.md. It's a living document that gets more precise the more you refine it.
Does it work with models other than Claude? Yes. DECISION.md is plain markdown. It works with any LLM that can read a system prompt: Claude, GPT, Gemini, Llama, Mistral, or any agent framework.
How often should I update it? Quarterly, or after major life changes (new job, new relationship, big move). Your decision-making philosophy evolves — your DECISION.md should too.
Is my data private? The core experience runs entirely in your browser with no backend. Your responses are stored locally on your device and your DECISION.md is generated client-side. If you optionally connect a Claude API key for adaptive questioning, your responses are sent to Anthropic's API under their standard privacy policy — but never to our servers.
Should I commit my personal DECISION.md to a public repo? Usually no. A DECISION.md can reveal sensitive information about your risk tolerance, finances, relationships, health boundaries, and professional preferences. Share anonymized examples when contributing publicly, and keep personal or organization-specific files private unless you deliberately want them public.
Built on the shoulders of:
MIT — use it, fork it, build on it.
"There are only two things that determine how your life turns out. One is luck, which we don't have any control over. And second, the quality of your decisions." — Annie Duke
Teach your AI agent how you think.
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.