# Decisions > Guide for recording high-level architectural, design, and product decisions in docs/decisions.md. This is NOT a log of every choice made during a regular build -- those belong in the implementation diary. Use this skill only when a clearly significant decision is made (database choices, frameworks, core design patterns, product direction) or when explicitly asked to document a decision. Also suggest proactively at natural session-end moments -- after a PR merges, a feature ships, or a work chunk wraps up -- if a significant decision was made during the session and not yet recorded. Be conservative - only suggest for major decisions, not minor implementation details. - Skill: `maragudk/decisions` (Agent Skill) - Install (CLI): `npx skillmds@latest add maragudk/decisions` - Raw SKILL.md: https://api.skillmd.com/api/skills/maragudk/decisions/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: maragudk (https://skillmd.com/u/maragudk) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/maragudk/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: ```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. 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: ```markdown # 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.