Record architectural decisions with context, alternatives, and rationale in docs/decisions.md.
npx skills add https://github.com/maragudk/skills --skill decisions
Please help me install this Agent Skill. Skill: decisions Source: https://github.com/maragudk/skills/tree/main/decisions Command: npx skills add https://github.com/maragudk/skills --skill decisions
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.
docs/decisions.md using a standardized format, including context, alternatives, and rationale.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:
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.
High-intent search queries and answers about installing and using this skill.
Document architectural decisions by recording them in a structured format within docs/decisions.md, capturing context, alternatives considered, tradeoffs, rationale, and the final decision. This creates a chronological, searchable record that preserves design reasoning and supports future onboarding and governance.
Each decision entry must include title, description, context (the problem and constraints), alternatives evaluated, tradeoffs analyzed, rationale for the choice, date, and the final decision. This standardized format ensures completeness and makes decisions retrievable for downstream reference.
Log decisions that materially affect long-term architecture—such as database systems, frameworks, core design patterns, and major structural changes. Document explicit requests to record a decision or proactively log when a choice creates dependencies that influence future development.
Yes, decision entries adapt in detail—from brief summaries for minor choices to comprehensive analyses for complex tradeoffs affecting multiple systems. The format remains consistent while depth varies based on decision significance and complexity.
A chronological decisions log preserves the reasoning, context, and alternatives behind architectural choices, preventing institutional knowledge from leaving with team members. New contributors can understand past decisions without reconstructing the thought process.
Record the migration decision by documenting the original database choice (context and rationale), the trigger for reconsideration, alternatives evaluated for the new system, tradeoffs of the migration, and the final decision. This maintains visibility into why the original choice was made and why it changed.
jeremyaryCreate structured Markdown Architecture Decision Records in the plans/adr/ directory.
controlaltnerdCreate, review, and update Architecture Decision Records with status lifecycle management.
ar4mirezGenerate structured Markdown files documenting Git-based work patterns, decisions, and project state.
igij01Document architectural decisions with Architecture Decision Records using standard templates and an organized index.