global-skills/skills/benchmark-refactor/references/madr-template.md

Markdown Architectural Decision Record (MADR) Template

Save approved architectural and refactoring decisions to docs/adr/NNNN-[slug].md.

# ADR-[NNNN]: [Short Title of Architectural Decision]

## Status
[Proposed | Accepted | Superseded | Deprecated]

## Context and Problem Statement
[Describe the context, performance bottleneck, or structural limitation prompting this decision.]

## Decision Drivers
- [Driver 1, e.g. Throughput requirement: sustain >= 25,000 events/sec]
- [Driver 2, e.g. Latency target: maintain p99 < 15ms]
- [Driver 3, e.g. Interface stability: zero breaking changes to public API]
- [Driver 4, e.g. Regression safety: zero test or type check regressions]

## Considered Options
- **Option 1**: [Short description of candidate A]
- **Option 2**: [Short description of candidate B]
- **Option 3**: [Short description of candidate C]

## Decision Outcome
Chosen Option: [Option X], because [justification based on empirical benchmark results and complexity balance].

## Empirical Benchmark Outcomes
- **Baseline Execution**:
  $\mu = XX.X\text{ms} \pm X.X\text{ms}$ (Throughput: $XX,\!XXX\text{ ops/sec}$)
- **Option 1 Benchmark**:
  $\mu = XX.X\text{ms} \pm X.X\text{ms}$ ($+XX\%$ improvement; [reason if rejected])
- **Option 2 Benchmark**:
  $\mu = XX.X\text{ms} \pm X.X\text{ms}$ ($+XX\%$ improvement, $p < 0.001$; [selected])
- **Option 3 Benchmark**:
  [Eliminated due to test failure or infrastructure complexity]

## Positive Consequences
- [Positive consequence 1]
- [Positive consequence 2]

## Negative Consequences & Accepted Trade-offs
- [Negative consequence 1, e.g. Added dependency]
- [Negative consequence 2, e.g. Increased algorithmic complexity]