Most bugs I lose sleep over don't come from a function returning the wrong value on a happy path. Unit and integration tests catch those when someone remembers to write the case. The bugs that slip past review usually live between steps: a worker crashing mid-transition, a retry arriving after a cancellation, or two processes interleaving reads and writes in an order nobody drew on the whiteboard.
A model checker explores every reachable order of events and checks whether your rules hold in all of them. For years I knew about formal verification and what it was used for, but I didn't know a specification language and never had the time or energy to climb that curve on top of day-to-day delivery work.
LLMs and coding agents have made it accessible to me. Instead of learning a specification language from scratch before checking an idea, I can lean on the model to handle the syntax and tool plumbing while I focus on the rules the system needs to keep. To try that on my own work, I put together and published grill-and-verify, which runs as both a Claude Code plugin and a pi package. Most of the skills inside it aren't mine; the experiment has been combining skills from different sources into one workflow and seeing what they find on real problems.
The mental model in plain English
Because I'm learning this as I go, it helped to separate the words that come from the chat skills from the model-checking terms:
- Questions and rounds (
grill-me): not formal verification terms. This is the agent interviewing you in chat, sending a small batch of questions (a round), waiting for your answers, and then asking the follow-up batch until you've agreed on the plain-English rules (which the skills call promises) the system has to keep. - States (the model checker): a snapshot of the system at one moment, such as what status a database row has, whether a request is in flight, or which worker is running.
- Steps (the model checker): one action that moves the system from one state to the next, such as a request arriving, a worker writing a row, a network call failing, or a process crashing.
- Bounds (the model checker): small limits you give the checker (for example, at most two workers and two retries) so the number of reachable states stays finite instead of growing forever.
- Failure path (what the checker calls a counterexample): the shortest chain of steps the checker found that takes the system from a valid starting point into a state that breaks one of your rules.
Under the hood, the skills use TLA+, a specification language for modelling concurrent and distributed systems, and TLC, its model checker. For pre-code product flows, they also use Quint, a newer specification language with more familiar syntax that compiles down to TLA+.
Where the skills come from
I combined existing skills from three places and wrote the packaging around them:
grill-mecomes from Matt Pocock'sskillsrepository (MIT, Copyright Matt Pocock), renamed fromgrilling.statechart,create-formal-verification-skill,create-verification-skill,maintain-formal-verification-skill, andmaintain-verification-skillcome from Lauren Tan'spstackcollection (MIT, Copyright Lauren Tan), via Brandon Kase's fork, which addsflow-promises.grill-and-verify,verify-toolbox, the-dockershims (statechart-docker,check-docker,render-docker, andtlc-docker), and harness-portable paths are original to my repo.
TLC, Quint, and Pele (a CLI tool that renders Mermaid diagrams to SVG) need Java and Node. Rather than installing those on my host machine, verify-toolbox packages Node 24, the Temurin 25 JRE, tla2tools.jar v1.7.4 (TLC), Quint 0.33.0, and Pele 1.9.0 into a single Docker image that the -docker shims run.
One workflow, not nine separate tools
grill-and-verify chains the skills into a five-stage pipeline, pausing at each stage so the human still owns the decisions:
grill-me ──▶ model & check ──▶ statechart ──▶ board ──▶ hand off
(settle the (flow-promises (diagram + (living (verified plan,
decisions) or create- bug paths) board) tests, next steps)
formal-verification-skill)It starts with grill-me, which interviews you in rounds to flush out unstated assumptions. Rather than dumping twenty questions on you at once, it asks the top-level decisions first, waits for your answers, and then asks the follow-up questions that depend on what you chose, while sub-agents look up codebase facts on their own. Two questions always sit in those rounds: what the system promises in plain words, and what can happen without a user asking for it (crashes, timeouts, retries, or concurrent workers).
Once those decisions are settled, stage two branches on whether code exists:
- Before code exists (
flow-promises): pairs screen mocks with a Quint model of how the user and the world move between states. You pick which promises to check,check-dockercompiles Quint to TLA+ and runs TLC, and broken promises come back as paths through the mocks so you can fix the flow before building it. - When risky code exists (
create-formal-verification-skill): targets the part of the codebase where a bug costs the most and tests reach the least. It writes a model (defaulting to TLA+ and TLC for state machines and event orderings) where each step in the model matches one indivisible step in the code. It also has to prove the check can fail by testing it against a broken copy of the model and a scratch edit to the real code, so the agent can't hand you a check that passes trivially. It then saves a project-local skill recording which files, bounds, and git commit it covers.
Both branches hand off to statechart. Raw TLA+ traces are hard to read if you don't know the language, so statechart uses a view module (state(), step(), and group()) to translate states and transitions back into your own words, reports the shortest counterexample path for each broken rule, and renders a Mermaid statechart to SVG via Pele with broken states marked. Above its 500-state chart budget, it draws only the bug paths (or flow-promises renders a merged view) while TLC still checks the full state space. Where a live board skill such as show-me exists, grill-and-verify puts the promises, diagram, and bug paths on a board before handing off acceptance and replay tests.
That division of labour is what makes pairing a coding agent with a model checker work for me. The LLM isn't deciding whether the concurrency is safe; TLC is checking every reachable state deterministically. And because you agree on the promises in plain English first, inspect the statechart in your own words, and force the check to fail on a broken copy, you aren't taking the TLA+ the agent wrote on trust either.
A formal model is still only a model, so the pipeline also includes create-verification-skill for checking real user-facing behaviour. It generates a project-local skill and a features/ map to launch the real app, run a doctor check, drive features through the real UI, CLI, or HTTP surface, capture evidence, and clean up. Alongside it, two maintain-* skills guard against drift as the codebase changes: maintain-formal-verification-skill diffs covered files from the recorded sync commit to separate model drift from real regressions, and maintain-verification-skill audits the app-driving skill against the source and a live run.
What the first runs found
I've pointed these skills at three concurrency and state-machine problems so far, plus two follow-up sessions checking fixes against the first model:
| Run | Skills used | Rules checked | Distinct states checked | Existing code result | Shortest failure path |
|---|---|---|---|---|---|
| 1 | create-formal-verification-skill, statechart | 2 | 3,774 to 76,928 | Passed under normal timing; both broke when timing was relaxed | 13 to 24 steps |
| 2 | grill-me, statechart | 10 | 7,598 to 95,497 (934,975 unsplit) | 10 of 10 broke | 3 to 22 steps |
| 3 | grill-me, statechart | 13 | 194,585 to 4,855,770 (39,305,356 initial) | 12 of 13 broke | 3 to 9 steps |
(The state counts show a range because statechart re-runs TLC as broken rules are removed or as a large initial model is split and bounded down so individual checks stay fast.)
A few things stood out as I worked through them.
In the first run, the existing code passed all 3,774 states in under 1 second while its normal timing setting held. When I asked what would happen if a slow worker ran past that timeout and overlapped with a second worker, both rules broke. The checker handed back a 13-step sequence of events for the first broken rule and an 18-step sequence for the second. When I tried fixing only one half of the race in a follow-up session, the checker found a 24-step chain of interleaving actions that still broke the rule, showing why both fixes had to go in together.
Runs 2 and 3 modelled two separate state machines. In Run 2, grill-me settled 8 initial rules and I added 2 more during modelling to make 10. In Run 3, grill-me worked through 23 questions across 3 rounds to settle 13 rules for the second state machine. Once modelled, almost every rule in both runs failed on the first pass, and several fixes I expected to be enough weren't. In Run 2, four intermediate designs still broke 7, 7, 5, and 2 rules before a combination of 7 fixes held all 10.
The third run also showed that the checker can stop you building things you don't need. I had 8 proposed fixes turned on in the final design. By switching them off one at a time and re-running the check (which took 1 to 66 seconds per rule on the bounded model), I found that 7 fixes were needed and 1 wasn't required for any of the 13 rules to hold.
I wouldn't have sat down and written a unit test where 24 events interleave in that order, and I couldn't have proved by staring at a diff that 1 of the 8 proposed fixes was redundant.
What this doesn't establish, and what I'm still unsure about
Model checking cuts both ways on the gap between a model and production code. When TLC prints No error has been found, it hasn't proved a production system correct; it has only checked that the rules you wrote hold for the model you wrote, within the bounds you gave it. If the model treats two database queries as one indivisible step when the code has no transaction, TLC will miss the race. If a bug needs three retries and your bound is two, TLC will never reach that state.
When TLC does break a rule, that doesn't mean every counterexample is a live production bug or that formal verification belongs on routine CRUD work. Database locking, transaction isolation, or deployment timeouts outside the model can block a trace in practice, which is why the workflow insists on replaying paths against the real system before calling them bugs.
State explosion is a real constraint too. Watching a model hit 39,305,356 distinct states in five minutes makes it obvious that picking bounds is a judgement call: trim them too hard and you can hide the two-fault interaction that mattered.
My own mileage is partial as well. Between them, the runs above only used grill-me, create-formal-verification-skill, statechart, and verify-toolbox. I haven't yet tried create-verification-skill on a live app, used flow-promises on a new user flow, or run maintain-formal-verification-skill and maintain-verification-skill across months of commits.
What I do have now is more useful than an abstract pitch for formal verification. I have concrete numbers, readable statecharts, and plain-English promises that the models show are broken, along with the step-by-step paths that break them. That gives me something tangible to take to my teams so we can walk through the findings and introduce the fixes. From there, the next step is bringing these models and verification skills into the systems themselves, and working out how to get the teams to adopt the process as part of how we build and maintain software.