Stories and acceptance criteria

A story is the piece of work kanman takes on: one issue in your tracker, small enough for one pull request, with acceptance criteria that say exactly when it is done. kanman only picks up stories that are ready, and every change it makes passes your CI and an independent review against the criteria before it merges.

Where stories come from

Stories come from two places:

• Your tracker. An issue in the connected project becomes a story on the team page once it is marked for kanman: it carries the pickup label (kanman by default) or is assigned to the account set in the team’s tracker settings. Unmarked issues never appear on the team page.
• Intake. Describe a requirement to kanman in the conversation (press N to start with the team you are looking at), or ask kanman in Slack or Microsoft Teams (see Work with kanman in Slack and Microsoft Teams). kanman drafts stories and shows them as a card for you to approve or reject; Open review opens a page to edit them first. Approved stories are written to your tracker in one batch, with the pickup label. A story gets its key (for example SBX-12) when you approve it, so rejected drafts leave no gaps in the numbering.

Triage comes first

Every message kanman receives on intake is classified as exactly one of four kinds:

Only work requests become stories, so a question like “what is blocking SBX-12?” never turns into a ticket. If a request is too vague, kanman asks up to three questions first; answer them on the request page and kanman drafts again.

Why a story exists

Right under its title, every story says in one sentence why it exists. The records it names are links. For example:

Opened by kanman on 23 Oct because develop of flow_object_cody turned red (pipeline 894405) and stayed red for 2 runs.

Part of the goal “Connectors never replay a vendor write”, approved by Jana on 21 Oct.

Asked for by Marco on 22 Oct: “Please add a CSV export of the invoices”.

Imported from the tracker issue FM-912.

kanman writes the sentence when it creates or takes on a story, in your team’s chat language. Each story, goal, message, pipeline, merge request, finding or tracker issue it names is checked against the real record before the sentence is saved, so every link opens what it names. People are named, not linked. For a story kanman has not written a sentence for yet, the page builds one from what is already known about the story, such as your request, the tracker issue, the goal or what kanman recorded when it opened the story. kanman replaces it with its own the next time it works on that story.

A story can come from:

The story’s history at the bottom of the page still lists every change.

kanman never adds scope on its own

kanman only builds what a person asked for. A story whose scope nobody confirmed never moves to Ready or starts:

• a request kanman turned into a feature in its own words, until you approve the draft;
• something kanman proposed itself, such as a follow-up;
• a part of such a story after a split;
• a story an outcome’s plan added, unless a person approved that plan.

These stories show Waits for a yes on the board. kanman asks the person who made the request (or the team’s responsible person) once per request: “May I build it as I drafted it?” with Yes, build it as written, Edit it first and Drop it. The question joins your other questions in one place (see Questions from kanman). You can also say yes on the story itself, or move it to Ready yourself: that move is your yes too. Drop it closes the story as won’t do; nothing is deleted.

Drafts that fit your team

kanman drafts for the team you actually have. Before a draft reaches you, kanman checks it against the tools your team uses (its code host, where it tracks work, its chat) and against what kanman already does for the team, such as the maintenance scan or watching your pipelines. A draft that names a tool your team does not use (“file GitHub issues” for a team on GitLab that tracks its work on its kanman board) or that builds something kanman already does (a dependency audit, a lockfile check, a link checker) is drafted once more. If it still does not fit, kanman files nothing and asks you one question instead, for example “My maintenance scan already looks for this. Should I run it instead? Say ‘run the scan’.” If you do want such a tool built, say so in your request (“add a lockfile check to our pipeline”), and kanman drafts it. The same check applies to the stories an outcome’s plan proposes: a step that names a tool your team does not use is left out of the plan.

When kanman finds drafts of an earlier request that miss the mark this way, it tells the person who asked, once per request: “I misread your request. May I drop them and run the maintenance scan instead?” with Drop them and run the scan instead, Edit it first and Yes, build it as written. Dropping closes them as won’t do (nothing is deleted) and starts the scan; what it finds arrives on the board for your review.

Work with a clear trigger keeps going without asking, within the team’s boundaries: failing pipelines, security and dependency updates, stories a person wrote, approved or moved to Ready, parts of such stories, issues from your tracker, and stories inside an outcome whose plan a person approved.

Reading a story

A story page answers the questions you usually have, in this order:

1. What is it, and why? The title, the sentence that says why the story exists, and the description. A long description folds after a few lines; choose Show more to read all of it. Choose Edit to change the title and short description.
2. Where does it stand? A short card says what needs you first, for example a question from kanman with Answer, or who the story waits on and since when. Otherwise it says the stage in a sentence, such as “In review: the change is made and being checked.”, and shows the latest thing that happened.
3. Is it done? Done when lists the acceptance criteria with their result (passed, failed, unclear or open) and how many are met. It also shows the merge requests, pipelines and commits that delivered the story, the plan and your to-dos. Choose Edit criteria to change them.
4. What happened? The newest entries of the story’s log. Choose Show more for the rest. Comments and the full history follow.

Size, class of service, labels, the test plan and assumptions are under Details: a column on the right on a wide screen, a fold you open on a phone. Choose a value to change it. Less frequent actions, such as Refine with kanman, Work on it in Claude Code, the issue in your tracker and Close without delivering, are in the … menu at the top right.

Anatomy of a story

Acceptance criteria

Each criterion is written as Given / When / Then and has a stable id (ac-1, ac-2, …) that is never reused within the story:

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

Before a change merges, an independent reviewer checks it against every criterion, and the story’s checklist shows which criteria are met. See How kanman checks its work.

Changing criteria during the work

Sometimes the team learns during the work that a criterion itself was wrong, for example a page load limit of 2.5 s that cannot be met because the measurement includes your company’s single sign-on redirect.

Edit the criterion on the story and say why in the story’s notes. kanman reads the change the next time it looks at the board, adjusts the work in progress, and the reviewer checks the change against the criteria as they are now. The change is recorded with who made it and when.

The Demonstrate block

The Demonstrate block says how a person would see that the story works. It ends the acceptance criteria and is required for every story. The reviewer uses it to judge whether the change does what was asked. It has a kind, steps and an expected outcome:

A good Demonstrate block:

Kind:     ui
Steps:    open /invoices, pick 2026-03-01 to 2026-03-31, click "Download CSV"
Expected: a CSV downloads with the columns date,number,amount

“Tests pass” is not a Demonstrate block. It names no outcome a person could check. A story without a Demonstrate block shows Add a Demonstrate step in the draft review and cannot be approved.

Readiness

Every story gets a readiness score from 0 to 100, built from five checks:

Each check is worth 20 points. At 100 the story shows Ready for kanman; only such stories can be approved and written to the tracker from intake.

Assumptions and open questions

kanman does not ask you what it can find out itself. Design and code details, such as which element owns a border, which color token or class to use, or where a change belongs, it settles from your repository and its conventions, and writes each choice down under What I assumed. It asks only what a person has to decide: scope, product intent, or a trade-off it cannot infer. Each question says whether it Blocks approval, and often what kanman would pick (“I would pick: …”).

Every open question has three actions, in the drafts card in the conversation, at the top of each draft in the review and on the story page:

Settled questions stay on the story under Settled questions, with the answer or kanman’s choice. You can also answer in the chat; see Answer kanman’s questions.

When you click Approve on a story that is not ready yet, kanman says why (“1 question blocks approval. Answer it first.”) and moves you to the first blocking question. Workspace owners and admins can choose Approve with open questions when only questions hold a story back: the questions stay on the story as notes, the approval is recorded in the audit log, and the tracker issue lists them under Open questions. The tracker issue also lists the assumptions and the answered questions, so whoever picks the story up sees what it was settled on.

Splitting stories

kanman keeps stories small instead of tracking checklists inside them. When kanman drafts a large requirement, it writes several stories, each with its own criteria and Demonstrate block. A story of size L does not pass the readiness check; split it in the draft review before you approve it.

kanman also splits large stories on its own when it plans the work: a story of size L becomes smaller stories, each with its share of the criteria, and kanman says so in the story’s notes and the activity log. Parts of a story nobody said yes to wait for a yes like the story itself (see kanman never adds scope on its own), and kanman never splits a draft you have not approved, a story that waits for a yes, or a draft that did not fit your team.

The test plan lists the concrete checks the change needs; the reviewer checks that the change has them.

When kanman would rather not start

kanman does not start every story it is handed. When a story is vague, too big, risky or collides with other work, it says so before any work begins: “I’d rather not start this yet, because …”, followed by one concrete proposal instead of the work.

You see the same words everywhere kanman talks about the story: in its reply in the conversation, in Slack and Microsoft Teams, in its answers on tracker issues and pull requests, on each draft in the drafts card and the review, and on the story page. It is a recommendation, not a lock: you decide, for example by splitting the draft or approving it as it is.

Estimates and what kanman is not sure about

Every drafted story carries an estimate: its size, an effort range and how confident kanman is, with a short reason, for example Size M · about 1–2 days · medium confidence: 3 criteria, touches the billing export. kanman never sounds surer than the facts allow: open questions, risky ground or several unknowns lower the confidence.

Under What I’m not sure about kanman lists what it could not settle, each with the reason and what would settle it: “I’m not sure which tenant the export uses because the story does not say. A look at the tenant configuration would settle it.” The same list goes into the plan kanman writes before it changes code, and the plan ends with what kanman is still unsure about.

Under Close to other work the story names the open stories, runs and pull or merge requests it overlaps with, and the files they share. Where your tracker can list its open issues, kanman compares with those too; otherwise with the stories on the board.

Before work starts

Work moves on between drafting and starting. Before kanman starts a story, it looks at what else is in progress. If other work is changing the same files, or another story is the same work, kanman orders them so they do not collide, or links the duplicate, and says so in the activity log.

Who works a story

A story is worked by kanman, by people, or by both together. The avatars at the bottom of a board card show who is on it: kanman’s avatar with its small bot badge, your colleagues with theirs, and +2 when more people are assigned. The number next to the speech bubble counts the story’s notes.

• Nobody assigned, or kanman assigned: kanman works the story once it is in Ready, as always.
• A person assigned: that person works it. kanman does not start work on it and helps instead: it answers in the story’s notes and keeps the board up to date. Remove the person, or add kanman and remove yourself, to hand the story back; once it is in Ready, kanman picks it up.

To change who works a story, open it and choose the avatars (or Assign) at the top right. Pick Assign to me, kanman or any member of your workspace; the line under the list says what your choice means for kanman. Owners, admins and members can assign; viewers see who is assigned. People you assign are notified. From Claude Code or Codex, use assign_story.

Labels and the board filter

Labels sort stories and goals at a glance. They show as coloured chips at the top of the board card. Each team has its own set:

• On a story, open Details and choose Add label (or the chips), tick the labels that fit, or type a new name and choose Create label. New labels get the next free colour.
• On a goal, open Details on the goal’s page.
• For the whole team, go to Team > Team > Labels to rename a label, pick one of eight colours or delete it. A deleted label leaves every story and goal.

kanman adds labels from your team’s set when it drafts stories, and only where one clearly fits. It never makes up new labels. Owners, admins and members add and remove labels; viewers see them.

Filter at the top right of the board narrows it to stories with certain people (you, a colleague or kanman) or labels. Choices within people or within labels widen the filter, choosing both narrows it, and a goal’s card stays when its own labels or any of its stories match. Clear filter shows everything again.

Checklist

A story’s checklist shows how far it is, on the story page under Done when and as a thin bar with “3/7” on its board card. It has three parts, and none of them can be ticked by someone just saying so:

• Acceptance criteria count as met when kanman’s checks pass them: your CI and the independent review.
• Plan: the steps of the plan kanman works from. A step is ticked only when one of kanman’s checks proved it (the check is named beside the step), not when the coding tool says it is done.
• To-dos: your own items. Add, tick and remove them, also while kanman works on the story.

The checklist shows progress. Whether a change merges is still decided by your CI and the independent review.

Notes and handovers

Every story and goal has notes: a conversation in threads, under Comments on the story page and under Details > Notes on a goal’s page. Reply to a note to keep a thread together.

• Mention people with @ and their name to address a note to them; the note stays in the story’s or goal’s thread for everyone to read. kanman tells each person you mention in their chat with the team (in Personal for notes outside a team), with a link to the story or goal.
• Mention kanman with @kanman. kanman reads the thread and answers in it, usually within minutes. It also answers when you reply in a thread kanman started, or write on a story assigned to kanman.
• kanman writes in the notes too. While it works on a story, it notes what it is doing and hands over steps that need a person, and a question it has for you shows in the story’s log with Answer, which opens the question pinned in your chat.

kanman hands work back and forth through the story’s assignee. When the next step is yours (for example, creating vendor test accounts for some connectors), kanman prepares a story that lists what is needed, assigns it to you and says in the notes what to do. When you are done, write “@kanman done” in the notes (and add any secrets under the team’s run secrets). kanman checks the story, takes it back and continues the work that waited for it.

kanman acts on notes from owners, admins and members. Notes from viewers are read, never followed.

Close a story without delivering it

Sometimes a story will not be delivered on its own: another story already covers it, it duplicates another story, or your team decides not to do it. Moving it to Done would report it as delivered. Owners and admins close it instead:

1. On the story page, open the … menu at the top right and choose Close without delivering.
2. Pick the reason: Another story covers it, It duplicates another story or We won’t do it. For the first two, pick the story of the same team that covers it.
3. Add a note if you like and choose Close story.

kanman moves the story to Done, links it to the covering story, closes its open questions and records who closed it and why in the audit log. The story page shows Closed, not delivered with the reason and a link to the covering story, and the board card shows a dashed Not delivered label. The weekly report does not count the story as delivered. Choose Reopen on the story page to bring the story back to the backlog.

kanman can close a maintenance story the same way when a later scan no longer finds what it was about. Its reason is No longer applicable. See What happens with findings.

Classes of service

The class of service decides urgency. expedite work (for example a CI regression, an outage or a security fix) goes first. fixed_date, standard and maintenance follow the normal rules. To expedite a story, ask kanman in the conversation, for example “expedite SBX-12”; “deprioritise SBX-12” sets it back to standard. Critical maintenance findings are filed as expedite automatically.

Related

• Write requirements kanman can finish
• Your first story
• How kanman checks its work