adr-suggest.md

adr-suggest.md

name

adr-suggest

description

Proactively offer to draft an Architecture Decision Record (ADR) when the conversation reaches an architectural decision point. TRIGGER when the user (or you) is choosing between alternatives ("X vs Y", "go with A or B"), switching away from an established approach ("replace X with Y", "deprecate X"), adding/removing a major dependency (mix.exs, npm, system service), introducing a new core abstraction (new context module, new CQRS aggregate, new behaviour), defining a cross-cutting convention ("from now on we always..."), or revisiting a previously made architectural choice. SKIP for bug fixes, UI styling, behavior-preserving refactors, test-only changes, copy edits, or work that follows an already-documented convention.

ADR Auto-Suggest

You've been activated because the conversation has the shape of an architectural decision. Your job is not to write the ADR yourself — it is to recognise the moment and steer the user toward the /adr slash command, which owns the authoritative template and workflow.

What counts as architectural

Apply the same bar as /adr. Triggers worth surfacing:

• Choosing storage: Postgres column vs jsonb vs Oban arg vs S3 vs cache vs config file
• Adding/removing a major dependency: anything in mix.exs, top-level npm package, new system service (Redis, queue, search engine)
• New core abstraction: a new context module under lib/amplify/services/, a new CQRS aggregate/projector, a new behaviour, a new Oban worker pattern that others will copy
• Cross-cutting convention: error code shape, locale isolation rule, validation library choice, redirect-guard pattern — anything where the answer to "should the next feature do this the same way?" is yes
• Replacing an established approach: ripping out an existing pattern in favour of a new one (this likely supersedes a prior ADR if one exists)

Non-triggers (do not suggest an ADR):

• Bug fixes, copy edits, UI tweaks
• Refactors that preserve behaviour
• Test additions
• Following a convention already documented in CLAUDE.md or an existing ADR

How to respond when triggered

1. Confirm the decision is real, not exploratory. If the user is still investigating options ("what would happen if…"), don't push for an ADR yet. Wait until a direction is chosen.

2. One short suggestion, not a lecture. Example phrasing:

   This looks like an architectural decision (choosing X over Y for Z). Want me to draft an ADR via /adr? It'll live in site/internal/src/content/docs/adrs/.

3. If the user accepts, invoke the /adr slash command (or follow .claude/commands/adr.md verbatim if invoking isn't possible). Use today's date and the next ID.

4. If the user declines, drop it. Don't bring it up again in the same session unless a different decision surfaces.

5. If superseding a prior decision, check site/internal/src/content/docs/adrs/ for the old ADR and follow the supersede flow in /adr.

Drafting hints (when the user accepts)

• Decision first, in 1–2 bolded sentences. If you can't, the decision isn't crisp enough yet — pull more from the user.
• Context answers "why now?" — what forced the question today.
• Options considered must include real alternatives with honest pros/cons (not strawmen).
• Consequences must include negatives. A one-sided ADR is a red flag.
• Tags — pick 1–3 from existing tags in the index, or introduce a new one if genuinely new area. Common tags so far: persistence, payments, auth, cqrs, frontend, i18n, email, cqrs, observability.

Do not

• Don't auto-create ADRs without confirmation — they're durable artifacts and committing one is a deliberate act.
• Don't create separate ADR-only commits. The ADR is folded into the feature commit.
• Don't edit body content of existing ADRs. Only status: / superseded_by: may change after commit.