ADR Writer

Write ADRs that clearly capture context, decisions, and consequences.

Quick Reference

govctl adr new "<title>"
govctl adr set <ADR-ID> context --stdin <<'EOF'
context text
EOF
govctl adr set <ADR-ID> decision --stdin <<'EOF'
decision text
EOF
govctl adr set <ADR-ID> consequences --stdin <<'EOF'
consequences text
EOF
govctl adr add <ADR-ID> alternatives "Option: Description"
govctl adr add <ADR-ID> refs RFC-NNNN

ADR Structure

Every ADR has three required fields and two optional fields:

1. Context (required)

Explain the situation that requires a decision. Structure:

## Context

[1-2 sentence summary of the situation]

### Problem Statement

What specific issue are we addressing?

### Constraints

What existing RFCs, ADRs, or technical limitations restrict our options?

### Options Considered

Brief overview (details go in the alternatives field).

Key principle: A reader 6 months from now must understand why this decision was needed without asking anyone.

2. Decision (required)

State what was decided and why. Structure:

## Decision

We will **[action]** because:

1. **Reason one:** Explanation
2. **Reason two:** Explanation

### Implementation Notes

Specific guidance for implementing this decision.

Key principle: Lead with the decision, then justify. Don't bury the answer.

3. Consequences (required)

Honest accounting of trade-offs. Structure:

## Consequences

### Positive

- Benefit one
- Benefit two

### Negative

- Trade-off one (mitigation: ...)
- Trade-off two (mitigation: ...)

### Neutral

- Side effect that is neither positive nor negative

Key principle: Every decision has downsides. If your Negative section is empty, you haven't thought hard enough.

4. Alternatives (recommended)

govctl adr add <ADR-ID> alternatives "Option A: Description. Rejected: reason."

Document rejected options. Future readers need to know what was not chosen and why.

5. References (recommended)

govctl adr add <ADR-ID> refs RFC-0001
govctl adr add <ADR-ID> refs ADR-0005

Link to artifacts that constrained or informed the decision. Use plain IDs (not [[...]] syntax) in the refs field.

Writing Rules

Quality Checklist

• •Context is complete. Problem statement, constraints, and options are all present.
• •Decision is decisive. Starts with "We will..." — not "We might..." or "We could...".
• •Consequences are honest. Negative section is non-empty with mitigations.
• •Alternatives are documented. At least one rejected option with reason.
• •References link to related artifacts. Use [[artifact-id]] in content fields.

Content Field Formatting

Use markdown within content fields. Wrap code/technical terms in backticks:

# Good
decision = "Use `HashMap<String, Vec<ClauseSpec>>` for clause storage"

# Bad — angle brackets break mdbook rendering
decision = "Use HashMap<String, Vec<ClauseSpec>> for clause storage"

Common Mistakes