skills/agent-swarm/references/product-quality.md

Product quality gates

Functional correctness is necessary, not sufficient. A build can compile, pass tests and produce a screenshot while still being too slow, visually incoherent or unpleasant to use. Do not let pass on technical acceptance stand in for product acceptance.

Prototype vs product

Choose the quality profile with the user before dispatch:

Profile	Use when	Mandatory gates
Prototype	the user explicitly wants a rough idea, spike or throwaway demo	runnable artifact, honest limits, no performance promise
Product	the artifact will be used, shipped, demoed to others or compared with an existing version	functional + performance + UX/visual + baseline + human acceptance

Do not silently treat a prototype as a product. Do not demand product polish for a disposable spike. State the profile in the brief.

Gates

1. Functional

• acceptance commands and edge cases pass;
• the artifact runs, not just compiles;
• the verifier can reproduce the checks;
• no known crash/data-loss path.

2. Performance

Performance is part of correctness for interactive products. Define a budget in the brief before code, measure it on a release/optimized build, and record the environment.

Suggested starting points (adjust to the product, do not treat as universal):

• p95 frame time at the target window size: ≤16.7 ms for 60 FPS, or a documented lower target;
• input-to-visible response: ≤50 ms for click/selection, ≤100 ms for heavier actions;
• startup to usable UI: ≤2 s for a local desktop editor;
• idle CPU and memory recorded; no runaway process when idle;
• test with a realistic scene, not only an empty one (e.g. 100/1 000 entities).

Measure with a frame-time diagnostic/overlay, a scripted interaction, or an external profiler. Record p50/p95, resolution, GPU/CPU, build profile and commit. Debug builds are not evidence of release performance; if only debug is available, report the numbers as provisional and do not claim the budget is met.

If the budget is not met: reduce scope or fix the hot path before adding features. Do not hide a frame-time regression behind more UI.

3. UX / visual

For GUI and visual work:

• run a real 5-minute task, not just a screenshot;
• check hierarchy, typography, spacing, contrast, focus, hover/active/disabled states;
• check default, minimum and error/empty states;
• check that the viewport is not blocked by panels and that resizing does not clip controls;
• compare with the existing version/baseline on the same scenarios;
• capture artifacts and record the exact commands.

“Looks fine” is not a verdict. Name what is readable, reachable, clipped or missing.

4. Baseline

If a previous version exists, define the scenarios where the new version must be no worse: startup, time to first edit, selection, drag, save, visual density. A regression against the baseline is a failure even if the new implementation has more features.

5. Human acceptance

A verifier can check evidence; it cannot decide that the product feels usable. After each milestone or vertical slice:

1. the lead gives the user a short runnable artifact and a 3–5 step scenario;
2. the user runs it and answers: usable / usable with issues / not usable;
3. issues become the next milestone, not a footnote in a report;
4. do not start the next milestone until the current one is accepted (or explicitly waived).

Record the verdict in state.json/final-report.md. A detached verifier pass is not a substitute.

6. Scope

One milestone per session. Do not implement M1/M2 while M0 is still unpleasant. If the current slice is not usable, adding assets, play mode or export will not fix it.

Stop rules

Stop and re-plan when any of these is true:

• functional acceptance passes but the product is visibly slower or worse than the baseline;
• performance was not measured on an optimized build for a product task;
• the user says “not usable” and the next step is more features instead of fixing the current slice;
• the work has consumed half the milestone budget/time without a runnable artifact;
• a UI slice has multiple parallel writers and the visual language is drifting;
• the verifier can only produce a pass by ignoring performance/UX.

Minimal product gate

Release build, measured p95 frame time and input latency, 5-minute real scenario, baseline comparison, explicit user verdict. If any is missing, the product gate is not_run, not pass.