Create Architecture Decision Record

Overview

Create a structured Architecture Decision Record (ADR) following Michael Nygard's format. ADRs capture the context, decision, alternatives considered, and consequences of significant technical choices so future engineers understand why something was decided, not just what was decided.

Workflow

1. Read project context -- Read .chalk/docs/engineering/ for existing architecture docs and conventions. Read any existing ADRs to understand prior decisions and link related records.

2. Determine the next ADR number -- List files in .chalk/docs/engineering/ matching the pattern *_adr_*.md. Find the highest number and increment by 1. If no ADRs exist, start at 1.

3. Clarify the decision -- From $ARGUMENTS and conversation context, identify:

   • The specific technical decision being made (or proposed)
   • The forces and constraints driving the decision
   • The alternatives that were (or should be) considered
   • Ask the user for clarification if the decision scope is ambiguous

4. Research alternatives -- If the user hasn't specified alternatives, propose 2-4 reasonable options based on the project context. Every ADR must have at least 2 alternatives considered, including the chosen approach.