| name | adr-new |
| description | Create an Architecture Decision Record. Use when documenting an architecture decision, "record this choice", "we decided to use X", or after resolving an architectural DR. Do NOT use for capturing questions (use dr-new instead) or reviewing existing ADRs (use sdlc-status instead). |
| argument-hint | [Decision Title] [--from-dr DR-NNN] [--status accepted] |
| user-invocable | true |
| metadata | {"author":"APME Team","version":"1.0.0"} |
ADR New
Create an Architecture Decision Record.
Arguments
If $ARGUMENTS is provided, parse for:
- Decision title in quotes → use as ADR title
--from-dr DR-NNN → pre-fill from a decided DR--status X → set status (proposed/accepted)
Usage
/adr-new # Interactive mode
/adr-new "Decision Title" # Quick mode with title
/adr-new --from-dr DR-008 # Pre-fill from decided DR
/adr-new "Title" --status accepted # With status
Behavior
1. Check for Context
From DR: If --from-dr DR-NNN provided, read the DR and pre-populate:
- Context from DR context
- Options from DR options
- Decision from DR decision
- Rationale from DR rationale
Ask user to confirm or modify.
From conversation: If recent discussion contains a decision:
I see you decided [X] over [Y]. Create ADR from this? (Y/n)
2. Determine Next ADR Number
Scan .sdlc/adrs/ADR-*.md for highest number, increment by 1.
3. Gather Information (Streamlined)
Decision title?
Context — why is this decision needed?
Accept paragraph. Will include any constraints and drivers mentioned.
Constraints and drivers? (bullet list, or included above)
Accept freeform bullets. Parse into constraints and decision drivers.
Options considered (name: description, pros/cons):
Accept freeform. For each option, parse:
- Name and description
- Pros (lines starting with +)
- Cons (lines starting with -)
Require at least 2 options for meaningful comparison.
Decision — which option and why?
Accept option name/number and rationale together.
Consequences? (use +/- prefix, or describe)
Parse into:
- Positive (+ prefix)
- Negative (- prefix)
- Neutral (~ prefix or unmarked)
Status? (1=Proposed, 2=Accepted)
Implementation guidance? (or skip)
Related ADRs? (numbers, or skip)
Validate ADRs exist, include titles.
From a DR? (number, or skip)
If provided, link ADR to DR and update DR with ADR reference.
4. Consistency and Invariant Check
Before creating the ADR file, verify consistency with the existing
architecture.
Step A — Read AGENTS.md Architectural Invariants. Check if this ADR
would modify, supersede, or conflict with any of the invariants:
Invariant consistency check:
| Invariant | Status |
|-----------|--------|
| 1. Validators read-only | Consistent / MODIFIES — [explain] |
| 2. gRPC between services | Consistent / MODIFIES — [explain] |
| ... | ... |
Step B — Read .sdlc/adrs/README.md. Check for conflicts with existing
accepted ADRs. Specifically look for:
- ADRs this decision would contradict without superseding
- ADRs that cover the same scope (potential duplicate)
- ADRs this should explicitly reference as "Related Decisions"
Existing ADR consistency:
- ADR-NNN: [compatible / superseded by this ADR / contradicted — explain]
If this ADR modifies an invariant:
⚠ This ADR modifies architectural invariant [N]: [name]
This requires:
1. Explicit "Supersedes" or "Amends" reference to the original ADR
2. Update to AGENTS.md Architectural Invariants after acceptance
3. Human approval — invariant changes cannot be auto-accepted
Include in ADR body: "This ADR amends invariant [N] because [rationale]"
If this ADR contradicts an existing accepted ADR without superseding it:
⚠ This ADR contradicts ADR-NNN without superseding it.
Either:
1. Add "Supersedes: ADR-NNN" to this ADR
2. Modify this ADR to be compatible with ADR-NNN
3. Explain why both can coexist (add to Related Decisions)
5. Create ADR File
Create .sdlc/adrs/ADR-NNN-title-slug.md using template.
Slug: 3-5 words, lowercase, hyphens.
Fill:
- Title, Status, Date (today)
- Context (including constraints/drivers)
- Options with pros/cons
- Decision and rationale
- "Why not chosen" for rejected options
- Consequences (positive/negative/neutral)
- Implementation notes (if provided)
- Related decisions
- References (originating DR if applicable)
- Revision history with initial entry
6. Update Index
Edit .sdlc/adrs/README.md:
- Add a row (insert in numerical order):
| [ADR-NNN](ADR-NNN-slug.md) | Title | Status | YYYY-MM |
7. Link to DR (if applicable)
If ADR originated from a DR:
- Update DR's "Related Artifacts" to reference ADR
- If DR open, note that ADR captures the decision
8. Summary
Done!
- Created: ADR-NNN-title-slug.md
- Status: [Proposed/Accepted]
- Updated: adrs/README.md
Next: [If Proposed] Share for review | [If Accepted] Implement
Quick Mode
With inline parameters:
| Provided | Skip |
|---|
| Title in quotes | Title prompt |
--status X | Status prompt |
--from-dr DR-NNN | Context, options, decision prompts |
From-DR Mode
With --from-dr DR-NNN:
- Read the decided DR
- Extract context, options, decision, rationale
- Show summary and ask for confirmation
- User can modify or accept
- Automatically link ADR ↔ DR
Parsing Freeform Options
Accept variations:
Redis: In-memory cache with TTL
+ Fast, built-in expiration
- Extra container
Memcached: Distributed cache
+ Simple, lightweight
- No persistence
Or structured:
Option 1: Redis
Pros: Fast, TTL support
Cons: Extra container
Parse into standard format for ADR.
Edge Cases
| Situation | Handling |
|---|
| <2 options provided | Ask for at least one more |
| DR not found | Warn and continue without pre-fill |
| DR not decided | Warn that DR is still open |
| No consequences listed | Note "To be determined" |
