Create Decision

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-.md where N is the next available number (counting existing files in that directory).

If this decision replaces an earlier one, run /supersede-decision 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.

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.

Useful Commands Reference

No CLI commands required. This skill operates on information provided in context and writes a Markdown file.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tomzx
• Source: tomzx/agents
• License: MIT

Install and usage instructions live in the source repository linked above.