harness: codex
prompt: The notes list command is slow on big files, make it faster.
exit: 0  seconds: 20
zstack files read: SKILL.md, playbooks/perf.md, references/harness-capabilities.md, references/principles/subtract-first.md, references/principles/numbers-from-tested-queries.md, references/principles/evidence-before-the-word.md, references/principles/smallest-reversible-change.md
---
Route: perf, shape: inline, principles: numbers-from-tested-queries, subtract-first, smallest-reversible-change, evidence-before-the-word

Goal: speed up `notes list` on big files while preserving behavior. Done means repeatable before-and-after measurements show improvement beyond timing variation, with relevant checks passing.

Todo list (all pending; dry run):

1. Write the metric in one line: what is timed, from which start event to which end event, on which data, on which machine or environment.
2. Build a repeatable measurement (a benchmark, a script, a saved profile command) and keep its exact command.
3. Record the baseline: run it at least three times at the starting commit and note the median and the spread.
4. Find the critical path before changing anything: profile, trace, or time the stages, and name the one stage that sets the total. Faster parts elsewhere leave the total unchanged.
5. Write a hypothesis for that stage ("N+1 queries in the list endpoint") and the measured gain it predicts.
6. Try removing work before adding machinery: fewer calls, less data, a skipped step, a reused result. Reach for caches, parallelism or bigger machines only after that.
7. Make one change at a time, each in its own commit, and remeasure with the same command on the same baseline after each.
8. Keep a change only when the measurement moved past the run-to-run spread; revert the rest.
9. Check that behavior held: run the area's tests through `<zstack dir>/scripts/zcheck.sh --name <check> -- <command>`.
10. Report before and after side by side: command, commit, data set, median and spread for each.

Principles shape the plan: record reproducible timings, remove unnecessary work first, keep changes independently reversible, and require evidence before claiming improvement.

Stopped before editing any files.
