skill create-adr

2026-04-29 00:38:11 +07:00
parent c616fcf037
commit fac874e747
4 changed files with 96 additions and 2 deletions
@@ -0,0 +1,89 @@
+---
+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.
@@ -0,0 +1,3 @@
+interface:
+  display_name: "Create ADR"
+  short_description: "Record a new architecture decision for durable repo changes"