docs-adr
/docs-adr
Tworzy i utrzymuje lekkie Architecture Decision Records jako pamięć decyzji czytelną dla agenta: co postanowiono, dlaczego i co odrzucono.
- Autor
- kensaurus ↗
- Repozytorium
- cursor-kenji ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 19.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 19.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Tworzy i utrzymuje lekkie Architecture Decision Records jako pamięć decyzji czytelną dla agenta: co postanowiono, dlaczego i co odrzucono.
Wyzwalacze z opisu
Oryginalny opis (EN)
Create and maintain lightweight Architecture Decision Records as agent-readable decision memory: what was decided, why, and what was rejected. Use when "record this decision", "set up ADRs", or "the agent keeps suggesting Y again".
Jak działa
- This skill vs neighbors
- How to reason
- Worked example
- Phase 0 — Set up the system (once per repo) [LOW freedom — INDEX.md + statuses]
- Phase 1 — The format (one page, hard cap) [LOW freedom — this shape]
- Phase 2 — What gets an ADR (and what does not) [HIGH freedom]
- Phase 3 — Backfill mode (existing repo) [LOW freedom — confirm list before writing]
- Phase 4 — Keep it alive [LOW freedom — supersede, do not edit Accepted]
- Definition of Done
- Self-critique before writing ADRs [LOW freedom — do not skip]
Podgląd SKILL.md
---
name: docs-adr
description: >
Create and maintain lightweight Architecture Decision Records as
agent-readable decision memory: what was decided, why, and what was
rejected. Use when "record this decision", "set up ADRs", or "the agent
keeps suggesting Y again".
license: MIT
effort: high
---
# docs-adr — Decision memory the next session can load
**Degree of freedom: MIXED — T1 is the priority.** What to record
`[HIGH freedom]`; format, supersede-not-edit, and present-backfill-first
`[LOW freedom — run exactly]`.
Install and maintain the repo's decision memory. **Code shows what was
decided; nothing shows why, or what was rejected — so every new agent
session is free to "improve" its way back to an alternative you already
ruled out.** Re-litigated decisions are the slowest form of drift. An
ADR makes the decision durable and its reversal deliberate.
## This skill vs neighbors
| Skill | Owns |
|---|---|
| **docs-adr** (this) | Why we chose X; rejected alternatives; INDEX.md |
| `plan-docs-sync` | Docs vs *what the code is* — not why |
| `handoff` | Session state for the next chat — not permanent decisions |
| `docs-writer` | Tutorials / README prose |
| `enhance-arch-boundaries` | Mechanical layering; this records the model |
| `workflow-housekeep` | Periodic index / status sweep |
| `housekeep-backlog` | Parked-work register (`BACKLOG.md`), not decisions |
## How to reason
1. **Observe** — the decision, the rejected alternative, who already tried to reverse it
2. **Interpret** — would a fresh agent "improve" back to the rejected option?
3. **Classify** — ADR / not-an-ADR (linter already enforces, routine impl)
4. **Severity** — load-bearing unusual choice first
## Worked example
> **Observe:** agent PR re-proposes Zustand; repo uses React context for
> session by choice; no ADR.
> **Interpret:** the rejection is oral memory — the next session will retry.
> **Classify:** ADR — stack choice with a rejected alternative.
> **Write:** "We use React context for session. Rejected Zustand: duplicate
> store vs server session." Present the backfill list **before** writing files.
---
## Phase 0 — Set up the system (once per repo) [LOW freedom — INDEX.md + statuses]
- `docs/adr/NNNN-short-title.md`, numbered sequentially, plus
`docs/adr/INDEX.md` — one line per ADR
(`NNNN | title | status | one-line decision`). The index is the
agent-facing surface: small enough to load every session.
- Reference the index from agent rules: *"Before proposing a change to
architecture, dependencies, conventions, or data models, read
`docs/adr/INDEX.md`; do not contradict an Accepted ADR without flagging
it explicitly to the user."*
- Statuses: **Proposed → Accepted → Superseded by NNNN / Deprecated**.
Never edit an Accepted ADR's decision — supersede it with a new one
that links back. History is the point.
---
## Phase 1 — The format (one page, hard cap) [LOW freedom — this shape]
```
# NNNN. <Decision as a verb phrase>
Status: Accepted Date: YYYY-MM-DD
## Context
2–5 sentences: the forces. What problem, what constraints.
## Decision
1–3 sentences, imperative: "We use X for Y."
## Rejected alternatives
The load-bearing section for agents. Each alternative: one line — what
it was, WHY it lost. This is what stops re-proposal.
## Consequences
2–4 sentences: what this commits us to, what it makes harder, when to
revisit.
```
No restating documentation, no tutorials, no aspirational essays. If it
exceeds a page it is two decisions or it is documentation (route to
`docs-writer`). "We tried it and it failed because…" is the highest-value
content — failure memory is exactly what a fresh session lacks.
---
## Phase 2 — What gets an ADR (and what does not) [HIGH freedom]
Write one for any decision an agent could plausibly reverse while
"helping":
- Stack and dependency choices (and the ones rejected), including
versions pinned for a reason.
- Architecture and layering (`enhance-arch-boundaries` model is ADR #1
material).
- Conventions with non-obvious rationale.
- Product / scope decisions that shape code ("no user accounts in v1 —
deliberately").
- Reversals of past attempts — the "we already tried that" archive.
**Not** ADRs: routine implementation choices, anything the linter / gate
already enforces mechanically, TODOs, meeting notes. Over-recording kills
the system as surely as under-recording.
---
## Phase 3 — Backfill mode (existing repo) [LOW freedom — confirm list before writing]
Mine implicit decisions before they are lost:
- From the code: unusual choices that look wrong but are load-bearing
(the thing every new agent "fixes" first).
- From git history / PR descriptions: reversions and migrations.
- From the user, one focused pass: "What has an agent (or a past you)
tried to change that must stay, and why?" Write those first.
Cap the backfill at decisions that still bind (typically 5–15). This is
memory, not archaeology for its own sake.
---
## Phase 4 — Keep it alive [LOW freedom — supersede, do not edit Accepted]
- New ADR in the same PR as the decision it records.
- `/handoff` / completion: any decision that meets the Phase-2 bar gets
filed before closure (`enhance-agent-guardrails` can install the
reminder).
- When an agent's proposal contradicts an Accepted ADR: **surface, cite,
ask** — do not silently comply *or* silently override. Changing course
produces a superseding ADR, on purpose, by the human.
- Periodic sweep (fits `workflow-housekeep`): statuses current, index
matches files, superseded chains intact.
---
## Definition of Done
- [ ] `docs/adr/` + INDEX.md exist; numbering and statuses in place
- [ ] Agent rules load the index each session and forbid silent contradiction of Accepted ADRs
- [ ] Format enforced: one page, rejected-alternatives section present, supersede-not-edit
- [ ] Scope rules recorded (what does / does not get an ADR)
- [ ] Backfill done for still-binding decisions, "things agents keep trying to change" first
- [ ] Same-PR rule and handoff hook wired
- [ ] Index verified against files (no dangling numbers, no unindexed ADRs)
## Self-critique before writing ADRs [LOW freedom — do not skip]
1. **Backfill list shown first** — decisions are theirs; recording is yours
2. **Rejected alternatives filled** — an ADR without them will not stop re-proposal
3. **One page** — two decisions or it's docs (`docs-writer`)
4. **Never edit Accepted** — supersede
5. **Not everything** — linter-enforced and TODOs stay out
## Output format
1. **System files** — the directory, INDEX.md, agent-rule text added
2. **Backfilled ADRs** — each one page, rejected-alternatives filled
3. **Lifecycle wiring** — same-PR rule, handoff hook, housekeep sweep item
Present the backfill list for confirmation **before** writing the ADRs —
the decisions are theirs; the recording is yours.
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · kensaurus/cursor-kenji | 100 | MIT |
| h2xd/skills | 100 | MIT |
| mgiovani/cc-arsenal | 100 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki 3baaa629c416 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 80decision-record
Pisze zapis decyzji architektonicznej (ADR), gdy użytkownik chce zapisać decyzję albo uchwycić, że coś postanowiono. - 84adr
Tworzy i prowadzi rekordy decyzji architektonicznych, czyli ADR, gdy trzeba zapisać decyzję lub przygotować obsługę ADR w projekcie. - 95adr
Tworzy lub recenzuje Architecture Decision Records dla decyzji architektonicznych, trwałych kompromisów, nowych zależności, kontraktów i wzorców. - 100adr-ops
Pisze, indeksuje i lintuje ADR jako dopisywaną pamięć odzyskującą powód kształtu systemu: szablon, kolejny numer, zastępowanie decyzji. - 100architecture-decision-records
Pisze i utrzymuje ADR według dobrych praktyk dokumentowania decyzji technicznych, także przy przeglądzie wcześniejszych wyborów architektonicznych. - 100030-architecture-adr-general
Prowadzi rozmowę i tworzy rekordy decyzji architektonicznych ADR dla projektu Java, z kontekstem i opcjami.