Contract for committed performance reports: what belongs here, how evidence should be linked, and how report files should be structured.
Use This Guide · What a Report Is · Chart Usage · Report Structure · Naming
Curated narrative layer · Raw artifacts remain primary · Charts support, not replace, evidence
Related docs: Performance overview · Methodology · Interpretation guide
| If you want to... | Start here | Then continue with |
|---|---|---|
| write a new committed performance report | What a Report Is | Recommended Report Structure, Naming |
| decide whether content belongs in a committed report or should stay local | What Does Not Belong Here | Performance overview |
| embed charts and artifact links correctly from a report file | Chart Usage in Reports | Relative Paths for Embedded Charts |
| see what a real report looks like in this repository | 2026-04-21 Initial Baseline | Interpretation guide |
This directory contains curated, human-authored performance reports for
arcoris.dev/pool.
A report is the final narrative layer of the performance subsystem. It links a concrete performance question to the supporting raw artifacts, comparison artifacts, profiles, and charts that were used to answer it.
A committed report SHOULD:
- answer one specific performance question;
- identify the benchmark families and execution classes it relies on;
- link to the raw benchmark artifacts it used;
- link to compare artifacts when the report is comparative;
- link to profiles when profiles materially support the interpretation;
- state whether chart values come from comparison artifacts or from an aggregated raw snapshot summary such as per-benchmark medians;
- use charts as presentation artifacts, not as a replacement for raw evidence;
- state the narrowest conclusion justified by the evidence.
This directory is not for:
- scratch notes;
- throwaway smoke-run output;
- copied raw benchmark dumps;
- unfinished conclusions without supporting artifacts;
- methodology rules that belong in the benchmark methodology guide;
- benchmark inventory that belongs in the benchmark matrix;
- interpretation rules that belong in the benchmark interpretation guide.
Reports MAY embed charts when the chart makes the evidence easier to read. Charts are presentation artifacts only.
Reports MUST still point back to the underlying artifacts, such as:
Good report chart usage:
- a small curated set of charts tied to the report question;
- per-section charts that match the benchmark family being discussed;
- explicit captions or nearby prose explaining what the chart family means.
Bad report chart usage:
- embedding every available chart;
- using charts without linking the underlying artifacts;
- treating a chart as if it were a statistical comparison by itself.
Reports in this directory sit three levels below the
repository root.
Embedded chart paths therefore need the ../../../ prefix.
Example:
Use the same rule for raw artifact links from reports:
[initial-baseline.txt](../../../bench/raw/initial-baseline.txt)A report in this directory should usually include:
- Title
- Question
- Scope
- Environment
- Evidence
- Findings
- Interpretation
- Limits
- Follow-up
Use stable descriptive file names:
YYYY-MM-DD-topic.md
Example:
| If your next question is... | Read |
|---|---|
| how the underlying benchmark artifacts should be collected | Benchmark Methodology |
| how report claims should be phrased and limited | Benchmark Interpretation Guide |
| what a real repository report currently looks like | 2026-04-21 Initial Baseline |