Key terms at a glance

Workspaces

The first thing you register in Specnote becomes a workspace. One service or app you want to verify is one workspace — the shop you're building, an internal tool, a weekend side project: that whole thing is a workspace.

A single workspace gathers everything for that service in one place: its tests, its rules (policies), the environment details (such as the address to test), and — if you've connected it — information about the actual code. It's all held together as one workspace, so deleting a workspace clears everything inside it.

Credit usage is also counted by workspace. Every account gets one workspace, on every plan — to work on a different service, clear out the one you have and make a new one.

Areas, tests, and steps

Verification inside a workspace is organized in three layers, from the largest grouping down to the smallest action.

• Area — a group of tests that share a purpose. "Sign-up and login" might be one area; "cart and checkout" another. On screen, tests are tidied up under their area.
• Test (scenario) — a single flow a user completes in your app from start to finish, like "log in with email." Verification runs one test at a time. Inside the product, the same thing is also called a scenario.
• Step — a single action within a test. "Type the email," "press the login button" — each thing a person does on screen is a step.

The place where you see all of this together is your workspace (the board) — think of it as your own working space. When you open the board, the default view is the Dashboard, where areas and tests are laid out so you can see at a glance which tests sit in which area. Next to it are tabs like Run tests (where you run verifications and see history), CI (where verification runs automatically on every push), and Test environments (addresses and test accounts).

You can also switch the same view by perspective: All, Visitor (not logged in), or Member (logged in). Pick one to see the flows from that point of view.

Verification and results

Verification is the same thing as a test run. It's Specnote replaying a test once in a real browser — opening the screen, typing, and pressing buttons all the way through, just as a person would click by hand.

A result shows up as one of three states.

• Pass — the test ran through to the end as intended.
• Fail — it got stuck somewhere. Which step and which screen it stopped on are recorded too.
• Verifying — it's replaying right now.

The verdict is either pass or fail, nothing in between — there's no ambiguous middle result. For example, if "the login button was pressed but the next screen never loaded," that test is recorded as a fail, with the point where it stopped marked. And every time verification runs, a screen recording and step-by-step screenshots are saved — so the result isn't just a single line of text; you can replay the video to see exactly what happened.

Every verification is saved as one run group (a round). Whether you run a single test or several at once, that one run stacks up as a single group, so you can look back at "which passed and which got stuck in this round." How pass and fail are decided is covered in How verification works.

A run group runs only after a person approves it

When you start a new run group (a round), the AI doesn't just start verifying. It first builds a plan review (a PRD) — grounded in your real code — of what it will verify and by what rules. A person approves it once, and only then are the tests submitted per that plan and the first verification runs automatically. The principle: verification begins only after a human has confirmed what will be checked — the AI never runs off on its own. (Only a person can approve. Tell your AI to "approve it" and it refuses, handing back the approval screen's address instead.)

That said, re-verifying an existing group, re-running just the failures, and automatic regression checks through CI all run without this approval. The plan review is a gate you pass "when starting a brand-new run group." Creating or editing tests themselves is always open to you; only the first verification of a newly made test rides along this approval flow.

Approving the pass condition, and following changes on its own

What a test treats as success is its pass condition. Specnote doesn't set this on its own. A person has to approve it once for that test to be locked in as "this is what we now measure against." The AI can create and run tests, but it never approves a pass condition on your behalf. The principle is simple: a human decides what counts as passing.

Once approved, a test follows small screen changes on its own. If a button moves or its label shifts a little, the test re-finds it and fixes its own steps (we call this auto-heal). But if the intent — what it's trying to check — changes, that's treated as a different test: the old one is retired and a new one takes its place, and you're asked to approve the new pass condition. So "just the surface changed" and "the essence changed" are handled differently.

And it gets more accurate the more you use it. Every verification adds to a memory of "this button on this screen is right here," so the next run wanders less and moves faster and more precisely.

When code drifts from the plan

When the code ends up different from what was originally planned, we call it drift.

Code keeps changing while you build. Buttons move, fields get added, flows shift. A sign-up that was meant to ask only for an email might quietly grow a phone-verification step. Bit by bit, what you "agreed to build" and what's actually on screen pull apart — and it's hard to keep track of every difference by eye.

Specnote finds that gap by holding your tests back up against the real screen. When verification fails, it's usually a sign that drift has crept in. It also flags when an approved pass condition no longer matches the current test — showing "the approval and the condition have diverged" — and lets you re-approve. Catching that gap early is what Specnote is for.

CI inclusion — adding a test to automatic verification

Among the tests you make, the ones you feel "this must pass before every deploy" can be switched on with Include in CI. A test turned on this way is verified automatically on every push. This toggle, too, is something only a person can do (the AI never adds one on its own). For how to connect it, see Connect CI for automatic verification.

Backward and Forward

Two ideas help you understand Specnote: Backward and Forward. These aren't buttons or switches on a screen — they name "which direction you're working in."

• Backward verification — working backward from code you've already built to pull out tests and verify them. This is the flow for confirming that a running app works the way it was planned. It's Specnote's main use.
• Forward planning — the layer where a person fills in the intent behind a test: who it's for, what they do, and why. Writing that down makes the bar for verification clearer.

To say it again: both are terms that describe concepts. You don't flip a mode anywhere — just know them as names for the direction of your work.

Credits and plans

Credits measure how much work the AI has done. When the AI moves — organizing tests, analyzing a screen — credits go down. (Some work costs no credits at all, like the check that compares a step against the screen before verifying.)

There are three plans.

• Free — for getting started lightly.
• Standard — for when you start using it in earnest.
• Pro — for when you need more credits.

Payment is handled securely through Paddle. When you run low on credits, you can top up. For where credits go and how the plans differ, see Credits and plans.

If you're wondering how to create your first test, see Creating tests.