github-cr-adr

Create ADR (GitHub)

Draft one Architecture Decision Record as an ephemeral local file, ready to be reviewed and then published as a GitHub issue by github-post-issue.

An ADR records one durable architecture decision so it is never re-litigated from scratch. Its value is the why and the trade-offs, not just the final choice. The published ADR must stand alone: GitHub is the project's state store, agent sessions are stateless workers, and the issue is the complete record — any future contributor or agent session must be able to read it with zero private context.

This skill always operates on the repository it is invoked in — the repo is detected dynamically in step 1 and never assumed.

When to use

• The decision is architecturally significant: it shapes structure, dependencies, interfaces, non-functional characteristics, or construction techniques.
• The decision is expensive to reverse, and a future contributor will need to understand why it was made.
• The user wants to formalize a decision already reached in discussion, so the reasoning survives the session.

Skip if

Workflow

1. Search for existing coverage — before writing anything

Catching a duplicate before drafting costs one search; catching it at publish time costs a fully written body. Detect the consumer's repository dynamically:

REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
# Fallback when gh cannot resolve the repo:
[ -z "$REPO" ] && REPO=$(git remote get-url origin | sed -E 's#(git@|https://)github.com[:/]##; s#\.git$##')

gh issue list --repo "$REPO" --search "<decision keywords>" --state all --limit 20

Search with --state all, because a closed or rejected ADR on the same topic is exactly the history that must not be forked. If gh is missing or unauthenticated, say so and continue drafting — dedup is a read-time optimization here and runs again as a hard gate at publish.

If an existing issue or ADR covers the topic, stop and propose one of these instead of a new draft:

• Comment on the existing issue with the new argument or evidence.
• Amend the existing ADR with a dated note (see the status lifecycle below).
• Sub-issue — a narrower follow-up decision linked to the existing record.

Continue to a new draft only when the topic is genuinely uncovered, or the user explicitly confirms the existing record does not apply.

2. Apply the worthiness gate — refuse, don't ask

An ADR is warranted only for a decision that is architecturally significant and expensive to reverse. If the request fails that bar, decline to draft it and explain why — do not draft anyway just because it was asked for, and do not soften the gate into a rhetorical question. Offer github-cr-issue for the same content as a regular issue, which is usually what the situation actually needs.

If the user insists after the refusal, ask for an explicit override rationale and record it in the draft's Context section, so the record itself explains why it exists.

Gate questions — all should be "yes":

3. Gather the essentials

Ask the user for whatever is missing; never invent decision content.

Decision statement, right and wrong:

Good: "The service adopts event sourcing for order state."   (commitment, present voice)
Bad:  "We could maybe consider event sourcing at some point." (open debate, no decision)

4. Fill the template and save the draft

Copy assets/adr-template.md, fill every section, and save the draft:

mkdir -p .claude/sdd/drafts
# Save as: .claude/sdd/drafts/adr-<verb-phrase-slug>.md

The slug is a verb phrase in lowercase-with-hyphens (adr-enforce-input-validation.md, not adr-validation-v2.md) — a verb phrase names the decision itself, not the topic area.

The draft is ephemeral. It exists only to be reviewed and then consumed by github-post-issue, which deletes it after a successful publish. The published GitHub issue is the canonical record; never treat the local file as a source of truth after publication.

5. Run the self-containment pass

The published ADR must be readable with zero private context, so strip or translate before handing off:

6. Hand off for review and publication

Present the draft path and a short summary to the user for review. Publication belongs to github-post-issue: it re-runs the dedup and self-containment guardrails, validates labels, creates the issue, retitles it with the real ADR number, and deletes the draft.

Output of this skill: exactly one draft file under .claude/sdd/drafts/, or a reasoned refusal with a pointer to github-cr-issue.

Content rules

Numbering

ADR numbers are sequential, starting from 1 (ADR-001, ADR-002, …) — they are citations, and a dense, ordered sequence is what makes them readable and quotable. The number is assigned at publish time by github-post-issue, which reads the highest existing [ADR-NNN] on the live board and takes the next one. Therefore:

• The draft carries the ADR-XXX placeholder and nothing else.
• Never pre-assign a number at draft time — two drafts written in parallel would claim the same number; the live board at publish time is the only allocator that cannot collide.
• Never reuse a number, even one freed by a rejected or superseded ADR — stable numbers keep old citations valid forever.
• Cross-references to other ADRs use their ADR number (link the issue alongside it for navigation).

Status lifecycle

• A rejected ADR stays on record with its reasoning — it prevents re-litigating the same idea later.
• Supersede, don't rewrite. When an accepted decision changes, raise a new ADR that supersedes the old one, cross-link both, and mark the old one Superseded by ADR-YYY. Erasing the old reasoning erases the only defense against repeating the mistake.
• Because published ADRs are GitHub issues and therefore mutable, amending in place is acceptable for clarifications — but always with a dated note, never silently.

References

Related skills

• github-post-issue — publishes the reviewed draft as a GitHub issue, assigns the real ADR number, and deletes the draft.
• github-cr-issue — drafts regular (non-ADR) issues: features, tasks, bugs, spikes, epics.