Assert

Assert is the third step of the Flow workflow. In this guide, you will learn:

• What the assert skill does and the problem it solves
• How the test planning works
• What the test plan produces

Overview

The assert skill plans the tests for a change. It reads the brief and the blueprint, and writes a test plan: exactly what each test asserts, and in what order the tests are built.

You invoke it with the change name:

/flow-assert project-archiving

Like the other planning skills, assert never writes test code. It produces assert.md and nothing else.

The problem it solves

Left to write tests and code together, an AI agent drifts toward green at any cost. It shapes the test to pass the code it just wrote. The test goes green, but it proves nothing, and it can lock a bug in place.

Assert breaks that loop by separating the two jobs. It plans the test contract, the precise set of assertions each test makes, before the build skill writes a line. The plan becomes the lock: the build agent inherits assertions it cannot quietly soften to match its own code.

This is why assert is a step of its own and not folded into build.

How the planning works

The skill first builds a behavior map: every observable behavior the change introduces or alters, and for each one, whether it is tested, and in which suite.

It favors functional tests, the kind that send a real request and exercise an action end to end, over isolated unit tests. A unit test earns its place only when a piece of logic owns real branching that a functional test cannot reach economically. A redundant test is treated as worse than no test, so the goal is a lean suite, not a maximal one.

The skill then authors a contract for each test, one surface at a time. A contract pins the assertions upfront: the HTTP status, the response body shape, the database row state, and so on. It asserts only what is observable from outside the code, never that an internal method ran. Each surface is presented for your approval before the next is authored.

Finally it reconciles tests across surfaces to remove duplication, audits the factories and fakes the tests will need, and scans the plan for anything that would break under the test runner's model.

TDD only

Assert plans tests, so it belongs to the test-driven path. If you do not intend to write tests for a change, skip this step and run build in --no-tdd mode, which works from the blueprint alone.

What the test plan produces

The skill writes assert.md into the change folder. It carries the behavior map, an ordered test list, and one contract block per test stating its surface, setup, action, and the exact outcomes it asserts.

Next step

• Hand off to the Build skill to implement the change against this plan.