/decision-doc
A decision record with options, tradeoffs, an owner, a first action and a review date.
Then type /decision-doc in Claude Code, or describe the task and let it pick the skill.
What you get back recorded run · 9 Oct 2026
Using /decision-doc
Build search on Postgres for now. Confidence: medium.
- Why Postgres: it's the only option that doesn't fail one of the team's hard constraints. Meilisearch would mean running a new service, which breaks "no new on-call." Algolia's ~$1,100/month is over the $500 limit, so it needs CFO sign-off.
- Sort the 41 August search tickets into typo, ingredient, filter and other. If typo complaints are the biggest group, Meilisearch becomes the better choice.
- Sam's case for Meilisearch is written up fairly as the main counterargument, alongside Maya's preference for Postgres.
CaveatOwners and due dates for the next steps are its own suggestions, flagged for checking.
Input → output from the run
Your notes
Options we talked about: 1. Postgres full-text search (tsvector + GIN index, pg_trgm for typos). No new infra. Maya prototyped it in 2 days: p95 38ms on a prod snapshot. Typo tolerance with pg_trgm is "okay, not great". Faceted counts would need hand-written queries. 2. Meilisearch self-hosted. Great typo tolerance and facets out of the box. Need to run + monitor another service and build a sync pipeline from Postgres. Sam estimates 2 weeks to production-ready. 3. Algolia (hosted). Best relevance tooling, zero ops. Quote we got: about $1,100/month at our projected volume. Finance said anything over $500/month recurring needs CFO sign-off. Constraints: launch the new search before the January "healthy eating" campaign (Jan 6). Nobody wants a new on-call rotation.
Decision record
Build on Postgres full-text search (tsvector + GIN, with pg_trgm for typos), and start logging zero-result queries now. Look at it again in February with real query data. If typo misses or facet work turn out to be the bottleneck, move to Meilisearch or Algolia then. Confidence: medium. It covers the must-haves (ingredient search, filters, the deadline, no new on-call) with the least risk. It is weakest on typo tolerance, and we don't yet know how much typo tolerance matters to users.
When to use it
Use when
Use when a person or team must choose between approaches or record a choice already made.
Skip it when
Skip it when the choice is settled and you need the build plan; product-spec turns a decision into scope.
The thinking behind itMost stalled projects are a decision nobody wrote down. Pick one option, name the owner and what would reopen it, and the team stops arguing it again.
Output contract from the skill's Output contract section
Return a concise decision record with:
- title, date, status, owner, participants;
- decision statement and deadline;
- context, constraints, and decision drivers;
- evidence and assumptions;
- options, including status quo where relevant;
- comparison and strongest argument for/against each;
- decision, confidence, and rationale;
- consequences and what is being given up;
- first action, owner, due date;
- review/expiry trigger and supersession links;
- unresolved risks or dissent.
Offer to save it only when the user requested a file or the workspace convention clearly supports one.
How it checks its own work from the instructions
- States one executable decision or explicit sequence
- Claims are sourced, measured, or labeled as assumptions
- Reversibility, cost, and downside are explicit
- Dissent and the strongest counterargument are represented fairly
Requirements what it needs
- Works in
- Codex, Claude Code, Cursor, Claude app
- Needs
- files you provide
The instructions SKILL.md · 59 lines
Instructions & references
Back to overview ↑On this page 5 sections
Decision document
Turn ambiguity into a decision that can be understood, executed, reviewed, and superseded.
Choose a mode
- Fast record: context already contains the decision and rationale; write the record.
- Facilitation: important inputs are missing or stakeholders are stuck.
- Research comparison: evidence must be gathered before choosing.
- Experiment to decide: a bounded test has positive expected value of information.
- Audit: evaluate an existing decision record or a decision that is not holding.
Classify the decision as reversible, costly to reverse, or effectively irreversible. This changes the depth and evidence burden; reversibility is not an automatic tiebreaker.
Workflow
- Extract the decision, owner, deadline, status quo, options, constraints, decision drivers, and known evidence from context.
- If a blocking input is missing, ask one focused question at a time. Do not force an interview when the record is already supportable.
- Include the status quo when it is a real option. Allow parallel or phased choices when dependencies, capacity, and order make them genuinely distinct—not as an escape from choosing.
- Evaluate options against the agreed drivers. Use weights only when they clarify the tradeoff; show sensitivity when small weight changes reverse the result.
- Distinguish facts, estimates, assumptions, preferences, and unknowns. Research time-sensitive claims from primary sources when authorized.
- If a short experiment could resolve a pivotal uncertainty, specify hypothesis, cost, duration, success rule, and the decision each outcome triggers. Otherwise decide with current evidence.
- Recommend one option or sequence. State confidence, strongest counterargument, consequences, and what would cause reconsideration.
- Name the first action, owner, due date, review trigger, and how this record supersedes or is superseded by later decisions.
Output contract
Return a concise decision record with:
- title, date, status, owner, participants;
- decision statement and deadline;
- context, constraints, and decision drivers;
- evidence and assumptions;
- options, including status quo where relevant;
- comparison and strongest argument for/against each;
- decision, confidence, and rationale;
- consequences and what is being given up;
- first action, owner, due date;
- review/expiry trigger and supersession links;
- unresolved risks or dissent.
Offer to save it only when the user requested a file or the workspace convention clearly supports one.
Verify
- The record states one executable decision or explicit sequence.
- The recommendation follows the stated drivers and evidence.
- Material claims are sourced, measured, or labeled as assumptions.
- Reversibility, implementation cost, and downside are explicit.
- An experiment is used only when its result can change the decision.
- Owner, first action, due date, and review trigger are present.
- Dissent and the strongest counterargument are represented fairly.
Put this skill to work
Learn a workflow. Take the skill with you.
Claude app, ChatGPT and ZIP download
Claude app
This workflow can run in chat using the files and context you provide. Download its complete ZIP, then upload it from Claude's Skills settings.
ChatGPT Skills
This workflow is suitable for ChatGPT Skills. ChatGPT does not document the same upload archive format as Claude, so follow its uploader instead of reusing the Claude ZIP.
Package details
- Package
- decision-doc/SKILL.md
- Author
- @tushaarmehtaa
- Added
- 22 Mar 2026
- Tags