adr-workflow

## Creation Flow ### 1. Check for duplicates Before creating any ADR, check if an ADR already exists in the same domain. If a Proposed ADR exists: recommend reviewing and accepting the existing one before creating a new one. If an Accepted ADR exists: if the decision has changed, use "Superseded by NNNN". Options: `[R]` Review existing / `[S]` Supersede (create new ADR) / `[C]` Create separate (different domain). ### 2. Determine status If no existing ADR exists in the domain: - `[A]` Decision already made: ask for the final decision and options considered. Create with Accepted status (but recommend Proposed for team review). - `[B]` Needs discussion: ask for options to consider. Create with Proposed status. ### 3. Options and recommendations Options preferably come from the user. Offer suggestions only if: - The user explicitly asks - The user has no options or has only 1 Never invent options from templates, generic READMEs, or placeholder content. ### 4. Tool consultation (when available) **Microsoft Documentation** (for decisions involving Microsoft/Azure services): - Use `microsoft_docs_search` to look up limits, SLAs, pricing tiers, comparisons - Use `microsoft_docs_fetch` for full content of relevant pages - Incorporate data into the ADR options evaluation **Azure Cost Estimate** (if Azure MCP Server is available): - Use `azure/pricing` when cost is a ranked priority or the user asks about pricing - Do not block creation if the tool is unavailable: record "pricing not verified" **Azure Cloud Architect** (if Azure MCP Server is available and the project deploys to Azure): - Use `azure/cloudarchitect` (design) for Azure architecture recommendations - Use `azure/deploy` (architecture diagram) for Mermaid topology diagram - Present as options for the ADR, not as a final decision - Options: `[S]` Incorporate / `[M]` Modify first / `[I]` Ignore ### 5. Format and naming - Template: `docs/architecture/decisions/ADR-TEMPLATE.md` - Naming: `NNNN-domain.md` (e.g., `0001-data-persistence.md`) - Use the decision domain, not the choice made (e.g., "Data Persistence", not "Use PostgreSQL") - Sequential numbering (0001, 0002, etc.) ### 6. Completeness validation Before considering the ADR complete, verify: - Context filled in - At least 2 options documented - Decision with justification - Pros and cons for each option If there are missing fields, request information from the user. ## Common Rationalizations | Rationalization | Reality | |---|---| | "ADRs are overhead" | A 10-minute ADR prevents a 2-hour debate about the same decision six months later. | | "The code is self-documenting" | Code shows what was built. It does not show why, what alternatives were rejected, or what constraints applied. | | "We will document the decision later" | Decisions made without records get re-debated. Later never comes. | | "Nobody reads ADRs" | Future agents read them to avoid re-deciding. Future engineers read them to understand context. | | "This decision is obvious, no ADR needed" | Obvious decisions still have alternatives. Recording the reasoning prevents someone from proposing the discarded alternative later. |