--- name: sentenz/adr source: https://app.decimal.ai/s/sentenz-adr@1/SKILL.md source_sha256: 425381e7e4d0 --- # Architecture Decision Records (ADR) Instructions for AI agents on creating and maintaining Architecture Decision Records (ADRs) to document significant architectural and technical decisions within a project. - [1. Benefits](#1-benefits) - [2. Principles](#2-principles) - [2.1. Characteristics](#21-characteristics) - [2.2. Status Lifecycle](#22-status-lifecycle) - [3. Structure](#3-structure) - [3.1. State](#31-state) - [3.2. Context](#32-context) - [3.3. Decision](#33-decision) - [3.4. Considered](#34-considered) - [3.5. Consequences](#35-consequences) - [3.6. Implementation](#36-implementation) - [3.7. References](#37-references) - [4. Workflow](#4-workflow) - [5. Style Guide](#5-style-guide) - [6. Template](#6-template) - [6.1. ADR File Template](#61-adr-file-template) - [7. References](#7-references) ## 1. Benefits - Traceability > ADRs provide a historical record of architectural decisions, enabling teams to understand why specific choices were made, reducing the risk of revisiting resolved problems. - Knowledge Sharing > Documenting decisions and their rationale helps onboard new team members quickly and ensures shared understanding across the organization. - Accountability > Clearly identifying authors, dates, and decision status creates ownership and transparency around architectural choices. - Informed Alternatives Review > Recording considered alternatives with their pros and cons enables future reviewers to evaluate whether circumstances have changed enough to revisit a decision. - Consequence Awareness > Explicitly documenting positive and negative consequences of a decision helps teams prepare mitigations and set realistic expectations. ## 2. Principles ### 2.1. Characteristics ADRs should embody the following characteristics to maximize their value. - Atomic > Each ADR addresses one clearly scoped decision concern. A single ADR may select one option or multiple complementary options from Considered, but it must not bundle unrelated decision concerns in one record. - Immutable > Once an ADR reaches `Accepted` status, its content should not be altered retroactively. Changes in direction require a new ADR that supersedes the old one. - Concise > ADRs should be as brief as the decision complexity allows. Use bullet points, tables, and structured sections rather than long prose. - Linked > Cross-reference related ADRs, issues, pull requests, and external resources to build a navigable decision graph. ### 2.2. Status Lifecycle Each ADR moves through a defined set of statuses. - Proposed > The decision is under active discussion and has not yet been formally accepted. - Accepted > The decision has been reviewed and approved. Implementation may proceed. - Rejected > The proposal was reviewed but not accepted. The rationale for rejection must be documented in the Context or Consequences section. - Deprecated > The decision was once valid but is no longer applicable. A newer decision should be referenced. - Superseded > The decision has been replaced by a newer ADR. The superseding ADR number and link must be provided. ## 3. Structure ### 3.1. State The State section captures administrative metadata for the ADR. - Author(s) > Initials or usernames of the individuals who authored the ADR. - Date > The date the ADR was created or last meaningfully updated (ISO 8601 format: `YYYY-MM-DD`). - Status > The current lifecycle status of the ADR (see [Status Lifecycle](#22-status-lifecycle)). ### 3.2. Context The Context section describes the circumstances that necessitated the decision. - Background > Explain the problem, requirement, or situation that needs to be addressed. Provide enough background for a reader unfamiliar with the project to understand why a decision was needed. - Decision Drivers > List the key criteria, constraints, and quality attributes that will guide the decision (e.g., performance, ease of use, maintainability, cost, compliance). ### 3.3. Decision The Decision section records the decision outcome from the Considered options. The decision may take one of three forms: - Single Selection > One option from Considered is selected as the solution to the problem described in Context. - Multiple Selection > Multiple options from Considered are selected and may be complementary or interdependent, collectively forming the decision. - Deferred > No options from Considered are selected at this time. The decision is deferred until more information is available or conditions change. For each selected option, create a subsection with the option name and explain the rationale for its selection, referencing the decision drivers from Context. For deferred decisions, document the reason for deferral and the next steps to resolve it. ### 3.4. Considered The Considered section enumerates all options evaluated during the decision process. Each option may be selected (wholly or partially), combined with others, or rejected in the Decision section. - Option Description > Briefly describe each option, including a link to its official documentation or repository. - Pros > List the strengths of the option relative to the decision drivers. - Cons > List the weaknesses, limitations, or risks of the option. ### 3.5. Consequences The Consequences section captures the impact of the decision once implemented. - Positive Consequences > Describe the expected benefits and improvements resulting from the decision. - Negative Consequences > Describe known trade-offs, technical debt, or limitations introduced by the decision. - Risks > Identify any residual risks or uncertainties that remain after the decision and outline planned mitigations. ### 3.6. Implementation The Implementation section provides actionable guidance for applying the decision. - Steps > Enumerate the concrete steps required to implement the decision. - Affected Areas > Identify the repositories, modules, or systems impacted by the decision. - Validation > Describe how conformance with the decision will be verified (e.g., linting rules, CI checks, code review criteria). ### 3.7. References The References section lists all external and internal resources cited in the ADR. - Links > Include links to official documentation, related ADRs, relevant issues, pull requests, and standards. ## 4. Workflow 1. Identify Identify a significant architectural or technical decision that needs to be made or documented (e.g., choice of framework, library, pattern, toolchain, or process). 2. Issue/Merge Request Creation Create an issue or merge request in the relevant repository to propose the ADR. Use a descriptive title that follows the canonical ADR title schema (see Style Guide). 3. Number and Name Assign the next sequential three-digit number and create a descriptive kebab-case file name derived from the canonical ADR title context following the convention: ```plaintext NNN-adr-[-].md ``` Examples: - Title with scope > An `ADR on Dependency Manager for C/C++` would have the file name `015-adr-dependency-manager-c-cpp.md`. - Title without scope > An `ADR on Git Hooks Manager` would have the file name `016-adr-git-hooks-manager.md`. 4. Place Create the ADR file in the designated decisions directory: ```plaintext docs/decisions/NNN-adr-[-].md ``` 5. Draft Fill in all sections using the [ADR File Template](#61-adr-file-template). Set the status to `Proposed`. 6. Review Submit the ADR for peer review via a pull request. Address feedback and update the content as needed. 7. Accept or Reject Update the status to `Accepted` or `Rejected` once a decision is reached. Document the rationale for rejection if applicable. 8. Supersede When a decision changes, create a new ADR and set its status to `Accepted`. Update the old ADR's status to `Superseded` and add a link to the new ADR. ## 5. Style Guide - Issue/Merge Request (MR) Title Refinement > When drafting or reviewing an issue or merge request that introduces or updates an ADR, refine the issue/MR title to match the canonical ADR title schema `ADR on [for ]`. Prefer consistency between issue title, merge request title, and ADR H1 title. - `` > Should be a concise, specific technical concern, tool, or practice. - `` > Optional. Include `for ` only when it meaningfully narrows the decision applicability. - File Naming > Use the pattern `NNN-adr-[-].md` with lowercase kebab-case for the title segment. The prefix `NNN` is a zero-padded three-digit sequence number (e.g., `001`, `012`). The `-` segment is optional and must be omitted when scope is not present (do not leave a trailing dash). Derive the slug from the canonical ADR title. - Heading Levels > Use H1 (`#`) for the ADR title, H2 (`##`) for top-level sections (State, Context, Decision, Considered, etc.), and H3 (`###`) for subsections (individual options or decisions under Decision or options under Considered). Support multiple decisions by using multiple H3 subsections under Decision (e.g., 3.1, 3.2, 3.3) when applicable. - Decision Drivers > Group decision drivers under a single numbered list item (`1. Decision Drivers`). List each driver as a bullet (`-`) with a blockquote (`>`) providing a one-sentence description. - Alternatives > Each considered option should be an H3 subsection using the option's proper name. Use `- Pros` / `- Cons` with nested blockquote descriptions for each point. Not all considered options must be selected in the Decision section; some may be documented here as rejected or deferred. - Status Field > Always include exactly one of the defined statuses: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, or `Superseded`. - Superseded Link > When status is `Superseded`, append a link to the superseding ADR in the State section: ```markdown - Superseded by: [NNN-adr-new-title](NNN-adr-new-title.md) ``` - Language > Write in clear, formal English. Use present tense for the Decision section and past tense only when describing historical context. - TOC > Include a Markdown table of contents with anchor links at the top of each ADR. ## 6. Template Use this template for new ADRs. Replace all `` values with actual content. ### 6.1. ADR File Template ```markdown # NNN-ADR: [for ] Architectural Decision Records (ADR) on . - [1. State](#1-state) - [2. Context](#2-context) - [3. Decision](#3-decision) - [3.1.