Write requirements kanman can finish

kanman and its reviewer can only check 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 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 blocking questions	Every question marked Blocks approval is answered, decided or dropped

The readiness score (0 to 100) summarizes these checks. Only stories that pass all of them 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 independent reviewer checks the change against each one before kanman merges it.

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 that only a person can decide, 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?”. Details it can settle from your repository, such as which element owns a border or which color token to use, it decides itself and lists under What I assumed, so check those too.

Each question is marked Blocks approval or Doesn’t block. Answer it in the drafts card, at the top of the draft in the review, or by replying in the chat (“1: …, 2: not relevant”); Let kanman decide and Not relevant settle it in one click. A story with blocking questions cannot be approved, except by a workspace owner or admin with Approve with open questions. See Assumptions and open questions.

Mark urgency with a class of service

Stories are standard unless something else applies. To expedite a story, ask kanman in the conversation, 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 size is S or M.
No blocking questions are left, and the assumptions under What I assumed are right.

Next: How kanman checks its work, which explains how the criteria are checked before a merge.