# Decision Log

> Document decisions with context, alternatives considered, and rationale

- Skill: `bromso/decision-log` (Agent Skill)
- Install (CLI): `npx skillmds@latest add bromso/decision-log`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bromso/decision-log/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: bromso (https://skillmd.com/u/bromso)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bromso/decision-log

---


# Decision Log

Document a decision for "$ARGUMENTS" with full context, alternatives considered, and rationale. Capture the decision question, constraints, options evaluated, final choice, and conditions for revisiting.

## Prerequisites

None — this is a utility skill. It can be run at any time, with or without existing project artifacts.

If `.project/$ARGUMENTS/` exists, read any available artifacts for context. If it does not exist, proceed based on information the user provides.

## Process

1. **Gather context:**
   - If `.project/$ARGUMENTS/decision-log.md` exists, read it for previous decisions and established patterns
   - If `.project/$ARGUMENTS/` exists, read available artifacts for project scope and constraints
   - Understand what decision needs to be made — ask the user if not clear

2. **Capture the decision question clearly:**
   - Frame the decision as a specific question: "Should we X or Y?" or "How should we approach Z?"
   - A vague decision question leads to a vague decision — sharpen it until it is precise
   - Note the urgency: is this blocking work? can it wait for more information?
   - Identify who needs to be involved in making this decision

3. **Document context and constraints:**
   - **Why is this decision needed now?** — what triggered it (new requirement, technical discovery, timeline pressure, team feedback)
   - **What constraints apply?** — budget, timeline, technical limitations, team skills, organizational policies, compliance requirements
   - **What assumptions are we making?** — state them explicitly so they can be challenged
   - **What do we already know?** — relevant data, prior experience, industry standards, previous decisions that constrain this one
   - **What don't we know?** — gaps in information, uncertainties that affect the decision

4. **List alternatives considered (minimum 2-3):**
   - Always include at least 2-3 genuine alternatives — if there is only one option, the decision is already made
   - Include "do nothing" or "defer" as an explicit option when applicable
   - For each alternative, provide a brief description of what it entails
   - Ensure alternatives are meaningfully different, not just minor variations

5. **Evaluate each alternative with pros and cons:**
   - For each alternative, list:
     - **Pros** — benefits, advantages, what it enables
     - **Cons** — drawbacks, risks, what it costs or constrains
     - **Effort** — rough estimate of implementation cost (time, money, complexity)
     - **Reversibility** — how easy is it to change course later? (one-way door vs. two-way door)
   - Use consistent evaluation criteria across all alternatives for fair comparison
   - Note any strong opinions or preferences from team members or stakeholders

6. **Record the final decision and rationale:**
   - State the decision clearly in one sentence
   - Explain why this option was chosen over the others — what tipped the balance?
   - Acknowledge trade-offs: what are we giving up with this choice?
   - If the decision was contentious, note dissenting views respectfully
   - Record the decision-making method used (consensus, leader decides, majority vote, delegation)

7. **Note who made or approved the decision and when:**
   - **Decision maker(s)** — who had the final say
   - **Consulted** — who provided input
   - **Informed** — who needs to know about this decision
   - **Date** — when the decision was made
   - **Effective date** — when the decision takes effect (if different from decision date)

8. **Define review and revisit conditions:**
   - Under what circumstances should this decision be reconsidered?
   - Examples: "If X assumption proves wrong," "If costs exceed Y," "After Z months of experience," "If the team grows beyond N people"
   - Set a review date if applicable (e.g., "Revisit in 3 months")
   - Note any one-way-door aspects: after what point is this decision effectively irreversible?

9. **Tag with relevant area:**
   - Categorize the decision: architecture, process, product, team, tooling, vendor, security, compliance, or other relevant area
   - Tags help when searching for related decisions later

10. **Write the artifact** — append to `.project/$ARGUMENTS/decision-log.md`:
    - Use a numbered decision format: `## Decision [N]: [Decision Title]`
    - **Date** — when the decision was made
    - **Status** — decided, superseded, or under review
    - **Area** — category tag
    - **Question** — the decision question
    - **Context** — constraints and background
    - **Alternatives Considered** — each option with pros, cons, effort, and reversibility
    - **Decision** — the chosen option and rationale
    - **Decision Makers** — who decided, consulted, and informed
    - **Revisit Conditions** — when to reconsider

## Output

Decision appended to `.project/$ARGUMENTS/decision-log.md`. Present a summary highlighting:
- Decision question and chosen option
- Key rationale (why this over alternatives)
- Main trade-off acknowledged
- Revisit conditions