Create Decision

---
name: create-decision
description: Record an architectural or implementation decision with context, alternatives considered, trade-offs, and consequences.
argument-hint: "[decision topic or question]"
---

# Create Decision

Records a decision made during implementation as a lightweight Architecture Decision Record (ADR).
Captures the context, the decision, alternatives considered, trade-offs, and expected consequences so future contributors understand why the code is the way it is.

## Prerequisites

- Apply the shared SDLC conventions in `skills/sdlc/references/shared.md`.
- A concrete decision that was made (or needs to be made) during implementation
- Enough context to explain the forces that shaped the decision

## Steps

1. Identify the decision: what question was answered or choice was made.
2. Describe the context: what problem exists, what constraints apply, what prompted the decision.
3. List the options that were considered (at least two, including the chosen one).
4. State the decision clearly.
5. Explain the trade-offs: what is gained and what is sacrificed.
6. Describe the consequences: what changes as a result, what follow-up is expected.
7. Save the document to `.sdlc/knowledge/decisions/` (or the project's existing ADR directory if one exists) using the filename pattern `N-<slug>.md` where `N` is the next available number (counting existing files in that directory).

If this decision replaces an earlier one, run `/supersede-decision <old> <new>` afterwards to mark the prior ADR `Superseded by [N]` and record the reverse link. Do not hand-edit the older decision's status.

## Output Format

Use the template at `skills/sdlc/templates/knowledge/decision.md` (copied to `.sdlc/templates/knowledge/decision.md` by `/initialize-sdlc-directory`; use the project's customized copy if present). Write the result to the artifact path named in the steps above.

## Outcome

If `$OUTCOME_YAML` is set, emit `verdict: approved` there per `skills/sdlc/references/shared.md` once the record is written.
In the same emission, list the artifact under `artifacts:` (`.sdlc/knowledge/decisions/N-<slug>.md`, or the project's existing ADR directory when one is used).

## Example Usage

**Scenario 1: Library choice**
Deciding between two HTTP client libraries during implementation.
Decision title: "Use httpx instead of requests for async support."
Context: the service needs to make concurrent outbound calls; `requests` blocks.
Option A (httpx): supports async/await natively, actively maintained. Con: adds a new dependency.
Option B (requests + threads): familiar but increases thread overhead.
Decision: use httpx. Consequence: all HTTP calls must use async context.

**Scenario 2: Data modeling trade-off**
Deciding whether to store computed values or recalculate on read.
Decision title: "Persist derived totals in the orders table."
Context: query load is high, recalculation is expensive.
Trade-off: gained query speed, sacrificed single source of truth (must keep totals in sync on write).

**Scenario 3: Deferring complexity**
Choosing a simple approach now and noting what was deferred.
Decision title: "Use a flat file for config instead of a database."
Consequence: revisit if config grows beyond 50 keys or requires per-user values.

## Completion Checklist

Before handing off to review, confirm:

- [ ] At least two options considered (including the chosen one), each with pros and cons
- [ ] If it replaces an earlier decision, `/supersede-decision` was run (do not hand-edit the older status)

Self-check the record against the [`review-decision` checklist](../review-decision/SKILL.md) and fix what you can, so review finds less to flag.

## Next Step

A review subagent is dispatched automatically to run `/review-decision` to audit the record for clarity, completeness, reasoning quality, and consequence coverage.