codeflash-agent/plugin/references/shared/pr-body-templates.md

PR Body Templates

Fill-in-the-blanks templates for optimization PRs. Pick the variant matching your domain, fill in {{PLACEHOLDERS}}, and remove any sections that don't apply.

Key: codeflash compare generates ready-to-paste markdown — E2E timing table, per-function breakdown, memory table (when available), improvement bars, and the "Generated by codeflash optimization agent" footer. Paste its output directly into the {{CODEFLASH_COMPARE_OUTPUT}} placeholder. The only thing the agent adds on top is {{PLATFORM_DESCRIPTION}} (machine specs + Python version), since codeflash compare does not include platform info.

---

CPU / Data Structures / Async Variant

{{SUMMARY_BULLETS}}

{{TECHNICAL_DETAILS}}

## Benchmark

### {{PLATFORM_DESCRIPTION}}

{{CODEFLASH_COMPARE_OUTPUT}}

<details>
<summary><b>Reproduce the benchmark locally</b></summary>

```bash
# Full comparison (timing + memory if --memory was used):
{{RUNNER}} -m codeflash compare {{BASE_REF}} {{HEAD_REF}} {{CODEFLASH_COMPARE_FLAGS}}

# Or manually with pytest-benchmark:
git checkout {{BASE_REF}}
{{RUNNER}} -m pytest {{BENCHMARK_PATH}} --benchmark-save=baseline

git checkout {{HEAD_REF}}
{{RUNNER}} -m pytest {{BENCHMARK_PATH}} --benchmark-compare=0001_baseline

{{CHANGELOG_SECTION}}

Test plan

• {{TEST_ITEM_1}}
• {{TEST_ITEM_2}}

---

## Memory Variant

Use when `codeflash compare` is not available and you're profiling with memray directly. If `codeflash compare` IS available, use the CPU variant — its output already includes the memory table.

```markdown
{{SUMMARY_BULLETS}}

{{TECHNICAL_DETAILS}}

## Benchmark

### {{PLATFORM_DESCRIPTION}}

#### Memory

| Ref | Peak Memory | Allocations | Delta |
|:---|---:|---:|:---|
| `{{BASE_REF}}` (base) | {{BASE_PEAK}} | {{BASE_ALLOCS}} | |
| This PR (head) | {{HEAD_PEAK}} | {{HEAD_ALLOCS}} | {{MEMORY_DELTA}} |

---

*Generated by codeflash optimization agent*

<details>
<summary><b>Reproduce the benchmark locally</b></summary>

```python
{{COMPARE_MEMORY_SCRIPT}}

Or manually:

# Base
git checkout {{BASE_REF}}
{{RUNNER}} -m memray run --native --trace-python-allocators -o /tmp/base.bin {{BENCHMARK_SCRIPT_PATH}}
{{RUNNER}} -m memray stats /tmp/base.bin

# Head
git checkout {{HEAD_REF}}
{{RUNNER}} -m memray run --native --trace-python-allocators -o /tmp/head.bin {{BENCHMARK_SCRIPT_PATH}}
{{RUNNER}} -m memray stats /tmp/head.bin

{{CHANGELOG_SECTION}}

Test plan

• {{TEST_ITEM_1}}
• {{TEST_ITEM_2}}

---

## Writing Guidelines

Write PR descriptions like a human engineer, not a summarizer:
- **Be specific**: "Replaces HuggingFace's RTDetrImageProcessor with torchvision transforms to eliminate 110 MiB of duplicate weight loading" — not "Improves memory efficiency of image processing."
- **Lead with the technical mechanism**, not the benefit. Reviewers want to know WHAT you did, not that it's "an improvement."
- **No generic headings** like "Summary", "Overview", "Key Changes" unless the PR template requires them. If the change is simple enough for 2 sentences, use 2 sentences.
- **Don't over-explain** the problem. Assume the reviewer knows the codebase. Explain WHY your approach works, not what the code does line-by-line.

## Placeholder Reference

| Placeholder | Description | Example |
|:---|:---|:---|
| `{{SUMMARY_BULLETS}}` | 1-3 bullet points: what changed and why. Lead with the technical mechanism. | `- Replace per-character regex with str.translate()` |
| `{{TECHNICAL_DETAILS}}` | Why the old version was slow, how the new version works. Assume reviewers know the codebase. Omit if the summary bullets are sufficient. | |
| `{{PLATFORM_DESCRIPTION}}` | Machine spec + Python version. `codeflash compare` does not include this — you must add it. | `Azure Standard_D8s_v5 — 8 vCPU Intel Xeon Platinum 8473C, 32 GiB RAM, Python 3.12` |
| `{{CODEFLASH_COMPARE_OUTPUT}}` | Paste the markdown output from `codeflash compare` directly. Includes E2E table, per-function breakdown, memory table, improvement bars, and footer. | |
| `{{BASE_REF}}` / `{{HEAD_REF}}` | Git refs compared | `origin/main` / `codeflash/optimize` |
| `{{RUNNER}}` | Python runner from setup.md | `uv run python`, `python`, `poetry run python` |
| `{{BENCHMARK_PATH}}` | Path to pytest-benchmark test file | `tests/benchmarks/test_benchmark_quotes.py` |
| `{{CODEFLASH_COMPARE_FLAGS}}` | Extra flags passed to `codeflash compare`. `--memory` for memray profiling. Omit if timing-only. | `--memory` |
| `{{COMPARE_MEMORY_SCRIPT}}` | Full self-contained `compare_memory.py` script (memory variant only, when `codeflash compare` unavailable) | |
| `{{CHANGELOG_SECTION}}` | Changelog entry if the target repo uses one. Omit entirely if not applicable. | `## Changelog\nAdded entry in CHANGELOG.md under 0.22.13.` |
| `{{TEST_ITEM_N}}` | Specific test results | `Existing unit tests pass`, `All 36 quote codepoints covered` |
| `{{BASE_PEAK}}` / `{{HEAD_PEAK}}` | Peak memory from memray stats (memory variant only) | `72.0 MiB` / `47.0 MiB` |
| `{{BASE_ALLOCS}}` / `{{HEAD_ALLOCS}}` | Allocation count from memray stats (memory variant only) | `124` / `118` |
| `{{MEMORY_DELTA}}` | Memory change with emoji (memory variant only) | `🟢 -35%` |