Implementation Guide for ADR / Pitch / Kickoff Memos: From 'Why Write?' to Operational Design
This article was generated by AI. The accuracy of the content is not guaranteed, and we accept no responsibility for any damages resulting from use of this article. By continuing to read, you agree to the Terms of Use.
- Intended readers: EMs, tech leads, and PMOs who want to introduce ADRs, Pitches, or kickoff memos
- Assumed background: STEP 4 from “Implementation Guide for Organizational Context Supply Capability”
- Reading time: Full read about 20 minutes / skim about 7 minutes
Overview
ADRs (Architecture Decision Records), Pitch documents (Shape Up), and project kickoff memos are usually discussed in isolation. But viewed from the higher purpose of organizational context supply capability, they are the same purpose at different granularities.
This article extends STEP 4 of the sister piece “Implementation Guide for Organizational Context Supply Capability” into a standalone deep dive. It organizes the three document types in a Diátaxis-like layout and treats “why write,” “where to put them,” “when to retire them,” and “how to keep them searchable” as one coherent operational guide.
Roles and granularity of the three documents
| Document | Granularity | Primary purpose | Origin |
|---|---|---|---|
| ADR | Single judgment (one file per decision) | Preserve the context and reasoning behind past decisions | Michael Nygard 20111 |
| Pitch document | Outline of a proposal (pre-commit) | Evidence of pre-commit deliberation | Basecamp Shape Up 20192 |
| Kickoff memo | Execution agreement (at start) | Clarify roles and success conditions among stakeholders | Practiced at Stripe and similar companies3 |
The three are also temporally complementary:
1
Pitch (pre-commit deliberation) → Kickoff memo (execution agreement) → ADR (mid-flight judgment record)
ADR implementation
1
2
3
4
5
# ADR-NNN: <decision title>
## Status: proposed / accepted / deprecated / superseded by ADR-MMM
## Context: what situation requires a decision
## Decision: what was decided
## Consequences: positive impacts / negative impacts / trade-offs / follow-ups
ADR operating principles
- One decision per file. Don’t bundle several
- Sequentially numbered and immutable. Don’t edit past ADRs; record supersedes in a new ADR
- Live in the same repo as the code. Reviewed via pull request
- Write “we won’t do this” decisions too (“we evaluated Kafka and chose not to adopt” is also valuable)
- Repurpose-able for business decisions (BDRs: Business Decision Records)
Handling the “too many ADRs” problem
When ADR counts reach the hundreds, searchability degrades. Countermeasures:
- Tagging (domain / status / related project)
- Twice-yearly cleanup that explicitly deprecates stale entries
- Importance labels (critical / important / informational)
- Combine with architecture-document systems like the C4 model or arc42
Pitch document implementation
1
2
3
4
5
6
# Pitch: <proposal name>
## Problem: whose problem, what kind. One concrete example
## Appetite: how many weeks (fixed time) you're willing to spend
## Solution: outline of the solution (user-experience flow, not detailed implementation)
## Rabbit holes: places where digging into detail is dangerous; pre-decided stance
## No-gos: out of scope (push to next cycle)
The essence of the Pitch
The core of Basecamp / Ryan Singer’s Pitch document2 is fixed time, variable scope: “how many weeks (appetite) we’ll spend” is decided up front, and scope flexes to fit. This is the inverse of the implicit operating model at most organizations (scope fixed, time slips).
The act of writing itself is evidence of having thought it through. If you can’t write it, that’s a signal you shouldn’t start it yet.
Usable even without adopting Shape Up wholesale
You don’t need to adopt the entire Shape Up methodology (6-week cycles / cool-down / betting table) to use Pitch documents. “Write before you commit,” “explicitly state Rabbit holes and No-gos,” “declare a fixed appetite” — those are universally useful.
Kickoff memo implementation
1
2
3
4
5
6
7
## Project name / start date / projected end
## Problem statement
## Success conditions (measurable)
## Failure conditions (abandonment line)
## Stakeholders and roles (DRI / Reviewer / Informed)
## Milestones
## Open questions (unresolved points)
Why “failure conditions” matter
Writing failure conditions and an abandonment line up front is what prevents the later “we have to keep going because of sunk cost” state. This matches the logic of Defensive Pessimism4: simulate bad outcomes in advance and prepare the response.
Connection to Stripe’s writing culture
Brie Wolfson, a former Stripe employee, has documented Stripe’s writing culture3: project kickoff memos, a Google Group for retrospectives, “state” emails, shipped/unshipped catalogs. A quote from Stripe’s CTO captures the essence: “If you invest extra time to communicate ideas in clear, precise writing, you get disproportionate returns, because there are far more readers than writers.”
Relationship to the Diátaxis framework
Daniele Procida’s Diátaxis5 classifies technical documentation into four kinds:
- Tutorial: leads the learner (learning-oriented)
- How-to guide: steps to solve a problem (task-oriented)
- Reference: specifications and facts (information-oriented)
- Explanation: deepens understanding (understanding-oriented)
Where do ADR / Pitch / Kickoff memo sit?
| Document | Diátaxis category |
|---|---|
| ADR | Explanation (why this decision) |
| Pitch | Explanation (proposal outline) + entry point to How-to |
| Kickoff memo | Reference (record of facts and agreement) |
These do not function as onboarding tutorials for new hires (curse of knowledge6 risk). New-hire onboarding needs separate Tutorial / How-to documents. To get a system-level view of architecture, arc427 or a similar systematic template is a useful complement.
Searchability is the whole point
The greatest value of ADR / Pitch / Kickoff memo is being searchable later.
- Centralize in one repo or wiki. It’s enough to split into folders like
decisions/pitches/projects/ - File names = date + slug
- Tag (project name / domain / status)
- Twice-yearly cleanup: explicitly mark deprecated entries
Make owner and “next review” date required on every document (auto-stale mark if not reviewed). Visualize read counts (access logs); low-access entries become deprecation candidates.
Anti-patterns
| Pattern | What happens | Countermeasure |
|---|---|---|
| ADR is too abstract | Re-reading later, the context is unclear | Always include concrete names and numbers in Context |
| Pitch becomes long-form | Motivation to write erodes | Strict 1-2 page limit |
| “Every decision must be an ADR” mandate | Ritualizes | Use the test “will this be useful as decision material in 3 months?” |
| Stored in a hard-to-search location | Written but unread | Co-locate with code or centralize at wiki root |
| Number of ADRs as a KPI | Goodhart runaway, hollows out | Look at reference count, not write count |
| Kickoff memo without failure conditions | Sunk cost prevents withdrawal | Make failure conditions / abandonment lines mandatory |
| Treating Pitch as requiring full Shape Up adoption | Adoption bar set too high | Pitch is usable on its own |
Summary
- ADR / Pitch / Kickoff memo are temporally complementary: Pitch (pre-commit) → Kickoff (agreement) → ADR (mid-flight)
- One document, one purpose; searchability is the whole point
- ADR: one decision per file, sequential and immutable, co-located with code, “we won’t do this” included
- Pitch: fixed time / variable scope; if you can’t write it, don’t start it
- Kickoff memo: success conditions paired with failure conditions / abandonment lines
- Sit at Diátaxis Explanation / Reference; new-hire Tutorials are a separate workstream
- Don’t make volume a KPI (Goodhart runaway)
Related articles
- Implementation Guide for Organizational Context Supply Capability: From Facing Problems to Repair — Parent article
- Documentation Theater: Organizations That Write a Lot and Have Killed All of It — Lifecycle of documentation
- WOOP for Organizations: Institutionalizing a Personal Technique into Organizational Decisions — Combining Kickoff memos with WOOP
- Goodhart’s Law: How Documentation KPIs Hollow Out the Moment They’re Set — The runaway when ADR counts become KPIs
References
Documenting Architecture Decisions — Michael Nygard, Relevance / Cognitect (2011-11-15). [Reliability: High] ↩︎
Shape Up: Stop Running in Circles and Ship Work that Matters — Ryan Singer, Basecamp (2019). [Reliability: Medium-High] ↩︎ ↩︎2
From kickoffs to retros and Slack channels — Stripe’s documentation best practices with Brie Wolfson — First Round Review (2023). [Reliability: High] ↩︎ ↩︎2
Defensive Pessimism: Harnessing Anxiety as Motivation — Julie K. Norem, Nancy Cantor, JPSP, vol. 51, no. 6 (1986). DOI: 10.1037/0022-3514.51.6.1208. [Reliability: High] ↩︎
Diátaxis: A systematic framework for technical documentation authoring — Daniele Procida (continuously updated). The four-way classification (Tutorial / How-to / Reference / Explanation). [Reliability: Medium-High] ↩︎
The Curse of Knowledge in Economic Settings: An Experimental Analysis — Colin Camerer, George Loewenstein, Martin Weber, JPE, vol. 97, no. 5 (1989). DOI: 10.1086/261651. [Reliability: High] ↩︎
arc42 Template — Gernot Starke (continuously updated). Architecture documentation system. [Reliability: Medium-High] ↩︎