Decision Log

Decision Log skill

What this skill does

Turns product decisions into structured, searchable markdown records that teams commit to git. Prevents decision churn by capturing what was decided, what was rejected, and why, in a format that is retrievable and linkable across the product org.

Works in two modes:

• Manual: PM provides decision details directly
• Agent: the decision is extracted from unstructured input (meeting notes, Slack threads, PRD drafts, discussion summaries)

How mode is determined

Mode is detected automatically from the invocation pattern.

Manual mode is active when:

• The user provides the decision details directly in their message
• Invocation follows the pattern: "log decision: [decision details]"

Agent mode is active when:

• The user pastes unstructured source material for extraction
• Invocation follows the pattern: "log decision from [source]: [paste]"
• Source type signals are present: "from slack", "from meeting notes", "from this thread", "from the transcript", "extract decision from"

When mode is ambiguous, default to agent mode if the input contains more than two sentences of unstructured text. Default to manual mode if the input is a single structured statement.

Before generating the record, always confirm the detected mode and output destination to the user in one line:

• Manual mode (DECISIONS.md): "Appending decision record to DECISIONS.md."
• Manual mode (individual file): "Creating individual decision file."
• Agent mode (DECISIONS.md): "Extracting decision from [source type] and appending to DECISIONS.md. Marking uncertain fields [NEEDS REVIEW]."
• Agent mode (individual file): "Extracting decision from [source type] and creating individual file. Marking uncertain fields [NEEDS REVIEW]."

When to activate this skill

Activate only when the input contains decision-bound language, meaning explicit signals that a choice was made or must be made between named alternatives. Required: at least one of the following must be present.

Explicit decision signals:

• "we decided", "we agreed to", "we chose", "we will go with"
• "the decision is", "going forward we", "we are not doing", "we ruled out"
• A direct request: "log this decision", "capture what we decided", "create a decision record", "preserve the rationale"
• A named trade-off request: "help me decide between X and Y and record it"

Do not activate for:

• Meeting summaries that contain no explicit decision statement
• Action item lists without a named choice between alternatives
• Preference discussions, brainstorming, or open exploration
• PRDs, specs, roadmap documents, retros, or postmortems
• Notes that describe a topic but not a resolution

If the input contains discussion that implies a decision but does not state one explicitly, ask the user to confirm the decision statement before generating a record.

Significance gate

Agent mode only. This gate does not apply in manual mode.

In agent mode, before generating a record for an extracted decision, check whether the decision meets at least one of these criteria:

• Hard to reverse without meaningful cost or delay
• Cross-functional (affects more than one team or system)
• Involves a real trade-off between named alternatives
• Will likely be revisited or questioned later
• Has compliance, regulatory, or security implications

If none apply, ask the user: "I found a decision in the source material but it may not warrant a formal log entry. Do you want to create one anyway?" Generate only after explicit confirmation.

In manual mode, the user has already made the significance judgment by invoking the skill. Generate immediately without applying this gate.

Output format

Two output modes are supported. Default is DECISIONS.md.

Default mode: DECISIONS.md

Append the new decision as a section to DECISIONS.md in the project root. If DECISIONS.md does not exist, create it with a header before appending the first entry.

DECISIONS.md header (create once, never overwrite):

# Decision Log

This file is maintained by the decision-log skill.
Reference it in your agent's project instructions file (CLAUDE.md,
AGENTS.md, or .cursor/rules) to load decisions as project context.

---

Each appended entry uses this structure:

## DL-YYYY-MM-NNN — short-slug

**decision-id:** DL-YYYY-MM-NNN
**date:** YYYY-MM-DD
**status:** accepted
**owner:** Name or role

### decision
[decision statement]

### context
[context]

### options-considered
[options]

### chosen-option
[chosen option]

### rationale
[rationale]

---

Append new entries at the bottom. Never overwrite or reformat existing entries. Never delete the header block.

NNN is a sequential counter. Scan DECISIONS.md for the highest existing DL-YYYY-MM-NNN value and increment by one. If no entries exist, start at 001.

Individual file mode

Activated by explicit invocation:

log decision (new file): [input]

Creates an individual file named DL-YYYY-MM-NNN-short-slug.md in /decisions/ if the folder exists, otherwise in the current working directory. If /decisions/ does not exist, create it before writing.

Use individual file mode when:

• The team uses git and wants per-decision diff history
• Decisions need stable URLs for linking from PRDs or tickets
• Multiple team members log decisions simultaneously

File creation rules (both modes)

Never overwrite or modify an existing entry in DECISIONS.md. Never overwrite an existing individual decision file. Never create or modify a decisions.md index file.

Section sequence (both modes)

Always produce sections in this exact sequence:

1. Header block (decision-id, date, status, owner)

2. decision (DECISIONS.md) or ## decision (individual file)

3. context or ## context

4. options-considered or ## options-considered

5. chosen-option or ## chosen-option

6. rationale or ## rationale

7. source or ## source (agent mode only)

8. supersession or ## supersession (only if status is superseded)

9. Optional extension block (commented out unless requested)

Note: DECISIONS.md uses ### for section headers to avoid conflicting with the ## entry header. Individual files use ## for section headers.

Header block format (both modes)

Always use bold field syntax. Do not use YAML frontmatter with --- delimiters. Do not use tables.

decision-id: DL-YYYY-MM-NNN date: YYYY-MM-DD status: accepted owner: Name or role

Mandatory fields (populate all eight)

decision-id Generate from date and a short slug derived from the decision statement. Format: DL-YYYY-MM-NNN.

decision-statement One sentence only. The decision itself, not the background. Start with a verb. Example: "Use Auth0 for authentication instead of building in-house."

status One of: proposed / accepted / superseded / deprecated. Default to accepted if the source clearly describes a past decision. Use proposed if the decision is still open. Do not infer superseded or deprecated unless the source explicitly states it. When status is superseded, the superseded-by field becomes mandatory.

context Two to five sentences. What forced this decision. The constraint, event, or problem that made standing still not an option. Populate only from information present in the source material or provided by the user. If context is thin or absent, write what can be confirmed and mark the field [NEEDS REVIEW - context inferred from limited source material]. Never invent a business justification that was not stated.

options-considered A list with at least two entries. Each entry gets a short label and one sentence description. If source material only surfaces one option, add "Alternative not captured in source" as the second entry and mark options-considered [NEEDS REVIEW].

chosen-option The selected option by label. Informal or free-form labels from source material are acceptable. One line.

rationale Why the chosen option won over the others. Most important field. If source material does not contain clear reasoning, populate what can be inferred and mark the field [NEEDS REVIEW - rationale inferred from context]. Never fabricate rationale to fill the field.

owner The person accountable for this decision. Not the full stakeholder list. If not stated in source material, mark [NEEDS REVIEW - owner not identified]. If ownership is implied but not explicitly confirmed (e.g. "led the conversation", "was driving this", "will handle it"), populate the name and add [NEEDS REVIEW - ownership implied but not explicitly confirmed]. Never drop the [NEEDS REVIEW] flag when ownership is ambiguous. Example: Mia [NEEDS REVIEW - ownership implied but not explicitly confirmed]

Agent mode additional rules

When extracting from unstructured input, add a source block after the rationale field:

source-type: meeting-notes / slack-thread / prd-draft / email / other source-date: date of the source document if identifiable source-reference: link or filename if available extraction-mode: agent

Decision signals to scan for: "we decided", "we will go with", "the decision is", "we agreed to", "we are not doing", "we ruled out", "going forward we", "we chose", "we rejected".

When multiple decisions appear in one source, produce one entry per decision with sequential NNN values. In DECISIONS.md mode, append each entry sequentially. In individual file mode, create one file per decision.

Supersession rule

When status is superseded, add: superseded-by: link or ID of the record that replaces this one superseded-date: date of supersession supersession-reason: one sentence

Handling ambiguity

• Populate what is explicit in source material first
• Infer only when the inference is unambiguous
• Mark uncertain fields [NEEDS REVIEW - reason]
• Never fabricate options or rationale
• If decision-statement cannot be derived with confidence, stop and ask the user to clarify before generating the record

Optional extension block

The template contains a commented optional section. Fields listed in order of downstream value for PM teams:

1. follow-up-actions — highest value: captures what must happen as a result of this decision, with owner and due date per action
2. assumptions — what must remain true for this decision to hold
3. risks — known risks at decision time with optional mitigation
4. linked-artifacts — links to PRD, ticket, ADR, Slack thread
5. review-date — when this decision should be revisited
6. stakeholders-informed — who was notified beyond the owner
7. regulatory-flag — boolean, marks compliance-relevant decisions
8. ai-decision-mode — human / ai-assisted / ai-recommended
9. ai-input-summary — one sentence on what AI contributed

Do not populate these unless the user requests them or source material contains clear content for them.

Output quality check before writing

Verify:

• decision-statement is one sentence and starts with a verb
• options-considered has at least two entries
• rationale is present and not a restatement of decision-statement
• status is one of the four allowed values
• owner is identified or marked [NEEDS REVIEW]
• all ambiguous fields are marked [NEEDS REVIEW], not left blank or fabricated
• in agent mode: significance gate was applied before generating
• in manual mode: significance gate skipped, user invocation is sufficient confirmation
• output mode is confirmed to the user before writing
• section headers use ### in DECISIONS.md and ## in individual files