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.
Ocena i bezpieczeństwo
- Pliki w paczce
- 2
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 18.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
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
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 — Claim the number and write the file, in one call
- 2 — Write the decision
- 3 — Sweep the live ADRs this one might contradict
- 4 — Resolve every reference, then edit the status lines
- 5 — Record the vocabulary impact
- 6 — Check, then report
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
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · kamp-us/phoenix | 100 | MIT |
| maximiliancw/adrinaline | 100 | MIT |
| pJijesh/adr-skill | 100 | MIT |
| zazencodes/skills | 100 | MIT |
| vindotski/spotcraft | 100 | Apache-2.0 |
| me-cedric/Shipyard | 100 | MIT |
| musingfox/cc-plugins | 100 | MIT |
| joestump/claude-plugin-sdd | 100 | MIT |
| kaisa-kucherenko/claude-code-flow | 100 | MIT |
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.