adr-writing

ADR Writing

Mode Detection

• Creation: "create", "write", "new", "draft"
• Validation: "validate", "check", "verify", "review"

---

Front Matter

---
title: Short descriptive title
date: YYYY-MM-DD
area: core
tags: [relevant, tags]
---

• title (required): Short, descriptive. Do NOT repeat as a Markdown # heading
• date (required): YYYY-MM-DD
• area (required): One of: core, checkout, admin, storefront, inventory, framework, discovery, infrastructure, process
• tags (required): Lowercase technical terms, YAML array
• authors, status (optional)

Required Coverage

Every ADR must address all 8 items:

1. Complete description of the requirements
2. All technical domains affected
3. All affected logic in the system
4. Pseudocode for new logic
5. All public APIs to be created or changed
6. How developers can extend the new APIs and what business cases you see
7. The reason for the decision
8. All consequences and their impact on developers

Writing Principles

• Audience: Shopware developers familiar with the codebase — no need to explain DAL, Symfony, Vue, Criteria, SalesChannelContext
• Voice: Direct, informal, developer-to-developer
• Factual over promotional: Describe what changes and why ("simplifies the caching logic", "removes manual transaction handling"). Never use marketing language ("greatly enhanced", "stands to benefit significantly"). Quantitative claims only when backed by explicit data the author provides — never estimate or guess numbers
• Prose for reasoning, plain bullets only for discrete independent items
• One decision per ADR
• Rationale focus: The "why" is the most valuable part

Load references/writing-style.md for voice examples, table/diagram guidance

---

Creation Workflow

Step 1: Gather Context

AskUserQuestion to collect: topic/title, area (present enum), tags, scope (single vs multi-domain).

If topic already provided, infer what you can before asking.