feat: refresh shared skills catalog

skills/benchmark-refactor/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: benchmark-refactor
+description: >
+  Measure baselines, evaluate optimization candidates in isolated branches, and record MADRs for performance-critical refactoring.
+scope: global
+---
+
+# Benchmark-driven refactoring
+
+**"The model proposes, but the engine measures."**
+Optimization and refactoring must never rely on theoretical claims or synthetic
+unit test speedups. Every performance-critical change must be empirically proven
+against a deterministic baseline.
+
+## 4-Phase refactoring workflow
+
+### 1. Baseline profiling
+Before altering any production code, establish and record the empirical baseline:
+1. Select the profiling harness appropriate for the stack:
+   - Python: `pytest-benchmark`
+   - Rust: `Criterion.rs`
+   - CLI / Compiled binaries: `hyperfine`
+   - C / C++: `google/benchmark`
+2. Run the suite under clean conditions to capture mean execution duration ($\mu$),
+   standard deviation ($\sigma$), memory overhead, and throughput.
+3. Export the baseline as a machine-readable JSON artifact (e.g. `benchmark-baseline.json`).
+
+### 2. Hypothesis & candidate generation
+1. Formulate 2–3 discrete optimization strategies (e.g. vectorization, streaming iterators,
+   in-memory caching).
+2. Implement each candidate in an isolated Git worktree or ephemeral branch
+   (`candidate-a`, `candidate-b`). Do not mutate the baseline tree.
+
+### 3. Differential benchmarking & elimination
+1. Execute the benchmark suite against each candidate under identical conditions.
+2. Apply strict statistical thresholds:
+   - Candidate is valid only if it demonstrates statistically significant gain
+     ($p < 0.01$ and $\ge 15\%$ improvement in throughput or latency).
+   - Zero regression across all unit, integration, and type checks.
+3. Immediately eliminate and hard-reset candidates that fail tests or fall below
+   the performance threshold.
+4. Select the winning candidate balancing performance gain against code complexity.
+
+### 4. Automated Architecture Decision Record (MADR)
+Refactoring without documentation produces code that future agents will revert.
+Formalize the decision by generating a Markdown Architectural Decision Record in
+`docs/adr/NNNN-[slug].md` using [the MADR template](references/madr-template.md).
+Commit the MADR alongside the refactored code and benchmark JSON outputs.
+Follow [shared verification](../../protocols/workflow.md#verification).

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

@@ -0,0 +1,45 @@
+# Markdown Architectural Decision Record (MADR) Template
+
+Save approved architectural and refactoring decisions to `docs/adr/NNNN-[slug].md`.
+
+```markdown
+# 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]
+```