epistex-dev/poteto-kit / example/.agents/skills/verify-app
verify-app
VerifiedRun the real Notes app in headless Chromium, drive it through a feature's scenarios, and produce evidence (screenshot, console log, CDP performance trace, report). Use after any change to src/ and before claiming a feature works, a bug is fixed, or opening a PR. Also use to reproduce a vague bug report or screenshot.
verify-app
Never claim "it works" from reading code or from a green type check. Run the app, drive it, and attach the evidence.
Pick a flow
- Run
npm run verify -- doctorwhen anything looks off, or before a first run in a new copy. It is read-only and tells you whether this instance is worth driving: browser found,dist/fresh, preview port free or who holds it, node version, git worktree or not. - Find the feature in references/features/README.md (index by area), then read its file. The README has the baseline preconditions, driving conventions and the rules for proof and skips. Read it once per session.
- Reproduce or verify with a scenario, then fix, then verify again.
Several copies or worktrees at once: see references/worktree-isolation.md. The preview port is derived from the project path; if another process holds it, the command refuses instead of silently using a different port.
Commands
Run from the repository root (the directory with package.json).
| Goal | Command |
|---|---|
| Usage and every flag | npm run verify -- --help |
| Health of this instance | npm run verify -- doctor |
| One feature, all its scenarios | npm run verify -- --feature <feature-id> |
| One scenario | npm run verify -- --feature <feature-id> --scenario <scenario-name> |
Everything; a scenario fails when its covers list is not what its passing assertions reached (also exports artifacts/verify-coverage.json for CI scripts; no gate reads it) | npm run verify:all |
| Every listed entry point has a scenario or a stated skip | npm run verify:coverage |
| Prove verification can fail | npm run verify:selftest |
The command builds the app, starts vite preview on the derived port, launches headless Chromium with playwright-core, runs the scenarios, and stops everything it started. It exits non-zero on any failed assertion, console error or uncaught page error, and with code 3 when it refuses to start because the port is taken.
Environment and flags:
--port <n>: use this preview port instead of the derived one. If something else already holds it, verify refuses with exit 3 and names the holder; it never drives a server it did not start (it checks the nonce in/.verify-build.jsonagainst the build it just made).CHROME_PATH: use this browser binary. Otherwise the newest~/.cache/ms-playwright/chromium-*, then Playwright's default path, then a system Chromium. Nothing is downloaded.INJECT_BUG=1: build-time flag that breaks the editor title commit on purpose. Onlyverify:selftestshould use it.VERIFY_ARTIFACTS_DIR: where to write artifacts (defaultartifacts/).
Evidence
Each scenario writes artifacts/<timestamp>/<feature>-<scenario>/:
report.md: command, steps, expected vs observed table, PASS/FAIL, console error count, long tasks (>50 ms) and tasks over the 16.7 ms frame budget, artifact paths. Read this first.screenshot.png: final state of the page. Look at it; a passing assertion can still sit on a broken layout.console.json: console errors and uncaught page errors. Must be[].trace.json: CDPTracingperformance trace (open in the Chrome DevTools Performance panel or Perfetto).
When you report back, quote the report.md result line and the failing "Expected vs observed" rows, not a paraphrase. Name the entry points you covered by their ids (for example search-open-chord, search-open-button) and any you skipped, with the reason.
Selectors
Prefer ARIA labels and semantic data attributes: [aria-label], [data-component], [data-action-id], [aria-current], [aria-selected]. They are listed in each feature file under "Driving it". Do not select by class or DOM position. Scenarios get their locators from scripts/verify/selectors.ts.
Adding or changing a scenario
- Create or edit
scripts/verify/scenarios/<feature-id>.tsexportingscenarios: Scenario[]. Files in that directory are discovered; there is no registry to edit. - Declare
covers: [...]with the ids from the feature file's Sub-features (or Flows) list. If you add an entry point, add its id to the feature file in the same change. - Use
expect(name, expected, read)for every outcome; it polls briefly, then records expected vs observed. Put{ reaches: '<id>' }as the fourth argument of the assertion that proves an entry point, normally the last one its feature-file description promises (for example the search result after a rename, not only the sidebar). A scenario that lists an id incoversand never passes such an assertion fails. Usestep(description, action)for interactions. - Prove it can fail: break the behaviour (or use the
INJECT_BUGpattern) and watch the scenario go red before trusting it. - Run
npm run verify:coverage,npm run check:features, andnpm run verify:all.
Rules
- A scenario that cannot fail is not verification. Every new scenario must be seen failing once.
- A proof that drives one convenient entry point is incomplete when the feature file lists others (a chord and a button, for example).
- Do not weaken an assertion or raise a timeout to get green. Fix the app or explain the discrepancy.
- Console errors fail the run on purpose. Do not filter them out.
- Unreachable paths are never dropped silently: end the id's line in the feature file with
skip: <reason>and cover the closest real path.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |