Log Decision

Help the user capture a Decision Record for a significant decision that is costly to change.

When the user invokes /log-decision with an argument, use $ARGUMENTS as the title. With no argument, ask for a title. When the conversation triggered this skill instead, say something like: "This looks like a significant decision. Would you like me to draft a Decision Record (DR)?" Wait for confirmation before you proceed.

Not sure yet? If the user is still exploring options, or has not settled on a direction, suggest /decide instead. That skill is a thinking partner for working through the problem before anyone documents it.

Execution steps

1. Gather information

Use AskUserQuestion for each question, and ask about one topic area at a time. Do not present every field at once. Start with the essentials. Ask about an optional field only when the user is engaged in that level of detail.

If the user has just come from a /decide session, the conversation already holds three of the fields. Those are the Context and Problem Statement, the Forces and Constraints, and the Considered Options. Confirm the key points instead of asking again, and move straight to the Decision field and to any gap.

Essentials, which are always required:

Depth, which you ask about only when the conversation has not covered it:

Metadata, which you ask about only when provenance or governance matters:

Never assume. Ask whenever something is ambiguous.

2. Determine the DR directory and the next number

1. Look for an existing DR directory in the project root, in this priority order: docs/decisions/, then adr/, then .decisions/.
2. When none of the three exists, use docs/decisions/ and create it.
3. Scan the existing files that match DR-*.md to find the highest sequence number, then use N + 1. Start at 0001 when no file exists.
4. While you scan, note any DR whose title or content looks related to the current decision. Report those to the user, so they can reference or supersede them.

3. Derive the file name

• Kebab-case the title, strip the special characters, and truncate it to roughly 50 characters.
• Use the format DR-NNNN-kebab-title.md.
• For example: DR-0003-use-postgresql-as-primary-datastore.md.

4. Write the DR file

Read the template from ${CLAUDE_SKILL_DIR}/assets/dr-template.md. Fill every section with the information you gathered. For an optional section with no content, remove the section and its <!-- This is an optional element. Feel free to remove. --> comment. Leave no placeholder text.

Include markdown links wherever they help: to the PRs or issues that motivated the decision, to external docs such as RFCs, benchmarks, and vendor pages, and to related DRs. Use a relative path for a link between DR files. Use a full web URL for every other link.

If the status is superseded, find the DR that this one supersedes. Add a "Superseded by DR-NNNN" note to its ## More Information section, and append that section when it is absent. Then reference that DR in the ## More Information section of the new file.

A DR outlives the conversation that produced it, and a reader opens it months later with none of that context. Write short sentences in the active voice, define a term that such a reader can miss at its first use, and cut filler. Keep the Y-statement shape of the Decision section, and keep every link and quoted value exactly as it is. When a plain-English writing skill such as simple-english is available, invoke it and apply its rules to the draft, before you write the file.

After you write the file, tell the user the file path and a one-line summary of the decision. Do not offer to improve the DR unless the user asks.