Przejdź do treści
Biblioteka skilli
Programowanie · Pisanie

adr

/adr

Zapisuje jedną decyzję architektoniczną jako plik NNNN-slug.md w korpusie decyzji repozytorium, także gdy w rozmowie ustalono preferencję, konwencję lub niezmiennik, którego muszą przestrzegać przyszli agenci.

Repozytorium
phoenix ↗
Licencja
MIT
Ostatnia zmiana repozytorium
18.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
2
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 18.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Zapisuje jedną decyzję architektoniczną jako plik NNNN-slug.md w korpusie decyzji repozytorium, także gdy w rozmowie ustalono preferencję, konwencję lub niezmiennik, którego muszą przestrzegać przyszli agenci.

Wyzwalacze z opisu

s decision corpus. Trigger on \, \
Oryginalny opis (EN)

Record one architecture decision as an `NNNN-slug.md` file in the repo's decision corpus. Trigger on \"/adr\", \"save this as an ADR\", \"record this decision\", \"ADR for X\" — and reach for it whenever a technical preference, convention, or invariant gets settled in conversation that future agents must respect, even when nobody asks for an ADR.

Jak działa

  1. 1 — Claim the number and write the file, in one call
  2. 2 — Write the decision
  3. 3 — Sweep the live ADRs this one might contradict
  4. 4 — Resolve every reference, then edit the status lines
  5. 5 — Record the vocabulary impact
  6. 6 — Check, then report
Sekcje z nagłówków SKILL.md, w oryginale · 165 linii, 1 704 słów
Podgląd SKILL.md
---
name: adr
description: "Record one architecture decision as an `NNNN-slug.md` file in the repo's decision corpus. Trigger on \"/adr\", \"save this as an ADR\", \"record this decision\", \"ADR for X\" — and reach for it whenever a technical preference, convention, or invariant gets settled in conversation that future agents must respect, even when nobody asks for an ADR."
---

# adr

One decision per file; the pull request adds nothing but that file plus the status-line edits it
implies and any optional pointer step 4 allows, because discovery is the CLAUDE.md contract and there
is no index. A settled preference earns a file even when nobody asks for an ADR — an unrecorded
ruling is one the next session re-decides differently. Examples run id `9240`.

## 1 — Claim the number and write the file, in one call

```bash
fabrika adr mint only-landed-adrs-may-be-cited
```

One call allocates the id and scaffolds the record, and that is why it is one call: it unions the
freshly fetched merged set with the ids open ADR PRs already claim and the ids this clone's branch
refs carry, remote-tracking ones included, so a checkout one id behind origin cannot mint a
duplicate — **and an id you
allocate now and write later is already stale**, which is how one id has landed on two pull requests
at once. The slug is kebab-case, at most 5 words; it prints the path written. How the union is
computed, and the exact bytes it scaffolds, are the verb's section
(`fabrika wire doc-section --heading "adr mint" < <skill-base>/contract.md`).

**A sibling worktree's unpublished mint counts.** An epic child commits its record to a local branch
and opens no pull request, and worktrees of one clone share one ref store, so that id is in the union
from the moment it is committed. Two children of one epic were each handed `0373` before this read
existed. The walk reads remote-tracking refs too, so a branch another clone has pushed counts here
once this one has fetched it. What it does not reach is a branch that is still unpushed elsewhere:
those two lanes collide, and step 6 is where you find out.

**A non-zero exit is UNKNOWN, never "nothing reserved."** Re-run it. Falling back to the highest id
on disk mints the same number from two lanes at once.

**An empty corpus is not one of those cases — it allocates `0001` and exits 0.** A repo
adopting fabrika has no records on day one, and that is a fact the verb reports, not a read it
failed. Only a directory it could not read at all refuses (exit 11). If the directory does not exist
yet, create it and re-run; a repo with no decision directory at all is a setup question for
[front-door](../front-door/SKILL.md).

**Where the corpus lives is the repo's, not this skill's.** `.fabrika.jsonc`'s `decisionsDir` names
it and defaults to `.decisions`; `--dir` overrides it for one run. A repo that writes `null` there
keeps no corpus at all, and then every verb of this group refuses on `22` naming the key — there is
nothing to read and nothing to write into, and that is a settled fact no retry changes, unlike the
`11` an unreadable directory earns.

`fabrika adr next` still answers the id on its own, and `fabrika adr new 9240 <slug>` still
scaffolds against an id you name (`fabrika wire doc-section --heading "adr next" < <skill-base>/contract.md`,
then `--heading "adr new"`). Reach for the pair only when you genuinely need the id before the
file — the gap between them is the race, so do not re-open it out of habit. Whichever route, the
minted file is not a reservation: another clone sees the id only once you push the branch it sits
on, or once the pull request opens, and step 6 is where you find out whether someone got there
first.

## 2 — Write the decision

**The `title` carries the decision, not the topic** — `Every gate fails closed on zero scope`, never
`Gate scope handling`. **One clause**: where the ruling has a discriminating half, it belongs inside
that clause (`X, never Y`), never appended as a second clause after an em-dash. The corpus median is
14 words, a shape rather than a cap. It renders verbatim as this ADR's compact-map row, and the
`# NNNN — <Title>` H1 repeats it character for character. The `**What this decides:**` line beneath
is the plain-language gloss a non-author reads.

`## Decision` opens with one bolded declarative sentence, ahead of any mechanics. Where this ADR
constrains future work, close it with an austere `**Binding constraints.**` or `**Banned.**` list.

## 3 — Sweep the live ADRs this one might contradict

Two live `accepted` ADRs deciding opposite things on one question are worse than an open question:
each reads as authoritative, neither hints the other exists. Write down what this ADR settles **as
questions** — *"may an open issue exist without a milestone?"* — not as a summary; you cannot sweep
for a question you cannot phrase. Then rank the uncited live-accepted ADRs your domain touches:

```bash
fabrika adr sweep --new 9240
```

How the ranking is computed, and why it caps where it does, are the verb's section
(`fabrika wire doc-section --heading "adr sweep" < <skill-base>/contract.md`). None of its three
outcomes is a clearance:

- **`shortlist`** — open the entries and judge each once. It ranks lexical adjacency, caps at 8, and
  **re-ranks as you add citations**, so the tail refills and chasing a clean result is the trap.
- **`no-overlap`** — nothing mechanically adjacent was left to open, **never** that there is no
  contradiction: an ADR disagreeing with yours about what a label *means*, sharing no distinctive
  vocabulary, never appears at all. Read the domain by hand.
- **`indeterminate`** — the run carries no information: your draft yielded no distinctive term — one
  every live-accepted ADR carries is not distinctive — or the corpus is too small to rank rarity
  against. Distinctiveness is a property of your draft against the corpus, not of what it overlaps,
  so a draft whose vocabulary is entirely its own is maximally distinctive and lands on `no-overlap`
  instead. Say which fired, and read by hand regardless.

Resolve each real hit in step 4 — supersede where this ADR replaces it outright, amend-in-part where
the rest still stands. Where you only refine your own earlier ADR's mechanics and its ruling holds,
append a dated `- **#NNNN — <what changed> (YYYY-MM-DD).**` line under its `## Amendments` instead.

**An amendment on a subject the parent's `title` does not name re-titles the parent, in the same
pull request.** Rewrite the frontmatter `title` and the H1 together so they name every ruling the
file carries, and add the new subject to `tags`. Keep the id and the filename, so every existing
citation still resolves. Discovery reads filenames plus frontmatter, so a ruling the title omits is
one a reader finds only by grepping the body — and a correct citation of it reads as a mis-citation.
A re-titled parent holds one clause per ruling, which is the one case step 2's one-clause shape
gives way.

## 4 — Resolve every reference, then edit the status lines

```bash
fabrika adr resolve 9164 9023 9126
```

Answers against a freshly fetched base ref, printing `live`, `landed`, `in-flight` or `absent` with
the real filename. Pass every citation, supersede link and amend target in one call.

**Cite only `live`.** `landed` means present but `proposed`, `superseded` or `retired`, and citing
one as settled law applies a decision that was already withdrawn. `in-flight` may never merge, so a
citation to one can pass every gate and still be dead on arrival. **A non-zero exit is UNKNOWN,
never `absent`.** **Use the filename it prints** — a remembered slug is usually the wrong one. How
each state is proven against the fetched base is the verb's section
(`fabrika wire doc-section --heading "adr resolve" < <skill-base>/contract.md`).

```bash
fabrika adr supersede 9126 --by 9240
```

Where the rest of that ADR still stands, `fabrika adr amend-in-part 9023 --by 9240` instead.
Either verb rewrites the `status:` line only. You **may** then hand-add a bounded pointer inside the
older ADR's body: a link to your record and a scope note saying where its text still holds. The
pointer adds no ruling, reverses nothing, and leaves the claims of the decision it sits in as they
are; a change past that is a ruling, so it goes in your record, and a reversal is a `supersede`. The
pointer is optional — naming the relationship only in your own `## Context`, with the older body
untouched, is equally conforming. Which line each rewrites, and what each refuses, is their shared
section:
`fabrika wire doc-section --heading "adr supersede and adr amend-in-part" < <skill-base>/contract.md`.

## 5 — Record the vocabulary impact

A terminal `## Records` section is required only when the ADR coins or redefines a term. Name the
term there and route it to `.glossary/TERMS.md`: the row in this PR when the definition is short and
unambiguous, otherwise `/glossary`.

## 6 — Check, then report

```bash
fabrika adr resolve 9240
```

Your own id, one last time. **This verb reads the published sets only** — the base ref and the open
pull requests — so its `absent` is not the branch-aware answer step 1 gave you: a lane in another
clone that has not opened its pull request is invisible here. `absent` means nobody *published* a
claim while you wrote; `in-flight` means
another lane opened its PR first, so **renumber now — the lane that opened first keeps the id, and
this check is the only place a renumber is still cheap.** Skip it and nothing else stops the
duplicate: a repo's own duplicate-id check reads the merge queue's batched ref and reports it, but a
job that is not a required context does not hold the batch. Both records land, the default branch
goes red, and you renumber
there instead — a second pull request, a second review, and the approval on this one already spent.

**Whether this PR needs a control-plane approval is `fabrika ship scope`'s answer, not yours** — it routes
on CODEOWNERS, and how a repo owns its decision corpus decides it
([control-plane classification](../../docs/control-plane-classification.md)). **That gate is the
authority: do not predict it, and never reword the ADR to change its verdict.** A wrong
control-plane call costs one approval; a wrong ordinary call reaches `main` with none. If you think
it misfired, say so on the pull request.

Report the path and the vocabulary outcome; do not summarize the body.
Pliki w paczce (2)
  • SKILL.md 10 KB
  • contract.md 47 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · kamp-us/phoenix100MIT
maximiliancw/adrinaline100MIT
pJijesh/adr-skill100MIT
zazencodes/skills100MIT
vindotski/spotcraft100Apache-2.0
me-cedric/Shipyard100MIT
musingfox/cc-plugins100MIT
joestump/claude-plugin-sdd100MIT
kaisa-kucherenko/claude-code-flow100MIT

Migawka bazy z 13.11.2026 · wersja paczki 2be00d153f53 (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

  • 100adr-write
    Zapisuje pojedynczą decyzję architektoniczną jako numerowany ADR po zatwierdzeniu przez użytkownika, także gdy zapadła w trakcie implementacji.
  • 100adr-writer
    Pisze rekord decyzji architektonicznej w Markdownie, gdy użytkownik prosi o ADR, decyzję techniczną albo jej udokumentowanie.
  • 80decision-record
    Pisze zapis decyzji architektonicznej (ADR), gdy użytkownik chce zapisać decyzję albo uchwycić, że coś postanowiono.
  • 90decision
    Zapisuje decyzję architektoniczną w formie ADR przy ważnych wyborach technologicznych i zmianach konwencji.
  • 90decision
    Zapisuje decyzję architektoniczną w formie ADR przy ważnych wyborach technologicznych i zmianach konwencji.
  • 100create-adr
    Tworzy Architecture Decision Record dokumentujący decyzję techniczną i uzasadnienie wyboru podejścia.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.