---
name: create-adr
description: Use when a change introduces or updates a durable cross-cutting technical decision that future work in this repository must preserve, such as dependency, storage, integration, workflow, or quality-gate policy changes
---

# Create ADR

## Overview

Create a new ADR in `docs/adr/**` when the current task locks in a durable technical decision.
Do not use this for bug fixes, styling changes, routine refactors, or ordinary test additions.

## Use This Skill For

- introducing or removing a major dependency
- choosing or changing a storage strategy
- defining release, branch, or workflow policy
- changing how agents, jobs, or external tools are integrated
- adopting or tightening repository quality gates
- changing a behavior-defining contract future work must preserve

## Do Not Use This Skill For

- bug fixes
- styling-only changes
- routine refactors
- ordinary test additions
- temporary plans or execution notes

## Workflow

1. Check whether an active ADR already covers the same decision.
   - Read `docs/adr/README.md` and scan existing files under `docs/adr/`.
   - If the current change is only implementing an already-recorded decision, do not create a new ADR.
2. If the new decision changes or replaces an older ADR, create a new ADR that supersedes it.
   - Do not rewrite the meaning of an active ADR in place.
3. Find the next numeric ID under `docs/adr/`.
4. Create `docs/adr/NNNN-short-kebab-title.md`.
5. Use this template:

```md
---
type: ADR
id: "NNNN"
title: "Short decision title"
status: active
date: YYYY-MM-DD
---

## Context

What changed? Why does this decision need to exist now?

## Decision

**State the decision clearly in one or two sentences.**

## Options considered

- **Option A** (chosen): description with pros and cons
- **Option B**: description with pros and cons
- **Option C**: description with pros and cons

## Consequences

What becomes easier?
What becomes harder?
What risks were accepted?
What would trigger re-evaluation?

## Advice

Optional. Capture important external guidance or review input.
```

6. Add the new ADR to the index in `docs/adr/README.md`.
7. Commit the ADR in the same change as the implementation it documents.
8. Mention the ADR in the issue comment and PR body under `Docs/ADR`.

## Rule Of Thumb

If the decision changes how future work should be done across the repository, it probably deserves an ADR.

## Repository Rules

- Keep one decision per file.
- Name files `NNNN-short-kebab-title.md`.
- Keep the `docs/adr/README.md` index aligned with the files on disk.
- Prefer concise, durable wording over implementation detail.