buy-vs-build-adr

name	buy-vs-build-adr
description	Use when a non-obvious buy-vs-build decision was just made and should be recorded durably, or when a project keeps a docs/decisions/ log of Architecture Decision Records (ADRs) for build/buy/reuse and dependency choices.

Buy vs Build ADR

Capture non-obvious buy-vs-build decisions as Architecture Decision Records so the reasoning — and the trigger to revisit it — survives the pull request.

When to record

Record an ADR when a decision is non-obvious or hard to reverse:

• Adding or removing a dependency.
• Choosing a commercial service over owning a capability.
• Building something in-house.
• Picking one technical option over a comparable one (for example, Server-Sent Events over WebSockets).

Skip it for obvious, trivial, easily reversible choices. An ADR is a few sentences, not an essay — it mirrors the one-line decision note the rule already produces, just durable and reviewable.

How to record

ADRs live in docs/decisions/, numbered sequentially as NNNN-title.md. Use the next free number. Either run the helper:

node scripts/record-decision.js \
  --title "Use Server-Sent Events for the live feed" \
  --rung native-platform \
  --decision "Stream updates with SSE over HTTP." \
  --rejected "WebSockets, because the feed is one-way and full-duplex is unused." \
  --revisit "the feed needs bidirectional messaging."

…or, if no helper is available, create docs/decisions/NNNN-title.md by hand with this shape:

# NNNN. <title>

- Status: Accepted
- Date: <YYYY-MM-DD>
- Rung: <do-nothing|built-in|native-platform|installed-dependency|open-source|commercial|in-house>

## Context

<requirement and constraints>

## Decision

<the option chosen>

**Tradeoff:** <why it wins>
**Rejected:** <next-best option> because <constraint>

## Consequences

Revisit if <specific trigger>.