Tutorials · Lesson 4 of 12

Bars

A bar is what done means, written before any code exists: a few numbered lines, each one a fact that must be true and the proof that shows it. Agents build to the bar, and a verifier from another model family checks every line. Sharper bars produce sharper work.

A good bar is:

One fact per line: numbered, so each one is checked on its own.
Proven, not promised: every line names how a machine proves it.
Tied to real code: it names the files the change touches.
Short: a person reads it in ten seconds.

One fact per line

Each numbered line says one thing that must be true, and ends with how it's proven.

The bar · Password reset

1. A reset link expires 30 minutes after it's sent [test]
2. A used reset link is refused the second time [test]
3. The reset email leaves in under 2 seconds [measurement]

Three kinds of proof

The tag at the end of a line tells the verifier what evidence to look for.

[test]: a named test case proves it. The strongest kind; use it wherever you can.
[command]: a command's result proves it, like a check or a lint passing.
[measurement]: a number proves it, with the threshold in the line itself.

Tie it to real code

Name the files it touches, plus one line that proves the real path.

The bar · Declined cards

1. web/checkout.js shows why a card was declined [test]
2. The cart is unchanged after a decline [test]
3. A real checkout with a test card that declines keeps the cart [test]

Without line 3, lines 1 and 2 can pass with dead code.

Too loose, then sharp

A loose bar lets the wrong work through. Then you sharpen the bar, not the diff.

Too loose

1. Password reset works [test]

Sharp

1. A reset link expires 30 minutes after it's sent [test]
2. A used reset link is refused the second time [test]

"Works" can't be checked, so anything passes. Each sharp line can fail.

Try it

File an item with a bar, then read it back.

~/your-repo

$ pullboard add web "Reset links expire" --criterion "1. A reset link expires 30 minutes after it's sent [test]. 2. A used reset link is refused the second time [test]."
$ pullboard show 4   # the item and its bar