Verifying Changes
When this applies
Before telling the user a fix, feature, or bug is done, choose the smallest
proof that exercises the behavior you changed and use the row below as a guide.
"I changed the code and it looks right" is not proof — it's the exact gap this
skill exists to close. A failing check is a reason to keep working, not a reason
to stop, ask, or report done anyway.
Scale the verification
Verification proves the changed behavior; it is not a reason to run a broad
workspace audit after every edit.
- For a localized one-line or small-file change, inspect the diff and run the
narrowest relevant test, typecheck, formatter, or direct invocation. Do not
run
pnpm run prep, browser automation, or restart a dev server unless the
changed area requires it.
- For an action or capability-card change, use the focused action/card check.
Restart only when the runtime process must reload registration or the change
explicitly affects startup.
- Escalate to package-wide tests or
pnpm run prep for shared contracts,
cross-cutting changes, migrations, or when a focused check exposes a wider
failure. Keep repository-required guards and doctor checks when they apply.
- If a focused check is unavailable, state the exact gap rather than replacing
it with unrelated expensive work.
Do NOT report done in these situations
- The change is "obviously correct" or one line — obvious fixes are the ones
that ship broken most often; run the smallest relevant proof anyway.
- You verified a similar path earlier in the session — re-run against the
actual latest edit, not a memory of an earlier pass.
- The user didn't explicitly ask you to test it — test it anyway; verify-
before-done is a standing rule here, not an opt-in.
- The full test suite is slow or flaky — run the targeted command for the
changed area (below) instead of skipping verification entirely.
- You're mid-task and unsure whether to keep going — keep going. Only stop for
a missing credential, an ambiguous decision only the user can make, or a
destructive action that needs confirmation. Silence from the user means
keep working, not pause and wait.
- You genuinely cannot run anything — say so out loud (see below); never let
"unverified" read as "done".
Proof by area
| You changed |
What proves it |
Command |
Template UI/behavior (templates/<app>/app/**) |
Drive the real page and check console + network, not just the diff |
pnpm --filter <app> dev (or root pnpm dev for the gateway), then click through the exact flow with whatever browser tool is available; check for console errors and failed (4xx/5xx) requests on that page |
An action (templates/<app>/actions/*.ts) |
Call it with representative args and inspect the real return value |
cd templates/<app> && pnpm action <name> --key value; for a write, follow with pnpm action db-query --sql "SELECT ..." to confirm the row actually landed |
| Schema/migration |
Boot the app so migrations run, then read back the new column/table |
pnpm --filter <app> dev once, then cd templates/<app> && pnpm action db-query --sql "..." (action is a per-template script, not a root one); pnpm guard:additive-migrations catches destructive DDL before CI does |
A guard/lint script (scripts/guard-*.{mjs,ts}) |
Run it directly against a case that should now pass and one that should still fail |
pnpm guard:<name> (name matches the package.json script); pnpm guards for the full sweep |
packages/core or another publishable package |
Run that package's actual tests, not just typecheck |
pnpm --filter @agent-native/core exec vitest --run <changed.spec.ts>, or pnpm test:core-integration for cross-cutting paths |
| Cross-cutting change, or unsure which area |
Workspace-wide pass |
pnpm run prep (fmt + typecheck + test:fast + guards, run in parallel) |
| Anything you deployed |
The deploy succeeding is not the check. Exercise the live path itself |
Hit the real URL or replay the real request against the deployed environment, then read that environment's logs; a green deploy with a still-broken path is the single most repeated false "done" |
Docs only (.md, AGENTS.md, SKILL.md) |
Nothing to run |
Say "docs-only, no runtime check applies" — don't invent a verification step |
For any user-visible change, put the proof in the reply: a screenshot of the
surface you just drove, or the actual query result / log line for backend work.
"Show me screenshots" is a standing expectation, not a special request.
pnpm test:fast excludes .db.test.ts / .integration.* / .e2e.* /
.live.* / .perf.* suites. If your change touches one of those, name and
run that specific file — test:fast passing does not cover it.
Production forensics
When inspecting production runs, query interactive and scheduled/background
work as separate populations before summarizing reliability. Report both
id NOT LIKE 'job-%' and id LIKE 'job-%' (or the repo's current equivalent),
including app, run count, completed count, failure count, and top terminal
reasons for each slice. A healthy interactive sample does not prove scheduled
jobs work.
When you can't verify
State it plainly and name what would close the gap: "I could not run this —
verifying it needs <command> or a browser check of <page>." Never write
"should be fixed" or "this resolves it" without having actually run the check
above.
Real failures this replaces
- "still getting it friend. this is the third time you said you fixed it when
you didn't. please reproduce end to end and verify"
- "did you test end to end? can you do so in the browser and confirm?" — asked
on nearly every wrap-up before this rule existed
- "ok so should work now?? i am getting sick of saying 'try this' and it still
not working. you confident?"
- "my analytics dashboards ALWAYS fail ... i have asked agents to fix this for
weeks at least 10x and they always say they did and then the emails keep
failing"
- "WHY THE FUCK DO YOU KEEP STOPPING" / "sorry what is still queued? you
should be doing everything now don't queue" — stopping mid-task instead of
finishing and verifying
1---2name: verifying-changes3description: Concrete, per-area proof that a change actually works before reporting it fixed, done, or "should work now" — which dev server, test command, or invocation proves a template UI change, an action, a migration, a guard, or a core/package change. Use before every wrap-up, and before stopping mid-task to ask permission instead of continuing.4---56# Verifying Changes78## When this applies910Before telling the user a fix, feature, or bug is done, choose the smallest11proof that exercises the behavior you changed and use the row below as a guide.12"I changed the code and it looks right" is not proof — it's the exact gap this13skill exists to close. A failing check is a reason to keep working, not a reason14to stop, ask, or report done anyway.1516## Scale the verification1718Verification proves the changed behavior; it is not a reason to run a broad19workspace audit after every edit.2021- For a localized one-line or small-file change, inspect the diff and run the22 narrowest relevant test, typecheck, formatter, or direct invocation. Do not23 run `pnpm run prep`, browser automation, or restart a dev server unless the24 changed area requires it.25- For an action or capability-card change, use the focused action/card check.26 Restart only when the runtime process must reload registration or the change27 explicitly affects startup.28- Escalate to package-wide tests or `pnpm run prep` for shared contracts,29 cross-cutting changes, migrations, or when a focused check exposes a wider30 failure. Keep repository-required guards and doctor checks when they apply.31- If a focused check is unavailable, state the exact gap rather than replacing32 it with unrelated expensive work.3334## Do NOT report done in these situations3536- The change is "obviously correct" or one line — obvious fixes are the ones37 that ship broken most often; run the smallest relevant proof anyway.38- You verified a similar path earlier in the session — re-run against the39 actual latest edit, not a memory of an earlier pass.40- The user didn't explicitly ask you to test it — test it anyway; verify-41 before-done is a standing rule here, not an opt-in.42- The full test suite is slow or flaky — run the targeted command for the43 changed area (below) instead of skipping verification entirely.44- You're mid-task and unsure whether to keep going — keep going. Only stop for45 a missing credential, an ambiguous decision only the user can make, or a46 destructive action that needs confirmation. Silence from the user means47 keep working, not pause and wait.48- You genuinely cannot run anything — say so out loud (see below); never let49 "unverified" read as "done".5051## Proof by area5253| You changed | What proves it | Command |54| --- | --- | --- |55| Template UI/behavior (`templates/<app>/app/**`) | Drive the real page and check console + network, not just the diff | `pnpm --filter <app> dev` (or root `pnpm dev` for the gateway), then click through the exact flow with whatever browser tool is available; check for console errors and failed (4xx/5xx) requests on that page |56| An action (`templates/<app>/actions/*.ts`) | Call it with representative args and inspect the real return value | `cd templates/<app> && pnpm action <name> --key value`; for a write, follow with `pnpm action db-query --sql "SELECT ..."` to confirm the row actually landed |57| Schema/migration | Boot the app so migrations run, then read back the new column/table | `pnpm --filter <app> dev` once, then `cd templates/<app> && pnpm action db-query --sql "..."` (`action` is a per-template script, not a root one); `pnpm guard:additive-migrations` catches destructive DDL before CI does |58| A guard/lint script (`scripts/guard-*.{mjs,ts}`) | Run it directly against a case that should now pass and one that should still fail | `pnpm guard:<name>` (name matches the `package.json` script); `pnpm guards` for the full sweep |59| `packages/core` or another publishable package | Run that package's actual tests, not just typecheck | `pnpm --filter @agent-native/core exec vitest --run <changed.spec.ts>`, or `pnpm test:core-integration` for cross-cutting paths |60| Cross-cutting change, or unsure which area | Workspace-wide pass | `pnpm run prep` (fmt + typecheck + `test:fast` + `guards`, run in parallel) |61| Anything you deployed | The deploy succeeding is not the check. Exercise the live path itself | Hit the real URL or replay the real request against the deployed environment, then read that environment's logs; a green deploy with a still-broken path is the single most repeated false "done" |62| Docs only (`.md`, `AGENTS.md`, `SKILL.md`) | Nothing to run | Say "docs-only, no runtime check applies" — don't invent a verification step |6364For any user-visible change, put the proof in the reply: a screenshot of the65surface you just drove, or the actual query result / log line for backend work.66"Show me screenshots" is a standing expectation, not a special request.6768`pnpm test:fast` excludes `.db.test.ts` / `.integration.*` / `.e2e.*` /69`.live.*` / `.perf.*` suites. If your change touches one of those, name and70run that specific file — `test:fast` passing does not cover it.7172## Production forensics7374When inspecting production runs, query interactive and scheduled/background75work as separate populations before summarizing reliability. Report both76`id NOT LIKE 'job-%'` and `id LIKE 'job-%'` (or the repo's current equivalent),77including app, run count, completed count, failure count, and top terminal78reasons for each slice. A healthy interactive sample does not prove scheduled79jobs work.8081## When you can't verify8283State it plainly and name what would close the gap: "I could not run this —84verifying it needs `<command>` or a browser check of `<page>`." Never write85"should be fixed" or "this resolves it" without having actually run the check86above.8788## Real failures this replaces8990- "still getting it friend. this is the third time you said you fixed it when91 you didn't. please reproduce end to end and verify"92- "did you test end to end? can you do so in the browser and confirm?" — asked93 on nearly every wrap-up before this rule existed94- "ok so should work now?? i am getting sick of saying 'try this' and it still95 not working. you confident?"96- "my analytics dashboards ALWAYS fail ... i have asked agents to fix this for97 weeks at least 10x and they always say they did and then the emails keep98 failing"99- "WHY THE FUCK DO YOU KEEP STOPPING" / "sorry what is still queued? you100 should be doing everything now don't queue" — stopping mid-task instead of101 finishing and verifying
Builder.io