Decisions

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:

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

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

Example (brief):

## 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):

## 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.

Alternatives considered:
- PostgreSQL: More features and better for high concurrency, but adds operational complexity
- SQLite: Simpler deployment, embedded database, sufficient performance for our scale

Tradeoffs: SQLite has limitations with high write concurrency and some advanced features, but offers zero-configuration deployment and excellent read performance. Given our expected load and preference for operational simplicity, these tradeoffs favor SQLite.

Decision: Use SQLite with WAL mode enabled for improved concurrency. We can migrate to PostgreSQL later if scaling needs change.

Step 4: Write to File

1. Check if docs/ directory exists; create it if needed
2. Check if docs/decisions.md exists:
   • If not, create it with this header:

     # Project Decisions
     
     This document records significant architectural and design decisions made throughout the project's development.
     

   • If it exists, read the current content
3. Append the new decision entry to the bottom of the file
4. Ensure proper spacing (blank line before the new entry)

Step 5: Confirm with User

After recording the decision, briefly confirm what was recorded. For example:

• "Recorded the decision to use SQLite in docs/decisions.md"
• "Added the routing decision to the decision log"

Proactive Suggestion Pattern

When detecting a significant architectural decision during conversation, suggest recording it:

This seems like a significant architectural decision. Would you like me to record it in docs/decisions.md?

Wait for user confirmation before recording.

Important Notes

• Always append to the bottom (chronological order from oldest to newest)
• Use today's date (YYYY-MM-DD format) for new entries
• Maintain formatting consistency with existing entries
• Don't create duplicate entries for the same decision
• Create docs/ directory if it doesn't exist
• Avoid recording trivial decisions that don't have long-term architectural, design, or product impact. The bar is high on purpose; see the scope section above.
• Don't modify old decision entries. Only edit an entry if it was created in the current session. If a previous decision is revisited or changed, record it as a new entry rather than rewriting the old one -- the decision log is a historical record.