| name | vs-perf |
| description | Use when optimizing latency, throughput, memory, startup, bundle size, or any performance target that needs evaluator-backed proof. |
Perf
Performance work needs a scoreboard before code changes. This building block turns a
performance goal into an evaluator-backed loop: baseline, optimize, compare,
guard against regressions.
Codex Goal Integration
When running in Codex, use
../vs-internal-shared/references/codex-goal.md
for standalone-goal rules.
Perf normally contributes measurement evidence to another workflow. If invoked
as the whole task, it may own a performance goal after the objective, metric,
evaluator, and pass contract are defined. Complete that goal when the result
reaches PASS, FAIL, WARN_NO_BASELINE, or BLOCKED with baseline/target
evidence and correctness guardrails reported.
Flow Contract
- Kind: Building block
- Inputs: Performance objective, metric, evaluator command or benchmark path, acceptable regression boundaries
- Outputs: Baseline, target, optimization plan, checkpoints, and final pass/fail evidence
- Status:
PERF_READY, PASS, FAIL, WARN_NO_BASELINE, or BLOCKED
- Consumers:
vs:shape-it for performance-shaped plans, vs:build-it before implementation, standalone optimization runs
- Skip conditions: Skip when the requested change is not performance-sensitive or no measurable performance claim is being made
Non-Negotiable Rule
Do not optimize before you know how to measure. If there is no evaluator, create
or identify one first. If no evaluator is realistic, report WARN_NO_BASELINE
and frame the work as cleanup or architecture, not proven performance.
Procedure
- Define the target. Name the metric: p95 latency, startup time, memory,
bundle size, query count, render count, throughput, or another concrete value.
- Find or create the evaluator. Prefer existing benchmarks, profiling
scripts, integration tests with timing, or bundle analyzers.
- Record the baseline. Run the evaluator before edits and capture the result.
- Set the pass contract. Example: "PASS when p95 improves by 20% and tests
still pass."
- Optimize in small patches. Re-run the evaluator after each meaningful
change.
- Guard correctness. Pair performance checks with relevant regression tests.
Output
## Perf Result
- Status: PERF_READY | PASS | FAIL | WARN_NO_BASELINE | BLOCKED
- Objective: <performance goal>
- Metric: <what is measured>
- Evaluator: `<command or tool>`
- Baseline: <value or unavailable>
- Target: <pass contract>
- Evidence:
- <checkpoint results>
- Correctness guardrails:
- <tests/build/lint results>
Workflow
Direct: emit Next only. Composed: return to caller.
Prev: /vs-shape-it | /vs-rfc-research | optimization request
Next: /vs-build-it
Relevant: /vs-verify | /vs-prototype
