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