Menú
Use when proposing or recording a significant technical decision (architecture change, new dependency pattern, public API change, hard-to-reverse choice) that should land as an Architecture Decision Record.
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Basado en la clasificación ocupacional SOC
Use when ingesting, refreshing, listing, searching, or deleting a local corpus with Blackbird code search and `gh blackbird search --fileset`.
Use when reaching for `gh blackbird` (Blackbird code search) for cross-repo lexical, symbol, or semantic search on GitHub — finding callers, ownership, or how systems work without cloning.
Use when creating a GitHub pull request, or when updating an existing PR's title or body so it matches what the code actually does.
Use when authoring or substantially editing a design doc, architecture doc, or subsystem explanation — the "here's what's there and why" companion to an ADR's terse decision record.
Use when creating a repo-tracked multi-agent planning PR for a large project, especially when phases, living docs, parallel agent prompts, and cross-PR coordination are needed.
Use when about to call a library, crate, or framework API you haven't verified, when a dependency's behavior is surprising, when training-data memory might be stale, or when investigating how a dependency actually behaves.
| name | adr-author |
| description | Use when proposing or recording a significant technical decision (architecture change, new dependency pattern, public API change, hard-to-reverse choice) that should land as an Architecture Decision Record. |
ADRs capture the framing behind significant technical choices. Repo-local conventions always win over the defaults here.
The bar is high — single digits per year for mature projects. Default to not writing one.
Write an ADR for:
Skip for: routine refactors, bugfixes, dependency bumps, subsystem-internal design choices (write a design doc — see design-doc-author), or choices likely revisited within months.
Calibration: if you can't name a similar-stakes decision the repo has already recorded as an ADR, you're over-reaching. Propose it, get explicit agreement, then write it.
Look for docs/adr/, docs/decisions/, adr/, or architecture/decisions/. Read the ADR README if present. Never invent a new filename pattern in an established directory — match sequential numbering (0007-foo.md) or date prefixes (2026-05-16-foo.md). If the repo maintains an index table, status convention, or any other ADR-adjacent ritual, follow it. New directory: default to docs/adr/ with YYYY-MM-DD-kebab-name.md and confirm with the user.
# ADR NNNN: Title
- Status: Proposed | Accepted | Deprecated | Superseded by [NNNN](NNNN-....md)
- Deciders: (optional) @handles or team names
- Related: (optional) links to related ADRs, skills, or docs
## Context
## Decision
## Consequences
## Alternatives
Status: Proposed (under discussion), Accepted (in effect), Deprecated (no longer applies), Superseded by NNNN (link both directions).
Open the ADR as a separate PR in Proposed status; review before the implementation PR merges. Mid-implementation realization: stop, open the ADR PR, link them.
Name the forces (performance, security, team capacity), the system constraints, and what the current approach fails at. A reader should understand why now. No hand-waving.
Name what gets harder, what locks in, what follow-up this implies. Only-positive consequences = red flag.
One sub-heading per serious alternative. State what it would look like and concretely why it lost — "slower" is hand-waving; specific cost is not.
skills/<topic>/SKILL.md).design-doc-author).Cross-link. Pair only when the rules need enforcing or the shape needs explaining beyond the ADR.
Superseded by [NNNN](...); cross-link both ways.docs/adr/.