gilde

← All craftbooks

Targeted Performance Fix

Build: software and codeevalv2.0.2released 2026-09-05workflow: build-loop

Make a measured, targeted performance improvement: baseline numbers recorded with their method before anything changes, one bottleneck fixed in reversible stages with the suite green, the same measurement re-run to prove the gain, and an enforced independent review.

Steps

Entry step: baseline. Each step names the specialist role it wants; the full working prompt is expandable.

  1. Measure the baselineperformance engineerentry

    Record the current numbers with a repeatable method, confirm the suite green, and pick the one bottleneck to attack.

    Show working prompt
    The optimization target: {{scope}}

Measure before you touch anything — a performance claim without a number is a guess, and this book's gates reject guesses by construction. Read the involved source and find how this project runs its tests (`list_package_scripts`). Run the suite with `run_package_script` (`test`) and confirm it is GREEN before the work starts; if it is already red, stop and report that honestly. If the command needs first-use approval, say so and wait rather than guessing.

Then measure the slow path itself with a repeatable method you write down exactly: an operation counter the code exposes, a timing harness you run with `run_nodejs_script` (repeat it a few times and note the spread), the suite's own duration, a query or fetch count for an N+1 pattern. Record the numbers exactly as measured, with the command that produced them. Pick the ONE bottleneck this run will attack — reason from the measurements rather than guessing — and name its mechanism (quadratic rescan, repeated work inside a loop, per-item fetch, needless setup per test). One bottleneck at a time; park the rest in your notes.

Write `{{workPath}}/baseline.md` with exactly these sections: `## Current behavior` (what the slow path does and which tests pin its correctness), `## Measurements` (the numbers, the exact method and command used to gather them, and the chosen bottleneck with its mechanism), `## Guardrail` (what must not change: results on the same inputs, observable behavior, the suite staying green). Cite the real files involved with backtick paths.

Observable handoff: write the completed result to `{{workPath}}/baseline.md` in the project's artifacts drawer with `write_artifact`. Do not merely describe what the file would contain. Re-read it with `read_artifact` before finishing this phase and repair any incomplete sections.
  2. Plan the fixperformance engineer

    Set a numeric target for the one bottleneck and break the fix into reversible stages. No source edits.

    Show working prompt
    Read `{{workPath}}/baseline.md`, then plan the fix for the ONE bottleneck it names. State the target as a number wherever possible (an operation count under a budget, a duration under a threshold, one query per batch instead of one per item) and the mechanism of the improvement (a better data structure, hoisting repeated work out of the loop, batching the access, sharing expensive setup). Break the work into ordered stages where EACH stage is individually reversible and leaves the tree working with the suite green. Name the files each stage touches. State the acceptance criteria: the measured number reaching the target using the SAME method as the baseline, results identical on the same inputs, and the suite green after every stage. Do not edit any source in this phase.

Write `{{workPath}}/plan.md` with exactly these sections: `## Target` (the number to reach and the mechanism), `## Stages` (numbered, each reversible, each naming its files), `## Acceptance criteria`. Cite the real files with backtick paths. Before working, open `{{workPath}}/baseline.md` with `read_artifact`.

Observable handoff: write the completed result to `{{workPath}}/plan.md` in the project's artifacts drawer with `write_artifact`. Do not merely describe what the file would contain. Re-read it with `read_artifact` before finishing this phase and repair any incomplete sections.
  3. Fix the bottlenecksoftware engineer

    Execute the planned stages at the real sites, keeping the suite green and the measurement honest.

    Show working prompt
    Read `{{workPath}}/plan.md` and `{{workPath}}/baseline.md`, then execute the stages in order at the REAL sites — edit the actual files with `read_file` plus `write_file`/`replace_in_file`; never a scratch copy, and never a rewrite of the measurement itself so the number looks better — fixing the measured path is the job, fixing the measurement is theater. After EACH stage, run the suite with `run_package_script` (`test`) and confirm it is still green before starting the next; a stage that goes red gets reverted or narrowed, not stacked on. Re-run the baseline's measurement as you go so you can see the number actually moving. Results must stay identical on the same inputs — speed that changes answers is a bug, not a win. Keep the code readable; do not obfuscate for a marginal gain.

Write `{{workPath}}/change-notes.md` with exactly these sections: `## Stages executed` (each stage, in order, with its suite-green confirmation and any interim measurement), `## Files touched` (backtick path per line), `## Deviations from plan` (anything done differently than plan.md and why; write `none` honestly when there are none). Before working, open `{{workPath}}/baseline.md`, `{{workPath}}/plan.md` with `read_artifact`.

Observable handoff: write the completed result to `{{workPath}}/change-notes.md` in the project's artifacts drawer with `write_artifact`. Do not merely describe what the file would contain. Re-read it with `read_artifact` before finishing this phase and repair any incomplete sections.
  4. Re-measure and verifyperformance engineer

    Re-measure with exactly the baseline's method, quote both numbers side by side, and record the suite green.

    Show working prompt
    Prove the speedup with fresh eyes. Read `{{workPath}}/baseline.md` and re-measure with EXACTLY the method and command it records — same workload, same counter, same harness; if the recorded method cannot be reproduced, that is a finding to report, not a license to substitute a friendlier one. Quote the baseline number and the new number side by side. Run the whole suite with `run_package_script` (`test`) and record the green result. Confirm results are identical to the baseline on the same inputs. Anything you could not actually re-run gets labeled unverified, never claimed.

Write `{{workPath}}/verification.md` with exactly these sections: `## Before / after` (the baseline figure and the re-measured figure side by side, same method, both quoted), `## Suite` (the full-suite result from the real run), `## Result` (target met or honestly missed, and anything unverified). Before working, open `{{workPath}}/baseline.md` with `read_artifact`.

Observable handoff: write the completed result to `{{workPath}}/verification.md` in the project's artifacts drawer with `write_artifact`. Do not merely describe what the file would contain. Re-read it with `read_artifact` before finishing this phase and repair any incomplete sections.
  5. Evaluate the deliverableperformance reviewer

    Independently grade the observable deliverable and route it to finish, repair, or user escalation.

    Show working prompt
    Review `{{workPath}}/verification.md`, `{{workPath}}/baseline.md`, `{{workPath}}/plan.md`, `{{workPath}}/change-notes.md` against every criterion below. Inspect the underlying evidence files named by the workflow; do not grade from the author's summary alone.

1. baseline.md records real numbers with the exact method and command used to gather them — an adjective where a figure belongs fails this criterion — plus a green suite receipt from before the work started.
2. The change attacks the ONE bottleneck the baseline names, at the real site, by the mechanism the plan declared — open the touched files and check; do not grade from change-notes.md alone.
3. The measured target moved against the recorded baseline using the same method: verification.md quotes both numbers side by side, and the method is identical before and after — a changed workload, counter, or harness voids the comparison.
4. Observable behavior unchanged (or changed only as the plan declared): results are identical on the same inputs, and correctness held with receipts.
5. No stage left the suite red (receipts, not claims).
6. No measurement theater: the number measured is the number the user feels — the real operation, path, or suite got faster, not a synthetic proxy, and the measurement itself was not weakened to flatter the result.

Open `{{workPath}}/verification.md`, `{{workPath}}/baseline.md`, `{{workPath}}/plan.md`, `{{workPath}}/change-notes.md` with `read_artifact`. Write the evidence-backed review to `{{workPath}}/review.md` in the artifacts drawer with `write_artifact`.

List the findings as a markdown table with columns `| Severity | File | Line | Problem | Fix |` (severities: critical/major/minor/nit; empty table only on PASS). Give each criterion a PASS or FAIL with a concrete path, excerpt, measurement, or observed behavior. End with exactly `Verdict: PASS` or `Verdict: REVISE`. The gate ENFORCES the verdict: a well-formed REVISE is rejected and routed back to `repair` automatically, carrying your findings — so list every finding in the table with a concrete fix. On PASS, `advance_task_step` to `finish`. Never write PASS while a criterion is unmet.
  6. Finishproject lead

    All deterministic and reviewer criteria passed.

    Show working prompt
    The independent review passed. Read `{{workPath}}/review.md` with `read_artifact`, then use `write_task_note` to record a concise DONE summary with the final deliverable paths (`{{workPath}}/verification.md`, `{{workPath}}/baseline.md`, `{{workPath}}/plan.md`, `{{workPath}}/change-notes.md`) and the evidence that each acceptance criterion passed. Report DONE without starting new work.
  7. Repair the deliverablesoftware engineer

    Fix only the concrete gaps from the latest independent review.

    Show working prompt
    Read `{{workPath}}/review.md` with `read_artifact` and repair every failed criterion in `{{workPath}}/verification.md`, `{{workPath}}/baseline.md`, `{{workPath}}/plan.md`, `{{workPath}}/change-notes.md`. Make changes on each file's declared surface (`write_artifact` for artifact inputs, `write_file` for workspace inputs), not in task notes or a reply. Preserve evidence that already passed. Re-run or re-check anything the reviewer found unproven. Ensure `{{workPath}}/verification.md` is genuinely updated this turn so the repair is observable, then hand it back for independent evaluation.
  8. Escalate unresolved concernsproject lead

    The bounded repair loop ended without a defensible pass.

    Show working prompt
    The deliverable did not pass after 3 review rounds. Do not claim success. Read `{{workPath}}/review.md` with `read_artifact`, then use `write_task_note` to record DONE_WITH_CONCERNS: the unmet criteria, what was attempted, the affected paths, and the smallest user decision or missing input needed to continue.

Triggers

Phrases that suggest this craftbook to a crew.

Source

View this craftbook on GitHub · MIT license