Adr

# ADR-XXX Title in title case

## Status

Accepted. Date: YYYY-MM-DD.

(Or: Proposed; Deprecated; Superseded by ADR-YYY; Amended by ADR-YYY.)

## Context

One paragraph stating the problem clearly enough for a reader who has never seen this codebase. Include the constraints that drove the decision and the existing state that triggered the choice.

## Decision

A single declarative sentence stating what was chosen. Optionally followed by 2 to 4 short paragraphs unpacking the choice.

## Alternatives Considered

### Alternative A: name

Description and rejection reasoning.

### Alternative B: name

(repeat structure)

### Alternative C: do nothing

If "do nothing" was rejected, document why. If it was the right choice, this ADR is probably not needed.

## Consequences

**Benefits**

- Specific positive outcomes, with measurements when achievable.

**Trade-offs**

- The cost we accepted by making this choice.

**Risks and mitigations**

- *Risk*: what could go wrong. *Mitigation*: how we address it.

## Related Decisions

- **ADR-YYY (Title)**: how it relates (supersedes, amends, depends on, complements).

## References

- Implementation tasks or issue IDs.
- Source files affected (file:line).
- External specs, RFCs, vendor docs, or measurements.

Format: ADR-XXX-short-descriptive-title.md

Where:
- XXX = zero-padded sequential number (001, 002, ..., 099, 100, etc.)
- short-descriptive-title = kebab-case description

Examples:
- ADR-001-postgresql-for-sensor-data.md
- ADR-014-rest-api-versioning.md
- ADR-042-grpc-internal-rpc.md
- ADR-099-deprecated-static-bundling.md

Wrong:
- ADR-1-postgresql.md (not zero-padded)
- adr-001-PostgreSQL.md (lowercase prefix, mixed case)
- ADR-001_PostgreSQL.md (underscore instead of hyphen)

NEGATIVE
"This change violates ADR-NNN (Title).
Please refactor or write a superseding ADR."

POSITIVE
"This change aligns with ADR-NNN (Title). Good use of the documented pattern."

QUESTION
"This introduces a new architectural pattern.
Please create an ADR documenting the decision before merging."

STATUS NUDGE
"ADR-NNN is referenced but its Status is still 'Proposed'.
Please flip it to 'Accepted' since this PR implements it."

## ADR Compliance Checklist

- [ ] Changes reviewed against existing ADRs
- [ ] No violations of architectural decisions (or a superseding ADR is included)
- [ ] New ADR created if needed (Status: Proposed)
- [ ] ADR Status updated if this PR implements an existing ADR
- [ ] Code comments reference relevant ADRs at non-obvious enforcement sites
- [ ] docs/adr/README.md updated if a new ADR was added
- [ ] All four verification gates pass on any new or amended ADR

# ADR-XXX Title

## Status

Accepted. Date: YYYY-MM-DD.

**Decision Maker:** User: [Name or role]   <- IMPORTANT: mark as human decision

## Context

[User's problem or request]

## Decision

**User Decision:** [What the user chose]

The user explicitly chose [X] over [Y] because [reason given].

## Alternatives Considered

[What was presented to the user]

### Alternative A: [Option presented]

**User Feedback:** [User's reasoning for or against]

### Alternative B: [Option presented]

**User Feedback:** [User's reasoning]

## Rationale

**User's stated reasons:**

- Reason 1
- Reason 2

**Technical context (from the agent):**

[Agent's analysis of the decision's technical implications. Useful for future readers who want the technical lens alongside the user's intent.]

WRONG (no example)
Use idempotent retry logic.

RIGHT (concrete example)
Use idempotent retry logic. Each request includes an Idempotency-Key
header derived from the client's request body hash, and the server
deduplicates within a 24-hour window.

Example client wrapper:

```python
def submit(payload):
    key = hashlib.sha256(json.dumps(payload, sort_keys=True).encode()).hexdigest()
    return http.post("/submit", json=payload, headers={"Idempotency-Key": key})

### Diagrams when helpful

ASCII diagrams travel well across tools and reviewers.

---

## ADR Index Management

Maintain `docs/adr/README.md` as the navigation hub. Required sections:

1. **What are ADRs?** Brief explanation for new readers.
2. **Quick Navigation** with category counts.
3. **ADR Index**: full categorized list with one-line summaries.
4. **ADR Template**: link to or embed the template.
5. **Key Architectural Themes**: cross-cutting concerns referenced by multiple ADRs.
6. **Architectural Dependencies**: which ADRs depend on which.
7. **When to Create an ADR**: guidance for new contributors.
8. **Superseding ADRs**: how to handle changes.
9. **Resources**: links to ADR best practices and external references.

When adding a new ADR:

1. Add an entry under the appropriate category.
2. Update the category count in Quick Navigation.
3. Update "Foundational ADRs" if the new one is highly referenced.
4. Add cross-references in any older ADRs that relate.

---

## ADR Metrics and Maintenance

### Health indicators (healthy repository)

- All ADRs have a clear Status.
- Superseded ADRs reference their replacement.
- Code references match existing ADRs.
- README index is up to date.
- Recent ADRs include implementation dates.
- Each ADR has at least 2 alternatives documented.

### Needs attention

- Multiple ADRs with `Proposed` status for >30 days (review and accept or deprecate).
- ADR numbers with gaps (consolidate or document the gap).
- Code comments referencing non-existent ADRs (broken links).
- ADRs without an alternatives section (low quality).
- README categories that do not match actual ADRs (drift).

### Periodic review (quarterly)

---

## Quick Reference

### ADR creation checklist

```markdown
Creating a new ADR? Check these:

- [ ] Next sequential number assigned (check docs/adr/)
- [ ] Filename follows convention
- [ ] Status field present
- [ ] Date field present (YYYY-MM-DD)
- [ ] Decision Maker identified (Agent or User: Name)
- [ ] Context section explains the problem clearly
- [ ] At least 2 to 3 alternatives documented
- [ ] Pros and cons listed for each alternative
- [ ] "Why not chosen" for each rejected alternative
- [ ] Consequences section complete (positive, negative, risks)
- [ ] Code examples included (if applicable)
- [ ] Related ADRs referenced
- [ ] Implementation notes with affected files
- [ ] Added to docs/adr/README.md index
- [ ] Category assigned
- [ ] References / external links included
- [ ] Four verification gates pass

- Writing "we should use X" without explaining why
- Skipping alternatives ("this is the only way")
- No code examples for technical decisions
- Forgetting to update status after implementation
- Not referencing related ADRs
- Vague consequences ("it will be better")
- No decision maker attribution
- Missing constraints that drove the decision
- Modifying accepted ADRs instead of superseding
- Not updating README.md index
- Using jargon without defining it
- Being superficial: not digging into the "why" behind constraints
- Hiding negative consequences
- Writing marketing copy instead of honest technical analysis
- Skipping measurements ("faster" vs "68% latency reduction")
- Not explaining technical trade-offs in understandable terms