claw-email/.codex/skills/create-adr/SKILL.md

name, description

name	description
create-adr	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:

---
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.