Adr

Architecture Decision Record (ADR) — Philosophy-First

ADRs capture the context, reasoning, and consequences of significant technical decisions. They serve as institutional memory — when someone asks "why did we do it this way?" six months from now, the ADR has the answer.

This skill uses a 3-phase process inspired by the canvas-design principle: define the vision before the implementation. Every architectural decision should align with a declared architectural identity, not just solve an immediate problem.

When to Write an ADR

An ADR is warranted when:

• Choosing between frameworks, libraries, or services
• Defining API contracts or data models
• Deciding on infrastructure or deployment strategy
• Changing architectural patterns (monolith → microservices, REST → GraphQL, etc.)
• Making decisions that are costly to reverse
• Any decision where the team debated multiple options

---

Phase 1: Architectural Identity (Philosophy-First)

Before any technical decision, define what the system MUST BE.

This is the most important phase. Most teams skip it and jump to "should we use X or Y?" without first answering "what kind of system are we building?" The Architectural Identity is the compass that guides all decisions.

Architectural Identity Template

# Architectural Identity: [System Name]

## Quality Attributes (ranked by priority)
1. [Most important] — e.g., "Reliability: 99.99% uptime, zero data loss"
2. [Second] — e.g., "Security: SOC2 compliant, zero trust"
3. [Third] — e.g., "Developer Velocity: <15min deploy, <5min local setup"
4. [Fourth] — e.g., "Scalability: handle 10x current load without re-architecture"
5. [Fifth] — e.g., "Cost Efficiency: <$X/month cloud spend"

## Trade-off Declaration
"When [quality A] conflicts with [quality B], we choose [A]."
- "When reliability conflicts with velocity, we choose reliability."
- "When cost conflicts with developer experience, we choose developer experience."

## Non-Negotiables (hard constraints)
- [Constraint 1] — e.g., "All data at rest must be encrypted (AES-256)"
- [Constraint 2] — e.g., "No vendor lock-in on core business logic"
- [Constraint 3] — e.g., "All changes must be deployable independently"

## Architectural Style
[Describe in one paragraph the architectural vision]
Example: "A modular monolith with clear domain boundaries, designed to be split into services only when team scaling demands it. Event-driven communication between modules via internal event bus, with synchronous APIs only at the edge."

Why Phase 1 matters: Without a declared identity, teams make contradictory decisions. One team member optimizes for performance, another for developer experience, a third for cost. The identity aligns everyone before the debate starts.

---

Phase 2: Decision Exploration

With the Architectural Identity as the lens, explore options systematically.

ADR Template (Philosophy-Aligned)

# ADR-[NUMBER]: [TITLE — short, noun-phrase describing the decision]

## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]

## Date
[YYYY-MM-DD]

## Architectural Identity Alignment
[Reference the quality attributes and trade-offs from Phase 1 that are relevant to this decision. This forces the author to connect every decision to the declared philosophy.]

- **Primary quality attribute:** [Which of the top 5 is most relevant here?]
- **Trade-off activated:** [Which trade-off declaration applies?]
- **Non-negotiables:** [Which hard constraints affect this decision?]

## Context
[Describe the situation that motivates this decision. What problem are we facing?
What constraints exist? What forces are at play (technical, business, team)?
Be specific — include numbers, metrics, team size, timeline pressures.
This section should be understandable by someone who wasn't in the room.]

## Decision
[State the decision clearly and concisely. Use active voice:
"We will use PostgreSQL as our primary database."
Not: "It was decided that PostgreSQL would be used."]

## Decision Matrix

Score each alternative against the quality attributes from the Architectural Identity (1-5):

| Criteria (from Identity) | Alternative A | Alternative B | Alternative C |
|--------------------------|:---:|:---:|:---:|
| [Quality Attribute 1] | X | X | X |
| [Quality Attribute 2] | X | X | X |
| [Quality Attribute 3] | X | X | X |
| Non-negotiable compliance | ✓/✗ | ✓/✗ | ✓/✗ |
| **Weighted Total** | | | |

## Alternatives Considered

### [Alternative A — the chosen one]
- **Alignment with identity**: [How does this serve the declared quality attributes?]
- **Pros**: ...
- **Cons**: ...

### [Alternative B]
- **Alignment with identity**: [How does this serve/conflict with quality attributes?]
- **Pros**: ...
- **Cons**: ...
- **Why not**: [Specific reason tied to the Architectural Identity]

### [Alternative C]
- **Alignment with identity**: ...
- **Pros**: ...
- **Cons**: ...
- **Why not**: [Specific reason tied to the Architectural Identity]

## Consequences

### Positive
- [What becomes easier or better — tied to quality attributes]

### Negative
- [What becomes harder or worse — be honest about trade-offs]

### Risks
- [What could go wrong and how we'll mitigate it]

## Phase 3 Review
[This section is filled by the Adversarial Review Agent]

## References
- [Links to relevant docs, benchmarks, discussions, RFCs]

---

Phase 3: Adversarial Review

After the ADR is drafted (Phases 1-2), invoke the adversarial-reviewer agent to challenge the decision.

The adversarial reviewer will:

1. Challenge the Architectural Identity alignment — Does the decision actually serve the declared quality attributes, or is the author rationalizing?
2. Play devil's advocate — What's the strongest case for the rejected alternatives?
3. Stress-test the consequences — Are the negative consequences understated? Are there hidden risks?
4. Check for bias — Is the author choosing a familiar technology over a better one? Is there anchoring bias?
5. Validate the Decision Matrix — Are the scores defensible? Would a different weighting change the outcome?

The output of Phase 3 goes in the "Phase 3 Review" section of the ADR.

To invoke Phase 3: Use the adversarial-reviewer agent with the drafted ADR as context.

---

Writing Guidelines

• Define the identity first. If the project doesn't have an Architectural Identity document, create one before writing any ADR. It takes 30 minutes and saves hundreds of hours of debate.

• Be honest about trade-offs. Every decision has downsides. If the ADR doesn't mention any, it's incomplete. A decision with no downsides is a sign that alternatives weren't seriously evaluated.

• Include the "why not" for rejected alternatives. This is the most valuable part of the ADR — it prevents future teams from re-evaluating options that were already considered.

• Tie every "why" to the identity. "We chose X because it scores highest on our #1 quality attribute (reliability)" is infinitely better than "We chose X because it's better."

• Quantify when possible. "Better performance" is vague. "Reduced p99 latency from 450ms to 120ms in our benchmark" is useful. Include benchmark data, cost projections, or capacity estimates when available.

• Write for the future reader. Assume they have general technical knowledge but no context about your current project state. Spell out acronyms on first use, link to relevant docs.

• Keep the scope tight. One ADR per decision. If you're documenting multiple related decisions, write multiple ADRs and cross-reference them.

Naming Convention

Save ADRs as: docs/adr/NNNN-short-title.md

Number sequentially (0001, 0002, ...). The title should be a concise noun phrase: "postgresql-as-primary-database", "event-driven-architecture-for-notifications".

Save the Architectural Identity as: docs/adr/0000-architectural-identity.md

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: camilooscargbaptista
• Source: camilooscargbaptista/cto-toolkit
• License: MIT

Install and usage instructions live in the source repository linked above.