Skip to content

SKILL.md

Latest commit

 

History

History
87 lines (68 loc) · 3.33 KB

SKILL.md

File metadata and controls

87 lines (68 loc) · 3.33 KB
Raw
name surface-proof
description Prove browser-visible changes with real targets, screenshots, flows, console/network checks, deploy freshness, and before/after snapshots when useful.

Surface Proof

Use this skill when text tests are not enough and the user-visible surface needs proof.

Core principle:

  • prove what a real user can see or do
  • use screenshots/snapshots when browser tooling is available
  • report skipped visual proof explicitly
  • do not turn proof into design review

When To Use

Use for:

  • UI or browser-visible behavior changes
  • public pages, deploy previews, or local served pages
  • forms, auth, navigation, routing, cache/version, or real user flows
  • visual/layout changes where screenshots matter
  • before commit/closeout when the owned slice changed a user-visible surface

Do not use for:

  • pure backend, docs, or data-only work with no visible surface
  • early design brainstorming before an implemented surface exists
  • broad redesign critique; use the appropriate design skill instead

Proof Loop

  1. Name the surface.

    • Identify URL/page/route, environment, and flow.
    • If the repo has maps, QA scripts, page-target docs, or deploy docs, use those before guessing.

  2. Prove the target is current.

    • For local work, state the served URL and how the server/build maps to the current checkout.
    • For deploy work, state the public URL, preview URL, build id, commit, cache-buster, timestamp, or other version proof.
    • If freshness cannot be proven, mark this as a risk.

  3. Capture snapshots.

    • Always provide at least one current screenshot/snapshot when browser tooling is available.
    • For big visual/layout/product changes, capture before/after if possible.
    • If no before snapshot exists, say so. Do not invent a baseline.
    • Prefer absolute local artifact paths or browser-visible screenshot references.

  4. Exercise the real flow.

    • Open the real target, not just a component in isolation unless that is the target.
    • Perform the user action: click, submit, navigate, sign in/out, resize, or refresh as relevant.
    • Check the result in the visible page state.

  5. Check browser health.

    • Inspect console errors and page errors when tooling exposes them.
    • Inspect network failures when the flow depends on requests.
    • Ignore unrelated warnings only if named and justified.

  6. Check responsive scope.

    • Use desktop and mobile/tablet viewports when layout, nav, cards, forms, or public landing surfaces changed.
    • Use a single viewport only when the change is clearly viewport-neutral; say why.

  7. Report the receipt.

    • Include the exact result and evidence.
    • If visual proof is skipped, say why and what weaker verification was used.

Receipt

Surface Proof:
- Target:
- Build/version:
- Flow checked:
- Snapshot:
- Before/after:
- Console/network:
- Viewports:
- Result:

For tiny checks, compress the receipt, but keep Target, Snapshot, and Result.

Snapshot Rules

  • A screenshot path without a sentence is not enough; say what it proves.
  • A browser automation pass without visual inspection is not enough for visual claims.
  • A static screenshot is not enough for forms/auth/navigation; perform the flow.
  • A local screenshot does not prove a public deploy; deploy proof needs the public or preview URL.
  • If the user names a browser/tool, prefer that path when available.