Menu
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.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
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/.