# Python Performance ADRs - Plan

**Created:** 2026-01-03
**Source:** python-numbers-everyone-should-know benchmarks

---

## The Three-Layer Model

```
Layer 1: Domain Papers (Exploration)
├── Full context, reasoning, benchmark methodology
├── ~2000-5000 tokens each
└── Loaded only when deep-diving into a domain

        ↓ distill

Layer 2: Rulebook (Tight)
├── Actionable rules, no fluff
├── ~200-400 tokens TOTAL
└── Loaded into every coding subagent

        ↓ formalize

Layer 3: Evals (Machine-Readable)
├── AST patterns, thresholds, rule IDs
├── For automated review agent
└── JSON/YAML, not prose
```

---

## Directory Structure

```
python-performance-adrs/
├── PLAN.md              # This file
├── README.md            # Usage for agents
├── RULEBOOK.md          # The tight rulebook (~200 tokens)
├── papers/              # Domain exploration papers
│   ├── async-overhead.md
│   ├── collection-membership.md
│   ├── json-serialization.md
│   ├── exception-flow.md
│   ├── string-formatting.md
│   ├── memory-slots.md
│   ├── import-optimization.md
│   └── database-patterns.md
├── data/
│   └── benchmarks.yaml  # Raw numbers for eval generation
└── evals/
    └── rules.yaml       # Machine-readable eval rules (future)
```

---

## Domains to Explore

| Domain | Key Insight | Priority |
|--------|-------------|----------|
| **Async Overhead** | 1400x slower than sync for simple calls | Critical |
| **Collection Membership** | Set O(1) vs List O(n), 200x at 1000 items | Critical |
| **JSON Serialization** | orjson 8x faster than stdlib | High |
| **Exception Flow** | 6x overhead when raised | High |
| **String Formatting** | f-string > % > .format() | Medium |
| **Memory/Slots** | __slots__ saves 50% memory | Medium |
| **Import Optimization** | Lazy imports for CLI startup | Medium |
| **Database Patterns** | SQLite reads fast, writes slow | Medium |

---

## Workflow

1. **Explore**: Spin up agents to analyze each domain from source benchmarks
2. **Write Papers**: Each agent produces a domain paper with full context
3. **Distill**: Extract tight rules into RULEBOOK.md
4. **Formalize**: Convert to machine-readable evals (later)

---

## Source

Benchmark data from:
- `/home/dafit/nimmerverse/references/python-numbers-everyone-should-know/`
- `the-report.md` - Main findings
- `results.json` - Raw benchmark data
- `code/` - Benchmark implementations

---

*The substrate holds. The rules compress.*