Architecture Decision Record

A short structured document that captures a significant architectural decision, its context, and its consequences.

Architecture Decision Record

An ADR is a lightweight record of a decision that was hard to make and will be hard to change. Its value is not in the decision itself but in the reasoning: future engineers who encounter the system and wonder “why is it built this way?” have an answer that does not depend on institutional memory. An ADR is a gift to your future self and to everyone who inherits the codebase.

The canonical ADR structure is three sections: Context (what forces were at play), Decision (what was chosen and why), and Consequences (what the decision costs and what it enables). Context is not history - it is the live forces at the time of the decision that made this the right call. Consequences are not just the good ones - a good ADR honestly names the tradeoffs.

Canonical template

# [ADR-NNNN] [Decision Title]

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

## Context
[What forces were at play. The problem, the constraints, the alternatives considered.]

## Decision
[What was decided. Be specific. Name the choice, not just the category.]

## Consequences
### Positive
- [benefit]
### Negative
- [tradeoff or cost]
### Neutral
- [consequence that is neither good nor bad]

When to use

Recording architectural decisions, capturing technology choices, documenting tradeoffs for future maintainers, team alignment on significant choices.

When not to use

Operational documentation, explaining how a system works, consumer-facing content.

Pairs well with

pragmatic-architect, operator, candid, matter-of-fact, problem-solution, comparison-contrast

Often confused with

prd: A PRD defines what should be built and why. An ADR records a decision already made about how to build it.

Tells

• Three canonical sections: Context, Decision, Consequences
• A Status line (Proposed, Accepted, Deprecated, or Superseded by ADR-NNNN)
• Context names the live forces and constraints at decision time, not project history
• Decision names the specific choice, not just the category
• Consequences honestly includes a Negative subsection, not only benefits
• Short and focused, roughly 300-600 words, readable in a few minutes

Anti-patterns

• Writing Context as a history narrative instead of the live forces at decision time - Context exists to show why this was the right call under the constraints then; history does not let a future reader reconstruct the reasoning.
• Listing only positive consequences and omitting the tradeoffs - The Consequences section is where an ADR earns its value; hiding the negatives turns a decision record into marketing.
• Reserving ADRs only for rare, major decisions - ADRs should be small and numerous; the compounding smaller decisions go unrecorded if the bar is set too high.
• Describing what to build rather than recording a decision already made about how - That collides with the confusable prd format; an ADR records a made decision and its reasoning, not a product specification.

Failure modes

• Over-formalizes - a short, clear call balloons into a multi-section treatise that buries the decision it exists to record - Keep it to roughly 300-600 words; if it needs a 20-minute read, the decision is buried, so split it or move detail to a linked doc.
• Fills out the full Context/Decision/Consequences ceremony for a non-decision, so the record is all scaffold and no actual choice - Write an ADR only when there is a real, hard-to-reverse decision; if naming the Decision section feels forced, there is no ADR to write.

Instruction

Write as an Architecture Decision Record (ADR). Use the canonical three-section structure:
Context, Decision, Consequences. In Context: name the live forces at the time of decision - not
history, but the constraints, options, and pressures that made this choice necessary. In
Decision: name the specific choice, not just the category. In Consequences: be honest about the
tradeoffs - name the negative consequences alongside the positive. The Consequences section is
where ADRs earn their value. Do not omit the hard truths. Keep the document focused and short -
an ADR that requires a 20-minute read is too long.

Template

See the Architecture Decision Record template.

Related

Pairs well with

Pragmatic Architect, Operator, Candid, Matter of Fact, Problem-Solution, Comparison-Contrast

Avoid with

Pastoral, Devotional Reflection, Reverent, Warm

Often confused with

Product Requirements Document

Examples

Should we adopt async-first standups?

ADR-0014: Adopt Async-First Standup Format

Status

Accepted

Context

The engineering team has grown from 6 to 11 engineers over 18 months. The team now spans four timezones: US Pacific (3 engineers), US Eastern (3 engineers), UK (2 engineers), India (3 engineers). The current synchronous standup is scheduled at 9am Pacific, which is 9:30pm India Standard Time.

Three forces pushed this decision:

Timezone asymmetry. The India-based engineers are disproportionately burdened by the meeting schedule. Attendance data from Q1 shows the three India engineers averaged 3.2 standup appearances per week out of 5, compared to 4.6 for US-based engineers. The shortfall is not disengagement - it is 9:30pm.

Information loss. Status shared verbally in the meeting does not persist. We have documented three incidents in the past quarter where an engineer spent more than an hour on a problem that had already been solved and discussed in a previous standup. There is no searchable record.

Meeting-to-value ratio. The standup averages 14 minutes. Analysis of the past month shows an average of 4.2 minutes of content that changed someone’s behavior - a blocker raised, a dependency flagged, a context shared. The remaining 10 minutes is status that required no response from anyone.

Alternatives considered: rotating the meeting time (solves equity but adds overhead and still does not create persistence), eliminating standup entirely (loses coordination value), and adopting an async tool like Geekbot (rejected on cost and added tooling complexity - Slack templates serve the same function).

Decision

Replace the synchronous daily standup with an async standup update in #team-standup. Engineers post by 10am their local time using a pinned template:

• Shipped: what completed in the last 24 hours
• In progress: current focus
• Blocked / at risk: anything that needs attention, with @mention of the person who can resolve it

The on-call engineer reads the channel by 9am Pacific and responds to blocked items within 30 minutes during business hours. The synchronous standup slot is replaced with a 60-minute Thursday working session - not a status meeting, reserved for discussion requiring real-time exchange.

Consequences

Positive

• All engineers participate on a schedule that fits their timezone
• Status information is persistent and searchable
• Blocked items route directly to the person who can resolve them via @mention
• Engineers recover 70 minutes per week previously spent in synchronous status reporting

Negative

• Social cohesion that comes from shared daily presence is reduced; the Thursday session is a partial substitute but not equivalent
• The format depends on consistent participation - if engineers stop posting, the channel’s value drops for everyone
• Blockers that require nuance are harder to surface in a structured three-field template than in a live conversation

Neutral

• On-call rotation adds a daily channel-reading responsibility, but this replaces the meeting facilitation responsibility previously on the same rotation
• The Thursday working session is new overhead for some engineers who previously skipped standup

How to start a morning routine

ADR-001: Adopt a Structured First Hour After Waking

• Date: 2026-05-14
• Status: Accepted
• Decider: Me
• Consulted: Spouse, accountability partner

1. Context

I currently wake at 6:30am and reach for my phone before my feet hit the floor. The first 45 minutes of the day are spent scrolling Slack, email, and news. By 7:30am, family obligations begin (breakfast, school dropoff, lunches), and by 9am the work day starts. The result: I begin every weekday already reactive, already drained, and already a step behind my own intentions.

I have tried “just stop using my phone in the morning” three times in the past year. Each attempt lasted four to six days. The failures share a pattern: I removed a behavior without replacing it. The vacuum collapsed back into the old habit.

A structured morning routine is well-trodden ground. The novelty here is not the content. It is committing to a specific design and documenting why, so that future-me cannot quietly renegotiate the terms.

2. Decision

Between 6:30am and 7:30am on weekdays, I will execute a four-module morning routine in this order:

1. Water (8oz, immediately on rising)
2. Light (10 minutes outside or by the largest window available)
3. Movement (15 minutes - walk, stretch, or bodyweight)
4. Planning (10 minutes with a paper notebook, no screen)

The phone stays in the kitchen, plugged in, face down, until 7:30am.

3. Consequences

Positive

• The first hour becomes proactive rather than reactive.
• The phone-in-kitchen rule removes the decision point; I do not have to resist scrolling because the device is not within reach.
• Paper-based planning forces me to think before I touch any work tool. By 9am I arrive at my desk with a written shortlist.

Negative

• I will miss early Slack messages from West Coast colleagues. Risk accepted - urgent issues can reach me by phone call.
• The routine requires going to bed earlier. Current bedtime drift (11:30pm-ish) will need to compress to 10:30pm.
• Family mornings may need light renegotiation. My spouse’s coffee window currently runs 6:45-7:15am; I will defer conversation to 7:15am.

Neutral

• This is a one-month commitment, after which I will revisit. If module ordering proves wrong (for example, planning before movement), reorder rather than abandon.

4. Alternatives Considered

• Do nothing. Rejected. Current state is the problem.
• Wake earlier (5:30am). Rejected as premature optimization. Fix the existing hour before adding a new one.
• Use a habit-tracking app. Rejected. Adds a screen to a routine whose purpose is partly to escape screens.

5. Review

Revisit on 2026-06-14. If module completion rate is below 70 percent of weekdays, escalate to a session with the accountability partner before changing the design.

How to choose between Postgres and DynamoDB for a new service

ADR-0023: Use Postgres for the Notification Service

Status

Accepted

Context

Lattice Notify is launching a real-time notification system that needs a new persistent data store. The system will handle 500K notification events per day at launch, with a 10x growth scenario in 12 months if the pending Slack-partnership deal closes. The decision sits between two candidates:

• Option A: Postgres. Extend the existing Postgres footprint with a new schema, add a job queue, and absorb the resulting scaling work. The team has operated Postgres at this scale before. Cross-database queries against the existing monolith data stay simple.
• Option B: DynamoDB. Adopt a new datastore that fits the notification access pattern (write-heavy, point-lookups by user) and scales without operator intervention. The team has no production DynamoDB experience. Ops surface area doubles. There is no rollback plan if it goes wrong.

Three forces pushed this decision:

Team operational capacity. We have 8 backend engineers and a 4-person on-call rotation. Adding a second database adds a second runbook, a second monitoring surface, a second backup story, and a second debugging skillset on every page. We have measured this cost before in a separate workstream and it is non-trivial.

Growth uncertainty. The 10x growth scenario depends on a deal that has not closed. Designing the system for the larger scenario, when the smaller one is the certain one, optimizes for the case that may not arrive.

Reversibility cost. If we choose Postgres and outgrow it, we incur 3-6 weeks of rework to migrate. If we choose DynamoDB and find we need cross-database joins for product features, we incur similar rework plus a team that has learned the wrong tool. The asymmetry is small; both choices are recoverable.

Marcus made a strong case for DynamoDB’s access-pattern fit. Ana raised the operational capacity concern. The architecture meeting on Wednesday confirmed that the operational concern is the load-bearing one.

Decision

Build the notification service on Postgres, using a new schema (notifications) in the existing primary cluster and a job queue backed by pg_notify plus a notification_jobs table. Provision read replicas to absorb fanout reads. Add a documented threshold (5M events/day sustained) at which we revisit DynamoDB before scaling the Postgres path further.

Priya has the decision recorded for the Friday sprint planning.

Consequences

Positive

• Single operational surface for the 4-person on-call rotation. No new runbooks, no new monitoring, no new debugging skillset on call.
• Cross-database queries (joining notifications to users, accounts, workspaces) remain simple SQL.
• The team ships the launch scope on familiar ground. Estimated 3 weeks faster to first production traffic than the DynamoDB path.
• The decision is reversible: if we cross the 5M events/day threshold, we have the data and the operational margin to plan a migration.

Negative

• We will likely need to do non-trivial Postgres tuning at the 10x growth point: partitioning the notifications table, tuning the job queue, possibly sharding. This work is real and is on the roadmap, not avoided.
• Marcus’s argument about access-pattern fit is correct in isolation; we are accepting a worse fit for the access pattern in exchange for a better fit for the team’s operational reality.
• If the Slack deal closes and growth arrives faster than 12 months, we hit the rework window earlier than planned.

Neutral

• The notification_jobs table becomes a new operational concern: queue depth, dead-letter handling, retry policy. These are familiar problems on a familiar platform.
• The 5M events/day revisit threshold becomes a tracked metric. The on-call rotation owns the dashboard.

Telling stakeholders a committed feature is being cut this quarter

ADR-0027: Defer Insights Dashboard to Q1; Ship CSV Export as Q3 Stopgap

Status

Accepted

Context

The team entered Q3 with a firm commitment to ship the Insights analytics dashboard before the end of the quarter. Sales had positioned Insights as a closing point for several enterprise accounts, and three key customers had been given a delivery date.

In early Q3, the mandatory billing-system migration surfaced scope that was not visible during planning. The migration is non-optional - regulatory and contract dependencies require it to complete before year-end. The engineering work required to meet migration requirements consumed the capacity originally allocated to Insights. The two projects cannot share capacity without risking both.

Two options were on the table:

1. Ship Insights on the original Q3 date against the current state of the build.
2. Cut Insights from Q3, complete the billing migration cleanly, and move Insights to Q1.

Option 1 was evaluated and ruled out. The current Insights build is missing the saved-view persistence layer and the scheduled-report delivery feature. These are the two capabilities the committed customers specifically asked for. Shipping without them would deliver a product that fails at the exact use cases for which it was promised. Rework after a disappointing early release carries more cost than an honest delay.

A partial stopgap is available. The underlying data that Insights will eventually surface is already queryable from the data layer. A CSV export of that data can ship before the end of Q3 without material engineering risk and with a few days of integration work.

Decision

We defer the Insights dashboard to Q1 next year. Before the end of Q3 (target: September), we ship a CSV export of the Insights data layer so that customers can analyze their data in a spreadsheet or BI tool of their choosing while the full dashboard is under development.

Sales and the affected customers will be notified directly and given the CSV export date and the Q1 commitment. The Insights scope for Q1 will be confirmed in the Q4 planning cycle.

Consequences

Positive

• No half-built feature ships. The Q3 commitment was for Insights with saved views and scheduled reports; releasing without those would not deliver the value that was sold.
• The billing migration completes without schedule pressure from a competing workstream, reducing defect risk from context switching.
• The CSV export gives customers immediate access to their data with no install or onboarding requirement. Some customers may find it sufficient for their current workflow.
• Q1 gives the team time to build Insights to the committed spec without scope shortcuts.

Negative

• The Q3 commitment to sales and key customers is broken. Trust repair is required and will take direct communication, not just a status update.
• The CSV export is a weaker experience than the dashboard. Customers must supply their own tooling to filter, visualize, and schedule reports against the exported data.
• The Q1 target is a directional commitment. It is not backed by a closed capacity plan until Q4 planning completes. Stakeholders should be told this clearly.

Neutral

• The Insights feature scope is frozen at the Q3 spec for now. Requests for scope changes during the deferral period are queued for Q1 planning; none will be folded in silently.
• Customer-facing messaging about the change is owned by Sales and customer success. Engineering provides the technical facts; messaging decisions are theirs.

Getting a new engineer productive in their first two weeks

[ADR-0023] Structured Guided Pairing for New-Engineer Onboarding

Status

Accepted

Context

We ship to production every day. Our on-call rotation means every engineer on the team carries pager load proportional to their system knowledge. When a new engineer joins, they need credentials, repository access, tooling configuration, and enough codebase familiarity to contribute safely - and they need it within two weeks, because the team’s capacity to absorb sustained hand-holding degrades fast.

Two failure modes repeat when we skip structure:

First: The new hire spends week one solving access and tooling problems independently, feeling blocked but reluctant to interrupt busy teammates.

Second: The new hire ships their first change in week three or four. By then, whether they feel they belong has been decided largely by the silence of the preceding weeks.

A third constraint: the delivery cadence does not pause for onboarding. A buddy cannot spend the full day with a new hire without a real cost to their own output. Any protocol must account for this, not pretend it away.

Alternatives considered: unstructured “sit beside someone and absorb”; fully written runbook with no paired work; assigning onboarding to the tech lead rather than a peer buddy.

Decision

We will run a structured two-week guided pairing protocol with a named buddy, explicit daily check-ins, and a pre-scoped “first real change” task handed off on day one. The protocol covers three domains:

1. Access and tooling (days 1-2): The buddy owns a printed checklist. No item is considered done until Priya has verified it herself.

2. Codebase orientation (week one): Two 90-minute guided walkthroughs - one on the service topology, one on the deployment and on-call tooling. Notes belong to Priya; the buddy does not maintain them.

3. Paired first change (week two): The team picks the task before Priya’s first day. Scope constraint: one service, no on-call risk if the change goes wrong. Priya drives; the buddy reviews and pairs on blockers.

We will not wait for the new hire to self-identify her first contribution. The team owns that decision in advance.

Consequences

Positive

• Priya’s name appears in the deployment log before the end of week two. The team’s perception of her, and her perception of herself, shifts accordingly.
• The buddy checklist means access and tooling problems have a named owner. They stop falling into a silent gap.
• Belonging is given structure rather than being left to chance - the protocol designs for it rather than hoping it emerges.

Negative

• The buddy loses roughly 30-40% of their capacity in week one and 15-20% in week two. This is a real cost. Sprint planning must account for it explicitly, or the protocol fails silently.
• Pre-scoping the first change before Priya arrives requires coordination the team may skip under sprint pressure. If the task is not ready on day one, the protocol’s week two collapses.
• If the pre-scoped task blocks unexpectedly (service churn, shifting dependencies), there is no baked-in fallback. The buddy improvises, which introduces variance the checklist cannot cover.

Neutral

• The buddy relationship created here does not automatically end at two weeks. It tends to become an informal mentorship channel. The team should expect this and treat it as a feature, not drift.
• Priya is explicitly excluded from the on-call rotation for her first 30 days. This protocol does not change that rule; it operates within it.

Writing to thank a mentor who shaped your career

ADR-0001: Sponsor the Junior Analyst as Project Lead on the Meridian Rebuild

Written to Dana Okafor, with ten years of compounding interest.

Status

Accepted - decision made Spring 2015; consequences still active.

Context

At the time, the Meridian customer data rebuild needed a project lead. The scope was real: six months, cross-functional, and visible to senior stakeholders. The organization expected someone who had already run a project at that scale.

I had not.

You had your own team to manage, your own delivery commitments, and your own reputation to protect. The safer call was to name an established mid-level person. I would have understood - I was not lobbying for the role. I did not know enough yet to know I should want it.

The live forces at the time:

• The team needed a lead who would be fully accountable, not a proxy carrying someone else’s decisions
• I had demonstrated enough in smaller work to show the aptitude, but I had no track record at this scope
• You would absorb the downside if the project went badly - questions about your judgment, not mine
• A co-lead arrangement would have given me the title without the actual weight of the calls, which would have taught me nothing

Decision

You put my name forward as the project lead. Fully. Not as a stretch assignment with an invisible ceiling that would close the moment I hesitated on a real call. You stayed close through the first several months - answering questions, asking sharper ones back, naming the things I wasn’t seeing - and then stepped back when I found my footing. You did not take over when taking over would have been faster. You let me carry it.

Consequences

Positive

• I grew faster in those six months than any formal development program could have produced
• The Meridian rebuild shipped, and the team had a lead who was genuinely accountable for the outcome
• I built a pattern of working under real stakes, not simulated ones
• That pattern became the primary way I think about developing the people I now manage

Negative

• You carried the reputational exposure for the full duration - if the project had failed, what the organization would have remembered is that you vouched for someone who was not ready
• You spent time you did not have, absorbing questions and holding space for my uncertainty, without being able to show that cost on any delivery plan
• The patience required to watch someone struggle through something you could have solved in an afternoon is not a small thing; I did not fully appreciate what it cost you until I found myself in the same position

Neutral

• The Meridian system itself was replaced three years later. What persists is not the artifact but the decision pattern demonstrated in building it.

---

I am writing now because last month I put someone on my team forward for a project she did not feel ready for. I stayed close, asked the sharper questions, held back when holding back was harder than stepping in. It went well.

Somewhere around week four of that project I realized I had learned exactly how to do that from you.

The ADR format records a decision so that the people who inherit the system understand why it was built the way it was. You built something in me. I thought the reasoning deserved a record.

Reflecting on keeping a discipline of rest

[ADR-0001] Commit to One Full Day of Rest Per Week

Status

Accepted

Context

For several years, I have structured my weeks around continuous availability and output. The expectation - partly self-imposed, partly structural - is that a productive person works until work is done, and work is never done. I have tried versions of a rest day before. Each attempt collapsed within a few weeks. The pull to check one more thing, to stay ahead of messages, to feel on top rather than behind, won every time. Rest felt like a liability rather than a resource.

The forcing conditions are now different. I have observed that weeks where I work through what should be rest leave me slower, not faster. Decisions take longer. I repeat analysis I should have done once. Patience for difficult problems narrows. The quality of my judgment late in a work stretch is measurably worse than at the start of one. These are not feelings - they are patterns visible by comparing weeks.

Alternatives I considered:

• Continue the current pattern, accepting degradation as a cost of staying current.
• Build in micro-recovery (capped evenings, short walks) without committing to a full day.
• Commit to one full day off each week - completely, not “mostly.”

Micro-recovery was already in place and had not changed the patterns described. The first option is not a choice so much as a default I had been living without naming it.

Decision

I will keep one full day of rest each week - one in seven. On that day: no work output, no task completion, no checking of messages or notifications. The day is not a lighter workday. It is a structurally different kind of day.

This is not a rule about what I must do on the day. It is a rule about what I will not do.

Consequences

Positive

• The remaining six days carry a different quality of attention. The rest is not lost time - it is what makes the other time worth spending.
• Decision quality improves when a decision follows rest rather than arriving at the tail of a long stretch.
• The rhythm of one-in-seven creates a natural unit for reviewing whether the week’s direction was right, without requiring dedicated calendar time.
• Willingness to sit with a hard problem - rather than reaching for the nearest shortcut - increases.

Negative

• Some things will be slower to respond to. The discomfort of knowing a message went unread for a day does not disappear immediately; it has to be sat with.
• The day can feel anxious at the start, particularly when something unresolved is waiting. That anxiety is real and does not pass quickly in the early attempts.
• Others notice the gap in availability and ask about it. An explanation is required, and the explanation needs more words than most people expect.

Neutral

• The shape of the week shifts. Activities that previously filled the seventh day have to find room in the six.
• What counts as rest will continue to require judgment. Not everything that is not work is restful.

Marking a long-serving colleague's departure

[ADR-0047] Backfill and Knowledge Architecture Following Howard’s Departure

Status

Accepted

Context

Howard Kessler is retiring after twenty-six years with Meridian Systems. He held the same position - Senior Operations Coordinator - for the last nineteen of those years while the organization around him was restructured three times and lost roughly half its institutional knowledge in two rounds of reductions.

Howard did not accumulate authority. He accumulated clarity. When a vendor contract dispute surfaced in late 2019 and the team lead who had owned that relationship was gone, Howard produced the original scope-of-work, the 2017 amendment, and the name of the right contact at the vendor. When a production incident required a rollback that our documented runbook no longer matched due to a platform migration nobody had fully recorded, Howard sketched the actual system state from memory on a whiteboard. He was correct.

He also kept junior members from making expensive mistakes - quietly, without making anyone feel corrected. Three people on this floor have said, separately and unbidden, that Howard is the reason their career at Meridian survived the first two years.

We have an approved backfill budget and a formal job requisition. The forces at play now:

• The institutional memory Howard carried is largely unwritten and cannot be extracted in his remaining weeks.
• His informal mentoring function has no defined owner and no formal acknowledgment anywhere in our org structure.
• His steady, unflappable presence during crises was itself a stabilizing input to decisions made under pressure. That is not a deliverable we can assign to a job description.
• A replacement into his formal role will cover the operational coordination load, but will not carry what Howard carried.

Decision

We will fill the posted position and we will not treat that backfill as equivalent to Howard’s departure. The new hire covers real work that must continue.

We will also stand up a quarterly knowledge capture practice - not a one-time documentation sprint. Team leads will record the decisions and constraints that shaped each major area of operations. We are naming this practice after what it actually is: it exists because Howard is leaving and we have now confirmed we had a single point of memory.

We will designate informal mentoring as an explicit expectation for two senior individual contributors, without creating a formal “mentor” title, because that title has historically read as sidelining rather than recognition at Meridian.

Consequences

Positive

• Operational coordination work continues without a queue gap.
• The quarterly knowledge capture practice, if sustained, reduces single-point-of-memory risk over time across all senior departures, not only Howard’s.
• Naming the gap honestly gives leadership a real picture rather than a false assumption that a backfill closes it.

Negative

• The new hire will carry missing context for at least the first year. We are accepting this rather than pretending we can prevent it.
• The knowledge capture practice requires scheduled senior time that is currently unallocated. The opportunity cost is real and will be felt.
• No one will replace Howard as a calming presence when something breaks at 11 p.m. That capability does not reconstruct by process. We will be less stable in those moments for a while.

Neutral

• Howard’s vendor relationships will transfer during a negotiated handoff period. Those relationships will change in character. That is not a problem to solve; it is a fact to manage.

Marking the team shipping a hard, long project

ADR-0017: Rebuild Checkout as a Parallel System with Incremental Traffic Migration

Status

Accepted - 2025-02-14 Milestone closure recorded - 2026-06-25

Context

Cart abandonment had been elevated for three years. Instrumentation pointed to the payment flow as the primary contributor, but the existing checkout system was not safely modifiable: it had grown through five years of emergency patches, carried no meaningful test coverage, and was tightly coupled to the session layer in ways the team did not fully understand. Two previous attempts to refactor it in place had stalled and been abandoned.

Three options were evaluated in early 2025:

1. Continue incremental patching - estimated 18 months to reach a maintainable state, high regression risk throughout, no guarantee of reaching cart-abandonment targets.
2. Big-bang replacement - build a new system and cut over in a single release window. Lower ongoing maintenance burden but no rollback path if the new system failed under real load.
3. Parallel-run replacement - build the new system alongside the existing one, route traffic incrementally by cohort, and keep the old checkout live as a fallback until the new system proved itself under production conditions.

Option 3 was the most expensive to build and operate. It required maintaining two live checkout systems simultaneously, with dual instrumentation, two on-call runbooks, and session compatibility across the boundary. The team would carry that operational overhead for the full duration of the migration.

Engineering lead Priya Nakamura and PM Linh Tran recommended Option 3. Priya’s argument: the only way to validate a system built to handle checkout load is to route real checkout load through it. Without a live fallback, the team would have one shot. With a parallel run, they could roll back cohorts without a site incident if something broke.

Decision

We will rebuild the checkout flow as a separate service, route traffic incrementally by user cohort starting at one percent, and decommission the old system only after the new service has handled at least two peak-load periods without incident.

Consequences

Positive

• The new checkout held without degradation under the two highest-traffic periods on record. Cart abandonment dropped in the migrated cohort before full cutover, confirming the hypothesis with live data.
• The rollback capability was exercised in October and December 2025, both times without customer-visible impact. The parallel architecture made those recoveries fast and contained.
• Future changes to the checkout flow now have a tested, instrumented baseline. The codebase no longer depends on undocumented session coupling.

Negative

• The team maintained two live checkout systems for fourteen months. This was not free: it cost engineering bandwidth, complicated incident response, and required sustained attention from backend engineer Dev Okonkwo and infra lead Marcus Ferreira throughout the run. The full cutover slipped twice as near-miss recoveries and integration work consumed the planned launch windows.
• The parallel-run period produced no visible features. The work was largely invisible to the rest of the organization, which made it difficult to communicate progress or protect the team’s capacity.

Neutral

• ADR-0018 records the decommission schedule for the legacy checkout system.
• Session compatibility shims built for the migration remain in place and will require explicit removal after decommission completes.

Arguing a public position on return-to-office

[ADR-0012] Work Location Policy - Anchor-Day Hybrid

Status

Accepted

Context

The organization has been operating under loosely defined “flexible” arrangements since offices reopened. That ambiguity has now produced two distinct and incompatible pressures.

A coalition of senior leaders argues that organic collaboration has atrophied. Trust formation among newer hires is slower than it was before distributed work became the default. Some decisions that used to resolve themselves in a corridor conversation now languish in threads. The concern is not nostalgia - it is operational. Projects with mixed tenures are showing coordination drag that correlates with teams that have never shared a room.

At the same time, a significant number of individual contributors and mid-level employees have built their lives around remote flexibility. They have relocated, restructured childcare, and accepted roles at this organization because the arrangement was described as sustainable. A policy shift is not a minor adjustment for them.

A third force: we are competing for talent in markets where we have no physical office. Any policy requiring five days in office eliminates entire candidate pools and forecloses hires we cannot make otherwise. We have experienced this constraint directly in the last two hiring cycles.

The three options considered:

1. Full in-office, five days per week
2. Fully flexible, no required presence days
3. Structured hybrid with mandatory shared anchor days and flexible remaining days

Full in-office resolves the collaboration concern but breaks commitments made during hiring and prices us out of non-local talent. Fully flexible preserves optionality but does not address the coordination and trust formation problem that leaders have named with enough specificity to take seriously. Option 3 does not make either side fully satisfied, which is the expected outcome when both sides are describing real costs.

Decision

We adopt a structured hybrid: two mandatory anchor days per week (Tuesday and Thursday) where all employees who can physically reach an office are expected to be in one. The remaining three working days are fully flexible - each person decides individually where to work.

Anchor days are the load-bearing structure of this policy. They are not preference days. Employees in roles that are defined as remote-eligible at hire are explicitly excluded; all others require a documented exception approved by their manager and the people team.

Consequences

Positive

• Anchor days create predictable, recurring windows for in-person collaboration without requiring constant physical presence
• People in focus-heavy roles recover two to three days of commute time per week for sustained, uninterrupted work
• The organization retains the ability to recruit from geographies without a local office, which is a real competitive advantage we would lose under full in-office

Negative

• Employees who structured their lives around full flexibility face genuine disruption; two days a week in office is not a small ask for someone who relocated
• We will lose some candidates and possibly some current employees who will not accept any mandatory presence requirement; that is a real and foreseeable cost
• Enforcement will be inconsistent across managers. The most likely failure mode is not defiance - it is drift, where anchor days erode quietly until they are no longer anchor days

Neutral

• Office real estate footprint stays constant in the near term; this policy does not justify reduction or expansion on its own
• Team rituals and one-on-ones will concentrate on anchor days, which compresses scheduling on Tuesdays and Thursdays
• The policy takes a position; it does not create consensus. The underlying disagreement about the right amount of in-person time remains unresolved

Announcing a new product to an outside audience

ADR-0042: Lead the Tidemark Launch Announcement with the Problem, Not the Feature Set

Status

Accepted

Context

Tidemark ships next week. It ingests customer feedback from wherever a team has been accumulating it - a spreadsheet, a chat thread, a ticket tracker - and produces a single ranked, shareable roadmap view.

At launch, one announcement will reach three distinct audiences: prospective users who have never heard of Tidemark, press contacts who will determine how the product is categorized, and a small group of existing beta customers who already have opinions. Their needs diverge, but they will read the same text.

The central tension is that Tidemark does several things. It collects, synthesizes, ranks, and surfaces feedback as a roadmap. We could announce it as any one of those functions. Roadmap software is an established category. Feedback management is an established category. Neither fully describes the workflow Tidemark handles, and defaulting to either invites reviewers to slot Tidemark into a bucket it does not quite fit.

Three approaches were weighed:

1. Lead with the product category: “Tidemark is a roadmap tool.” Familiar framing, easy to scan, but undersells the synthesis step and invites direct comparison to tools that do only the roadmap side.
2. Lead with the team outcome: “Tidemark helps teams ship the right things faster.” Aspirational, but too vague to tell a prospective user what the product actually does. Press cannot categorize it from that sentence alone.
3. Lead with the problem: “Customer feedback piles up in spreadsheets, chat threads, and ticket trackers with no shared view of what matters most. Tidemark turns it into a ranked, shareable roadmap.” Concrete, honest, and names the gap rather than a category.

A fourth option - describing only the input side and treating the ranked roadmap as a secondary detail - was rejected because it positions Tidemark as a research aggregator rather than a decision-support tool.

Decision

The launch announcement leads with the problem (scattered feedback, no shared ranked view) and resolves it with one specific description of what Tidemark produces: a ranked, shareable roadmap. We do not position Tidemark inside any named tool category. We do not enumerate capabilities beyond the core workflow. The call to action is a free trial signup with no sales-call gate.

Existing beta customers receive a separate, direct note that acknowledges their early involvement. The launch announcement is not written for them.

Consequences

Positive

• Problem-led framing reaches the prospective users most likely to convert: small teams already frustrated with how they handle customer feedback today.
• Naming one workflow (feedback in, ranked roadmap out) keeps the announcement scannable and prevents it from reading as a feature inventory, which loses both press and casual readers.
• A free-trial CTA reduces the commitment threshold for the largest segment and avoids making first contact a sales interaction.
• The positioning holds consistently across the press release, the product site, and any partner channels without internal contradiction.

Negative

• Teams with adjacent pain (general prioritization work that is not specifically feedback-driven) may not recognize themselves in the announcement and may never try Tidemark.
• Press will categorize the product regardless of our framing. We can slow the “just another roadmap tool” read; we cannot prevent it.
• Beta customers who think of Tidemark differently from the launch framing need explicit outreach. If we omit that step, the announcement can feel like a redefinition of something they helped build.

Neutral

• This decision fixes the anchor language before any press coverage runs. Shifting the positioning after that point requires active re-framing effort; it does not happen by updating one page.
• The free-trial CTA commits the product team to a working self-serve onboarding flow on launch day. That dependency is not visible in the announcement copy, but it is real.

A personal year-end reckoning with a difficult year

[ADR-0001] Continue Toward Exposure Rather Than Retreat

Status

Accepted

Context

In the past year, two load-bearing commitments failed simultaneously. The Meridian project - a two-year effort to build a resource-sharing platform for independent educators - was sunset by the foundation that funded it. The work was not poor; the foundation’s priorities shifted. No amount of effort on my part would have changed the outcome. I did not know this until months after I had escalated my own investment, working longer and later under the assumption that the effort gap was mine to close.

Separately, a long friendship with someone named Cassiel shifted in ways I did not choose and cannot fully account for. The distance is mutual now but it was not mutual in origin. I got something wrong, or they changed in ways I could not track, or both. I still do not have a clean narrative.

The forces at play when I began this review:

• Fatigue from sustained effort that did not produce its intended outcomes
• A tendency to interpret loss as evidence of a solvable error (if I had just worked harder, communicated better, held on differently)
• A competing pull toward reducing exposure: narrowing what I commit to, investing shallowly so there is less to lose
• Recognition that both the project and the friendship were genuinely worth the investment, regardless of outcome

The alternatives I considered:

1. Reframe the year - find the hidden gifts, produce a tidy growth narrative
2. Protect forward - decide that the pain was a signal to limit scope, depth, and attachment
3. Accept the record as it is and make a deliberate, eyes-open choice about what I carry forward

Option 1 is not honest. Option 2 is a form of decision I am already drifting toward by default, which makes it worth naming explicitly as a choice rather than letting it harden into a posture.

Decision

I will not restructure my orientation toward work and relationships around the risk of loss.

This year did not reveal that deep investment is a mistake. It revealed that deep investment is costly when it does not pay off, and that the cost is real. I will not pretend otherwise. That is not the same finding as “do not invest deeply.”

I am choosing to carry forward the capacity for full commitment, knowing that this year is evidence of what full commitment can cost - not evidence that it should be avoided.

I am releasing the search for a clean narrative about Cassiel. I do not know what happened, and manufacturing a story will cost more than the uncertainty.

Consequences

Positive

• I do not end the year by deciding that effort is a fool’s game, which would compound the loss
• The capacity to commit fully to the next meaningful work remains intact by choice, not by inertia
• Releasing the narrative search about Cassiel frees attention that has been spent on reconstruction

Negative

• This choice does not reduce the risk of the same kind of loss in the next cycle
• Choosing not to protect also means accepting future costs that a narrower approach might avoid
• The unresolved questions about Cassiel remain unresolved; this decision settles my response to them, not the questions themselves

Neutral

• The Meridian work is over and what it was does not depend on anyone else acknowledging it
• The friendship changed; how I carry that going forward is mine to decide regardless of what Cassiel decides

Appears in diff-pairs

• adr vs meeting-notes (varies format)
• adr vs prd (varies format)
• adr vs whitepaper (varies format)