Key terms at a glance

Projects and Specs

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

In some places the same thing is called a Spec. There are two names because they describe two angles.

• Project — the word you use when talking about "what flow a user goes through inside this service."
• Spec — the word for billing, usage, and limits. When you count which project a credit was spent on, or how many you can create on your plan, you count by Spec.

A single project holds its scenarios, the environment details (such as the address to test), and — if you've connected it — information about the actual code. So deleting a project clears everything inside it along with it.

Areas, scenarios, and steps

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

• Area — a group of scenarios that share a purpose. "Sign-up and login" might be one area; "cart and checkout" another. On screen, scenarios are tidied up under their area.
• Scenario — a single flow a user completes in your app from start to finish, like "log in with email." Verification runs one scenario at a time.
• Step — a single action within a scenario. "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 — think of it as your own working space. On the board, open the User Scenarios tab and you get a service map: areas and scenarios laid out side by side, so you can see at a glance which scenarios sit in which area.

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. It's Specnote replaying a scenario 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 scenario 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 scenario 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. The result isn't just a single line of text — you can replay the video to see exactly what happened on screen. How pass and fail are decided is covered in How verification works.

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 scenarios back up against the real screen. When verification fails, it's usually a sign that drift has crept in. Catching that gap early is what Specnote is for.

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 scenarios 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 scenario: 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 scenarios, 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 projects and 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 scenario, see Creating scenarios.