Write requirements kanman can finish

kanman can only prove what was asked for if the request says what “done” looks like. This guide shows what makes a story finishable, with examples you can copy.

What kanman checks

Every story gets five readiness checks before it can be approved and written to the tracker:

Check	Passes when
Clear acceptance criteria	Each criterion has a situation (Given), an action (When) and an observable result (Then)
Testable	The story has a test plan, and every result can be checked by a test or a script, not by opinion
Small enough	The story fits size S or M; L stories must be split
No open questions	Everything kanman asked during intake is answered
Has a Demonstrate block	There are concrete steps that show the outcome

The readiness score (0 to 100) summarizes these checks, 20 points each. Only stories that pass all five show Ready for kanman and can be approved.

Start with the outcome, not the solution

Describe what a user or a system can do afterwards. Leave the implementation to the team unless it really matters.

Instead of	Write
“Add a CSV library and a new endpoint”	“Customers can download their invoices for a date range as a CSV file for their accountant.”
“Fix the money formatting”	“Every amount on the invoice list and the invoice page is shown as `€4,125.00`, like on the invoice page today.”
“Improve performance”	“The invoice list for a customer with 5,000 invoices loads in under 1 second on the staging server.”

kanman turns an outcome into criteria and steps. It cannot turn a solution into an outcome without guessing.

Write acceptance criteria as Given/When/Then

Each criterion is one situation and one observable result:

Given a customer with 3 invoices in March 2026
When they export March 2026 as CSV
Then the file has 3 rows and the columns date, number, amount

Tips:

One result per criterion. “Then the file downloads and has 3 rows and is named …” is three criteria.
Use real values. “3 invoices in March” is checkable; “some invoices” is not.
Include the edge cases that matter: empty results, invalid input, permissions.
Do not describe the UI pixel by pixel. Name what must be visible or returned.

kanman gives each criterion a stable id (ac-1, ac-2, …). The evidence pack reports each one as passed, failed or unknown, with file and line references.

Write a Demonstrate block

The Demonstrate block is the most important part of a story. It is the short script a colleague would follow to show you the feature works, and kanman turns it into the executable acceptance spec.

A good Demonstrate block has a kind (UI, API, CLI or configuration), concrete steps, and the expected result:

Kind: UI
Steps:
  1. Open /invoices
  2. Pick the date range 2026-03-01 to 2026-03-31
  3. Click "Download CSV"
Expected: a CSV file downloads with the columns date, number, amount and 3 rows

Kind: API
Steps:
  1. GET /api/invoices/export?from=2026-03-01&to=2026-03-31 with Accept: text/csv
Expected: status 200, content type text/csv, header row date,number,amount

What does not work as a Demonstrate block:

“Tests pass.” Tests are part of verification, not the outcome.
“It works.” There is nothing to run.
Steps that need production data, a person’s login or a third-party system that the test environment cannot reach.

Warning

A story without a Demonstrate block cannot be approved in intake and cannot reach Ready. The story shows Add a Demonstrate step so you can add one.

Keep stories small

kanman sizes stories S, M or L. Size drives cost and risk:

S: one behaviour in one area, typically a few files.
M: one feature across two or three areas, for example API and UI.
L: several behaviours or areas. An L story does not pass the readiness check.

Small stories are cheaper, faster to review, and fail in ways that are easy to understand. If a requirement produces an L story, split it into smaller stories before you approve them.

Answer open questions in intake

When a requirement leaves something open, kanman lists it as an open question instead of inventing an answer. Typical examples: “Should the export include draft invoices?” or “Which time zone defines the date range?”. Answer them in the intake review. A story with open questions cannot be approved.

Mark urgency with a class of service

Stories are standard unless something else applies. To expedite a story, ask on the team’s intake page, for example “expedite SBX-12”; “deprioritise SBX-12” sets it back:

Class	Use for
`expedite`	Incidents, CI regressions, security fixes. Never stopped by budgets or throttles.
`fixed_date`	Work with a real deadline
`standard`	Everything else (default)
`maintenance`	Upkeep found by maintenance mode (set automatically)

Checklist

Before you approve a story, check:

The title says what a user can do afterwards.
Every criterion has Given, When and Then with real values.
The Demonstrate block can be run against a fresh test environment.
The size is S or M.
No open questions are left.

Next: Add an acceptance manifest so kanman can run the Demonstrate block as a real test.