| name | sam-perceived-performance |
| description | Make a requested interaction feel instantaneous while the real work is still running, using measured immediate feedback, optimistic updates with proven rollback, layout-stable placeholders, streaming, prefetch, and backgrounding — without faking progress, success, or freshness. Use when an action, screen, list, form, upload, search, or navigation feels slow, laggy, janky, or stuck behind a spinner, and real backend or network latency cannot be removed. |
Sam Perceived Performance
Analyze what was asked, then make the named interactions feel instantaneous while
the real work continues behind them. Remain stack-, provider-, host-, tool-, and
model-neutral.
Perceived performance is measured, not asserted. The deliverable is a first
feedback inside 100 ms with no unacknowledged pending time — proven by before and
after measurements, not by the presence of a spinner.
Non-Negotiable Contract
- Never expose secrets, credentials, private data, or sensitive paths in diffs,
commands, reports, artifacts, or returned evidence.
- Never fake progress: a determinate bar or percentage must come from a real
signal. Never fake success: an optimistic outcome requires a reversible effect,
a proven rollback, and a visible failure surface. Never fake freshness.
- Never make the real interaction slower to make it feel faster. An increase in
settled latency beyond
max(25ms, 5%) is a regression to revert.
- Never suppress or delay an error to protect the illusion.
- Never add artificial delay beyond a 200 ms anti-flicker floor, and state why.
- Never claim a timing improvement without a receipted measurement of the same
interaction, in the same environment, before and after.
- Preserve public contracts, security, permissions, data integrity, and
observability. Preserve unrelated staged, unstaged, and untracked work
byte-for-byte.
- Never reset, checkout, stash, clean, rebase, or broadly restore the workspace.
Undo only the exact patch this work introduced.
- Do not stage, commit, publish, or message an external system unless the user or
a parent workflow explicitly requests it. Parent authorization is enough; do
not re-ask.
- Stop after two cycles unless new measured evidence appears.
Resource Routing
1. Freeze the Request and the Scope
SAM_PERCEIVED_DIR="<absolute directory containing this SKILL.md>"
WORK_TMP="$(mktemp -d)"
python3 "$SAM_PERCEIVED_DIR/scripts/capture_scope.py" --repo "$PWD" \
> "$WORK_TMP/baseline.json"
Use repeated --path <repo-relative-path> only for explicit scope and reuse the
exact arguments later. Keep all temporary artifacts outside the repository.
From the request, name each interaction that should feel instantaneous. An
interaction is one user intent with one entry point: the trigger, the code path
that handles it, and the work that must finish before the result is final.
Freeze, before touching anything:
- Each interaction's id, name, entry point, trigger, and blocking work.
- What must not change: public contracts, totals, ordering, permissions, security.
- Honesty invariants for this domain — which outcomes may never be shown before
confirmation, and which data may never be shown stale.
- Owned paths, no-go paths, and the baseline fingerprint.
If the request names a feeling ("the app is slow") without an interaction, pick the
interactions on the described path, state that choice, and proceed. Under a parent
workflow, never ask; return BLOCKED with receipts if scope cannot be established
safely. Standalone, ask one blocking question only if no interaction can be
identified at all.
2. Measure the Baseline
Follow references/measurement-protocol.md.
Record feedback_ms, meaningful_ms, settled_ms, and dead_time_ms per
interaction, from at least five samples, with the device and network profile
written down.
python3 "$SAM_PERCEIVED_DIR/scripts/run_checked.py" \
--id E-001 --receipts-dir "$WORK_TMP/receipts" \
--classification BASELINE --repeat 2 \
-- <baseline measurement command>
Then locate the real cost. Read the handler and the work it awaits, and answer:
- What must finish before the user can see a correct result?
- What is awaited but not actually needed for the first useful paint?
- Which part of the wait is unacknowledged, and how long is it?
Inspect changed command definitions before executing them. If an interaction
cannot be measured comparably, mark it BLOCKED and keep going with the rest. Do
not estimate a number you could not measure.
3. Select Techniques by Class and Reversibility
Classify each interaction by its measured settled_ms:
python3 "$SAM_PERCEIVED_DIR/scripts/classify_latency.py" \
--label I-001 --settled-ms <baseline settled> --feedback-ms <baseline feedback> \
--dead-time-ms <baseline dead time>
The class sets the minimum affordance and names what is forbidden. Then choose
from references/technique-catalog.md, cheapest
first, and gate every optimistic or progress affordance against
references/honesty-policy.md.
Decide reversibility before writing code. For each candidate optimistic commit,
state the failure mode, what rollback restores, what the user sees on failure, and
the reconciliation rule for concurrent or out-of-order results. If the effect is
irreversible, reject the optimistic path and use acknowledgement plus real
progress instead — a rejected optimistic technique is a result, recorded as
REJECTED with its reason.
Classify each technique APPLIED, REJECTED, or BLOCKED. Prefer one
acknowledgement that lands in 40 ms over three stacked loading affordances.
4. Implement the Smallest Honest Illusion
Apply one coherent technique at a time. After each meaningful change:
- Inspect the exact diff and confirm only owned paths changed.
- Re-measure the interaction and compare against the baseline.
- Run the failure-path proof for any optimistic commit.
- Undo only that exact patch if it fails, regresses real latency, or requires
hiding an error.
Every applied technique needs, before it counts as applied:
- A passing test for the fast path.
- A passing test that drives the failure and asserts the rollback and the failure
surface, for any optimistic commit.
- A passing test that the pending, settled, and failed states are announced, and a
stated reduced-motion behavior.
If owned scope exceeds twice the frozen initial set, or the work crosses an owner,
protocol, storage, migration, or release boundary: under a parent workflow return
BLOCKED with the exact breach; standalone, stop and request approval.
5. Prove the Perceived Improvement
Re-measure with the identical procedure, then receipt the budget verdict so the
gates are executed rather than asserted:
python3 "$SAM_PERCEIVED_DIR/scripts/run_checked.py" \
--id E-006 --receipts-dir "$WORK_TMP/receipts" \
--classification TARGET --repeat 2 \
-- python3 "$SAM_PERCEIVED_DIR/scripts/classify_latency.py" \
--label I-001 --settled-ms <after settled> --feedback-ms <after feedback> \
--meaningful-ms <after meaningful> --dead-time-ms <after dead time> \
--baseline-settled-ms <baseline settled>
An interaction is IMPROVED only when first feedback moved measurably earlier,
lands inside 100 ms, and its unacknowledged pending time is within budget. It
feels instantaneous only when dead_time_ms is zero.
Run a second cycle only when the first exposes a new measured gap. Stop when the
remaining gap is real latency that no honest affordance can mask — say so instead
of adding another layer.
6. Validate and Return
python3 "$SAM_PERCEIVED_DIR/scripts/capture_scope.py" --repo "$PWD" \
> "$WORK_TMP/current.json"
python3 "$SAM_PERCEIVED_DIR/scripts/validate_perceived_report.py" \
--baseline "$WORK_TMP/baseline.json" \
--current "$WORK_TMP/current.json" "$WORK_TMP/report.json"
Follow references/output-contract.md. Cover every
post-baseline path exactly once.
Return PERCEIVED_INSTANT only when every improved interaction acknowledges
inside 100 ms with zero unacknowledged pending time, no interaction is blocked,
every mandatory gate passes, and no evidence is flaky. Return IMPROVED when
first feedback moved earlier but pending time remains, and say what remains.
Return NO_CHANGE when the interactions already met their budgets or no honest
technique existed. Return BLOCKED when measurement, authorization, or a safe
technique is unavailable.
Do not weaken the validator, the budget table, or a test to reach a status. Report
real latency alongside perceived latency so the improvement cannot be mistaken for
the work getting faster. Remove temporary artifacts before returning.
