decisions

What problem does it solve?

This Skill ensures that significant architectural and design decisions are consistently documented, providing a clear, chronological record of choices, their rationale, and evaluated tradeoffs, preventing knowledge loss and improving project clarity and maintainability.

Core Features & Use Cases

• Structured Decision Logging: Records decisions in docs/decisions.md using a standardized format, including context, alternatives, and rationale.
• Intelligent Triggering: Proactively suggests documenting decisions when major architectural choices are made (e.g., database selection, framework adoption).
• Flexible Detail Levels: Adapts the level of detail for each entry, from brief summaries to comprehensive analyses of complex tradeoffs.
• Use Case: During a discussion, the team decides to switch from a monolithic architecture to microservices. This skill prompts the user to record this decision, then guides them in documenting the context, alternatives considered, and the rationale for the microservices choice, creating a permanent, searchable record for future reference and onboarding.

Quick Start

Example of a detailed decision entry

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.