ADR - Architecture Decision Record

Evaluate whether recent changes warrant an ADR and create one if justified.

Instructions

1. Analyze Session Changes

Run git diff to see uncommitted changes. If no uncommitted changes, run git diff HEAD~1 to review the last commit.

If a scope is provided via arguments (e.g., a commit range or file path), use that instead.

2. Determine if an ADR is Warranted

An ADR is justified when:

• A significant architectural decision was made (new pattern, new abstraction, structuring technical choice)
• The decision affects the code structure in a durable manner
• There were alternatives considered that are useful to document
• A new library or tool was introduced that replaces or complements existing ones
• A convention or pattern was established that future code should follow

An ADR is NOT justified for:

• Routine feature additions following existing patterns
• Bug fixes
• Minor refactoring that doesn't change architecture
• Dependency updates (unless a major migration)
• Configuration changes

3. If Not Warranted

Report to the user:

No ADR needed - changes follow existing patterns without introducing new architectural decisions.

4. If Warranted

4a. Determine the next ADR number

List existing ADR files to find the next sequential number:

ls docs/adr/

4b. Read the template

Read the ADR template at docs/adr/0000-template.md.

4c. Draft the ADR

Write the ADR following the template with these rules:

• Title: Concise decision statement in imperative form (e.g., "Use Zod for runtime validation")
• Date: Today's date
• Status: Accepted
• Context: Why did this decision come up? What problem were we solving?
• Decision: What was decided, concisely
• Options Considered: At least 2 options with honest pros/cons. Only include options that were actually considered, don't invent fictional alternatives.
• Consequences: Real positive and negative impacts
• Links: Reference related ADRs if applicable

4d. Present for validation

Show the full draft to the user and ask for feedback before creating the file.

4e. Create the file

Once validated, write the file to docs/adr/NNNN-kebab-case-title.md.

4f. Update the index

Add the new ADR to the index table in docs/adr/README.md.

Scope

$ARGUMENTS

If no scope provided, analyze all uncommitted changes or the last commit.