decisions

Files (1)

• SKILL.md

SKILL.md (first lines)

# Decisions

## Overview

This skill maintains a chronological record of significant project decisions in `docs/decisions.md`. It captures high-level architectural, design, and product decisions, especially those involving tradeoffs, to create a permanent record of why key choices were made.

## Scope: High-Level Decisions Only

**The decisions doc is for high-level architectural, design, and product decisions. It is NOT a log of every little decision made during a regular build.**

A regular feature build involves dozens of small choices: which helper to extract, how to name a type, whether to return early, which package a function lives in, how to structure a test. None of those belong in `docs/decisions.md`. They belong in the implementation diary (see the `diary` skill), in the PR description, or nowhere at all.

The test is: **would someone six months from now need to know why this was chosen in order to understand the shape of the project?** If the answer is no, do not record it here.

Belongs in the decisions doc:
- Choosing a database, framework, or major library
- Core architectural patterns (monolith vs microservices, rendering approach, sync vs async)
- Product direction (what the project is and is not, who it is for, what it will not do)
- Fundamental design choices that constrain future work

Does NOT belong in the decisions doc:
- Implementation details of a single feature
- Naming, file layout, or code organization within a package
- Choices that could be reversed in a single PR without anyone noticing
- Anything you would only mention in a code review comment

### Common Misuses

These patterns show up in real decision logs and are all wrong:

- **Dependency bumps and version pins.** "Bump library X" or "Pin Y to version Z for compatibility" is maintenance, not a decision. Put it in the commit message or the diary.
- **Single-PR implementation details.** Encoding formats, size caps, rounding rules, error-vs-empty return conventions for one endpoint. These are choices a reviewer sees in the diff and are reversible without ceremony.
- **Progress notes disguised as decisions.** "Shipped X partially, Y deferred", "closed 4 of 6 open items", "post-review refinement of Z". These describe where the work is, not why the project is shaped the way it is. They belong in the diary.
- **Decision-per-PR cadence.** If a single day or a single PR produces several entries, the log is tracking the build rather than the architecture. Collapse them into one entry if a real decision is buried in there, otherwise drop them.

Title smell test: an entry title starting with "Bump", "Pin", "Fix", "Ship ... partial", or ending in "(post-review refinement)" is almost never a decision.

When in doubt, leave it out. A short, high-signal decisions doc is far more useful than a long one nobody reads.

## When to Use This Skill

**Proactive (Conservative):**
Suggest recording decisions only when there is a clearly significant architectural choice, such as:
- Choosing between database systems (e.g., SQLite vs PostgreSQL)
- Selecting major frameworks or libraries
- Deciding on core architectural patterns (e.g., monolith vs microservices, rendering approach)
- Making fundamental design choices that will shape the project long-term

**Do NOT proactively suggest for:**
- Minor implementation details
- Routine coding decisions made during a regular build
- Small refactoring choices
- Trivial technical choices
- Anything that fits in the implementation diary instead

A normal feature build should usually produce zero entries in the decisions doc.

**Manual:**
Record decisions when explicitly requested by the user with phrases like:
- "Record this decision"
- "Document this in the decision log"
- "Add this to decisions.md"

## Recording a Decision

### Step 1: Identify the Decision

From the conversation context, identify:
- What decision was made
- Why it was needed (context)
- What alternatives were considered (if applicable)
- Key tradeoffs evaluated (if applicable)
- Rationale for the final choice

### Step 2: Determine Detail Level

Adapt the level of detail based on decision complexity:

**Brief** (simple decisions):
- Title and 1-2 sentence summary
- Example: Choosing a well-established library

**Moderate** (typical decisions):
- Decision description
- Brief context (why it was needed)
- The choice made

**Detailed** (complex decisions):
- Decision description
- Context and motivation
- Alternatives considered
- Key tradeoffs evaluated
- Rationale for final choice

### Step 3: Format the Entry

Use this format:

```markdown
## YYYY-MM-DD: [Decision Title]

[Description paragraph(s) adapted to the complexity level]
```

Example (brief):
```markdown
## 2025-10-23: Use httprouter for HTTP routing

Chose httprouter for its simplicity and performance. It's a well-established library that fits our needs without unnecessary complexity.
```

Example (detailed):
```markdown
## 2025-10-23: Choose SQLite for primary database

After evaluating PostgreSQL and SQLite, we chose SQLite for the following reasons:

Context: Need a reliable database for the application that handles moderate traffic (< 1000 concurrent users) and simple relational data.

From maragudk/fabrik, MIT.

More from maragudk/fabrik