name: adr description: Create an Architecture Decision Record in docs/adr/. Use when the user says "create an ADR", "document this decision", "record this architecture decision", or when a design discussion leads to a conclusion that should be preserved. Also trigger when the user describes a significant technical trade-off or says "why did we choose X over Y" in a way that implies the decision should be documented. argument-hint: "<decision-title> [--issue N]"
Architecture Decision Record Creator
Create an ADR following the project's established template at docs/adr/TEMPLATE.md. ADRs are the permanent record of why things are the way they are — they prevent re-litigating settled questions and help future contributors understand the framework's design.
Determine the next number
ls docs/adr/ | grep -E '^[0-9]{4}-' | sort -r | head -1
Extract the highest number, increment by 1, zero-pad to 4 digits. ADR-0000 is reserved for guiding principles.
Gather the content
From $ARGUMENTS and the conversation context, extract the building blocks of the ADR. The template (from docs/adr/TEMPLATE.md) has these sections:
Title: Short noun-phrase. Good: "Use networkx for dependency graphs". Bad: "We decided to add networkx".
Status: Almost always Accepted when creating a new ADR — if the decision is already made, it's accepted. Use Proposed only if the ADR is being written before the decision is final.
Date: Current month and year (e.g., "April 2026").
Context: The forces at play, the problem that needed solving, the constraints. Write as you would explain to a new team member with domain context. If the conversation has a design discussion, synthesize the key tensions here.
Decision: What was chosen, in active voice. "We will use X" / "We chose Y because Z." Specific enough that someone could implement or verify it.
Consequences: What becomes easier and harder. Every decision has trade-offs — state them plainly. This is the most valuable section for future readers.
Alternatives Considered (optional): Other approaches evaluated and why they were not chosen. Include this when multiple viable options were discussed.
If the user provides only a brief summary, expand it into the full structure. If the conversation contains a detailed design discussion, distill it — don't copy-paste the whole thread.
Create the file
Write to docs/adr/NNNN-<kebab-case-title>.md.
The filename should be descriptive but concise:
- Good:
0010-use-networkx-for-dependency-graphs.md - Bad:
0010-decision-about-which-graph-library-to-use.md
Link to related issue
If $ARGUMENTS contains --issue N or the conversation references a GitHub issue or epic, add a reference in the Context section:
Related: [#123](https://github.com/proteanhq/protean/issues/123)
Also reference other ADRs when the decision builds on or constrains earlier ones — e.g., "Building on the IR-first approach established in ADR-0005."
Stage and report
git add docs/adr/NNNN-*.md
Show the user the file path and a brief summary so they can review before committing. ADRs are best reviewed before merge — they're hard to correct retroactively because they represent a point-in-time decision.