feat(docs): ADR framework + ADR-001 stacked pull requests methodology

[scottschreckengaust]

Parent

Sub-issue 0 of #120 (RFC: Least-privilege CDK bootstrap policies as code)
This is now the first issue in the stack — precedes #121.

Branch strategy

feat/adr-framework → targets main

Estimated review time: ~20 min

Summary

Establish the docs/decisions/ ADR framework and write ADR-001: Stacked Pull Requests as the standard methodology for delivering multi-PR features. This ADR documents how stacked PRs reduce review fatigue, how each PR in a stack relates to the prior/remaining/overall goal, and how reviewers and agents should consume them.

Motivation

This repository uses stacked PRs for complex features (this RFC being the first formal instance). Without a documented methodology:

• Reviewers don't know if they're looking at a standalone PR or part of a sequence
• Agents can't determine what's already been delivered vs. what's coming
• The relationship between sub-issues, branches, and the overall goal is implicit

ADR-001 makes this explicit and referenceable.

Deliverables

ADR framework

• Create docs/decisions/README.md:
  • Purpose of ADRs (capture "why" decisions were made, not just "what")
  • Template structure (title, status, context, decision, consequences, references)
  • Numbering scheme: NNN-slug.md (zero-padded, sequential)
  • Lifecycle states: proposed → accepted → superseded → deprecated
  • Discovery: how to find ADRs (AGENTS.md routing, Starlight docs site, docs/decisions/ directory)
• Update AGENTS.md routing table: add docs/decisions/ entry
• Update docs/scripts/sync-starlight.mjs (if needed) to include decisions/ in the Starlight build

ADR-001: Stacked pull requests

• Create docs/decisions/001-stacked-pull-requests.md:

  Status: Accepted

  Context:

  • Complex features spanning 4+ files or multiple concerns are hard to review in a single PR
  • Large PRs (>500 lines) suffer from reviewer fatigue — critical issues get missed
  • Sequential PRs without a framework leave reviewers without context of where they are in the overall delivery

  Decision:
  Use stacked pull requests for multi-PR features. Each PR in the stack:

  1. States its position in the PR description:

     • "PR N of M in stack for #"
     • What the prior PR delivered (establishes baseline)
     • What this PR adds (the reviewable delta)
     • What remains after this PR (sets expectations)
     • How the overall goal is served (connects to parent RFC/issue)

  2. Branch targeting:

     • PR 1 targets main
     • PR N targets PR N-1's branch
     • Final PR merges the full stack to main

  3. Self-contained reviewability:

     • Each PR compiles, passes tests, and can be deployed independently
     • No PR leaves the codebase in a broken intermediate state
     • Each PR has a clear single responsibility (one concern per PR)

  4. Size guidelines:

     • Target: 200-400 lines changed per PR
     • Maximum: ~45 minutes of focused review time per PR
     • If a PR exceeds these, decompose further

  5. Rebase discipline:

     • When a lower PR changes after review, all PRs above it in the stack must be rebased
     • CI must pass on each PR independently after rebase

  6. Sub-issue linking:

     • Parent issue lists all sub-issues with the stack visualization
     • Each sub-issue references the parent and its position in the stack
     • GitHub's task list in the parent tracks completion

  Consequences:

  • (+) Each PR stays in the "reviewable without fatigue" window (~15-40 min)
  • (+) Agents can pick up any sub-issue independently knowing what came before
  • (+) Partial delivery is meaningful (each merged PR adds value)
  • (+) Reviewer can approve incrementally without holding full-stack context
  • (-) Rebase cascades when early PRs change
  • (-) Slightly more overhead in PR descriptions and branch management
  • (-) Requires discipline to keep each PR independently valid

  PR description template:

  ## Stack position
  
  PR {N} of {M} for #{parent-issue} — {overall goal one-liner}
  
  ### Prior (PR {N-1}): {what was delivered}
  ### This PR: {what this adds}
  ### Remaining ({M-N} PRs): {what comes next}
  
  ## Changes
  ...

  References:

  • Stacked Diffs (Pragmatic Engineer)
  • Parent RFC: RFC: Least-privilege CDK bootstrap policies as code (with preflight validation) #120

• Sync Starlight mirrors (mise //docs:sync)

Acceptance criteria

• docs/decisions/README.md is clear enough for a new contributor to write an ADR
• ADR-001 is complete and actionable — a reviewer reading it knows exactly what to expect from stacked PRs in this repo
• AGENTS.md routes agents to docs/decisions/
• Starlight docs site includes the decisions section
• mise run build passes (including docs sync)

Impact on existing sub-issues

After this merges:

• feat(bootstrap): ADR framework and least-privilege decision record #121 becomes ADR-002 (least-privilege bootstrap policies) and targets feat/adr-framework branch
• All subsequent sub-issues shift branch targets accordingly
• Each sub-issue's PR uses the template from ADR-001