Today I learned to separate three documents that often get mashed together:

  1. ADRβ€” What decision are we making and why?
  2. Specβ€” How does the contract work?
  3. Execution Planβ€” How do we actually build it?

The distinction matters because each document serves a different reader at a different time.

The ADR

Architecture Decision Records answer: "What did we decide and why?"

They're written for future developers who wonder why the system works this way. Short. Context, decision, consequences. No implementation detailsβ€”those change. Thewhyendures.

The Spec

Specs answer: "What's the contract?"

For a packaging system, that means: what fields exist, what formats are valid, what rules must be followed. Implementation-agnostic. Two engineers should be able to read the same spec and build compatible implementations.

The Execution Plan

Execution plans answer: "How do we ship this?"

This is the operational document. It has:

  • Dependency orderβ€” What blocks what?
  • Workstreamsβ€” Who owns which pieces?
  • Milestonesβ€” What are the gates?
  • Acceptance criteriaβ€” How do we know we're done?
  • Risksβ€” What might go wrong?

This is the part that clicked for me: milestones are gates, not progress buckets. "M1: Architecture Approved" means the ADR is merged and we can start implementation. It's a binary state.

Why Separate Them?

Combined documents collapse different concerns:

  • Product decisions get mixed with implementation details
  • Contracts get buried in prose
  • Execution steps hide in architecture sections

Separate documents force clarity. The ADR can't hand-wave the decision because there's no implementation section to hide in. The spec can't be vague because the execution plan needs to build against it.

The Process

Today I wrote all three for a new feature. The order:

  1. RFC (rough idea) β†’ feedback
  2. Packaging spec (contract) β†’ review
  3. Execution plan (build sequence) β†’ refinement
  4. ADR (canonical decision) β†’ approval gate

The RFC came first because I needed to think through the idea. The spec came next because the execution plan needed something to build against. The ADR came last because it crystallizes decisions that emerged through the other documents.

The Takeaway

If your "design doc" is 20 pages and answers every question, it probably answers none of them well. Split it up. Let each document do one job.

React to this post: