# ADR Writing Exercises

## Exercise 1: Write an ADR for a Database Choice

**Task:** Write a full ADR for: "We chose PostgreSQL over MongoDB for the main application database." Include Title, Status, Context (options, constraints), Decision, Consequences (positive and negative).

**Validation:**
- [ ] All five sections present
- [ ] Context explains the options and constraints
- [ ] Decision is clear and actionable
- [ ] At least one negative consequence included

**Hints:**
1. Context: need ACID, relational data, team familiarity, existing tooling
2. Consequences: PostgreSQL — strong consistency, ecosystem; negative — schema migrations, scaling writes
3. Keep it under 1–2 pages

---

## Exercise 2: Supersede an Old ADR

**Task:** You have ADR-003: "Use REST for all APIs (Accepted)". The team later decides to add GraphQL for mobile. Write ADR-007 that supersedes ADR-003 for the mobile API only. Include a reference to ADR-003 and explain the change.

**Validation:**
- [ ] ADR-007 has Status: Accepted
- [ ] ADR-007 references/supersedes ADR-003
- [ ] Context explains why the original decision no longer fully applies
- [ ] ADR-003 would be updated to Status: Superseded by ADR-007

**Hints:**
1. "This ADR supersedes ADR-003 for mobile clients only."
2. Update ADR-003's status to "Superseded by ADR-007"
3. Context: mobile needs fewer round-trips, flexible querying

---

## Exercise 3: Lightweight vs Heavyweight

**Task:** Compare lightweight ADRs (Markdown in repo, no tooling) vs heavyweight (formal review, Log4brains, templates). List 2 pros and 2 cons of each. When would you recommend a team switch from lightweight to heavyweight?

**Validation:**
- [ ] Pros and cons for both approaches
- [ ] A clear trigger for when to add process (e.g., compliance, many teams, governance)

**Hints:**
1. Lightweight: fast, low friction, might get inconsistent
2. Heavyweight: discoverable, consistent, more overhead
3. Switch when: audit needs, many ADRs, cross-team coordination

---

## Exercise 4: Context That Helps Future Readers

**Task:** You're writing an ADR for "We use feature flags for all production releases." Write a Context section that would help someone in 2 years understand *why* — include what problem it solved and what the alternative was (e.g., long-lived branches, big-bang releases).

**Validation:**
- [ ] Problem is stated clearly
- [ ] Alternative approach(es) are mentioned
- [ ] A new joiner could understand the rationale without asking

**Hints:**
1. Problem: risky deployments, hard to roll back, long merge cycles
2. Alternative: branch per feature, merge at release
3. Include constraints: team size, release frequency

---

## Exercise 5: Deprecate Without Replacement

**Task:** Write an ADR that deprecates a previous decision: "We no longer use Redis for rate limiting; we switched to an API gateway feature." This deprecation has no replacement ADR (the new approach is configured, not a separate architecture decision). Document it appropriately.

**Validation:**
- [ ] Status: Deprecated
- [ ] Context explains what changed and why
- [ ] References the original ADR if one existed
- [ ] States that the capability now lives elsewhere (gateway config)

**Hints:**
1. "This ADR deprecates ADR-005 (Use Redis for rate limiting)."
2. Context: gateway provides rate limiting; one less moving part
3. No superseding ADR needed — operational change