When a Tool Earns Its Place

You have run the loop a few times now. Each hypothesis is a file, each result is a file next to it, and every one is committed.

This chapter is about the moment that stops being enough — and about how to tell the difference between that moment and the feeling that you ought to have a proper system. They are not the same, and only one of them is a reason to do anything.

The signal

It is not the number of files. It is a change in what costs you effort.

While you are writing things down, files are perfect. Writing is cheap, and a folder imposes nothing.

The signal is when you start spending time finding things instead of writing them. Concretely, you will catch yourself doing one of these:

• opening three files to remember which prediction you already checked
• writing a hypothesis, then half-remembering you wrote nearly the same one in June
• wanting to answer "what am I waiting on?" and having no way to ask
• avoiding starting a new one, because the folder has become a place things go quiet

That last one is the real tell. A system you avoid using is worse than no system, and the avoidance shows up before you can articulate why.

If none of that has happened, you do not need a board yet. That is not a stalling answer — see below.

The case for doing nothing

Most advice at this point sells you something. Here is the argument on the other side, seriously meant.

A board is a cost. It is a thing to install, a place your work now lives, a set of conventions to remember, and something that can be out of date. It buys you nothing while you have six files, because scanning six files is instant.

HDD is a discipline, not a tool. Everything you have done so far — the prediction, the number, the commit, the check, the honest record — is the whole method. A board does not make any of it more true. It makes it cheaper to do often, which only matters once you are doing it often.

A perfectly good answer to this chapter is: "not yet, and here is why."

Write that down, in the folder, with a date. In two months you will either have hit the signal — and your note will tell you what you were waiting for — or you will not, and you will have saved yourself a tool.

If you have hit the signal

Here is the whole setup. It took four seconds on a clean machine when I walked it for this chapter.

pip install yurtle-kanban

Then, in the folder you already have — the one with your hypotheses in it:

yurtle-kanban init --theme software

That is it. No account, no server, no sign-up, nothing running in the background. It creates some folders and a config file next to your work, and it leaves your existing files exactly where they are.

⚠ The --theme part is required — a bare yurtle-kanban init is not the command. software is the right theme here; there is a research-flavoured one, and it is not the one you want yet (I say why at the end).

What a board actually is

If you have never used one, the vocabulary is smaller than it looks.

A board is a set of columns, and a column is a state your work can be in. That is the entire idea. The software theme gives you five:

Backlog  │  Ready  │  In Progress  │  Review  │  Done

An item sits in exactly one column, and moving it between columns is how you record that something changed. There is no more to it than that.

The columns are not a schedule and not a hierarchy. They answer one question — where is this? — and the value is that you can ask it about everything at once instead of opening files.

The one number that is not obvious

Look at the board's header and you will see something like Ready (0/5) and In Progress (0/3).

That second number is a limit on how many things may sit in that column at once. It is called WIP — work in progress — and it is the one part of a board that people delete first and miss most.

It reads as a restriction. It is the opposite: it is a limit on how many things you are allowed to be halfway through. Five hypotheses open at once is five things you are partly holding in your head, and the cost of that is not linear — it is the reason none of them are finishing.

You will not feel the benefit immediately. You will feel it the first time the board refuses to let you start a sixth thing and you notice you were about to.

Carrying your work in

Your hypotheses are already files. Do not retype them into the tool. Tell your agent:

Look at the files in my hypotheses folder. For each one, create an item on the
kanban board with the same title, and put the hypothesis and its number in the
body. If I already recorded a result for it, put the item in Done. If I have
not checked it yet, leave it in Backlog.

Then look:

yurtle-kanban board

The point of doing it this way is that nothing is invented. The board is now a view of work you had already done, so if it tells you something surprising — three things half-checked, or one sitting untouched since spring — that surprise is real information, not a side effect of setting up a new toy.

The part nobody tells you about

Open one of the items the tool just made. Not in the board — the actual file, in your editor.

You will see your title and your prose, and above it something like this:

<#IDEA-R-001> a kb:Idea ;
    kb:title "Do most support tickets come from one feature" ;
    kb:status "backlog" ;
    kb:created "2026-08-27" .

Read it out loud as three-word sentences. This item is an Idea. This item has the title "…". This item has the status "backlog".

Each line names a thing, a property, and a value. That is all a knowledge graph is — a pile of three-part statements, and anything that can be said in three parts can be asked about later.

You have been writing one since you opened this chapter, and nobody had to explain the phrase first. That is the actual reason we suggest this tool rather than the faster one we also make: the graph is right there in the file you were already reading. In a database it is real but invisible, and invisible things are hard to learn from.

Nothing about this is a prerequisite. You can use the board for a year and never think about it. But when you eventually want to ask "show me every hypothesis I refuted in the last six months", the answer will already be in your files — you will just be reading them a different way.

What is rough about this

The tool has sharp edges, and you should hear them from us rather than find them.

The board counts items it does not draw. Create an item, and the column header will say Draft (1) above an empty column. yurtle-kanban list shows it correctly. It is a display bug, your data is fine, and it is filed as #87 — the item's status is backlog while the theme's columns are Draft/Active/Complete/Abandoned, so the count and the placement disagree.

⚠ I nearly missed it, and how is worth more than the bug. A fresh board shows (0) above an empty column — which looks perfectly correct. I wrote "fixed" in my notes. A count of zero and a drawing of nothing are indistinguishable when there is nothing to draw, and I only found out by creating a real item.

That is chapter 2's lesson — check hardest when the answer pleases you — happening to me while writing chapter 3. It does not get less true with practice. It gets faster to catch.

There is a research-flavoured theme, and on the current release it is not ready for you. --theme hdd creates folders for papers and experiments, and on 2.1.0 — what pip install gives you today — its first command refuses to let you state a hypothesis until you have invented a research paper to attach it to.

That was a bug rather than a philosophy, and it has been fixed in the repository — but not yet released, so you will still meet it. Check the version you actually have before assuming either way.

Either way, use --theme software here: you are tracking your thinking, not running a research programme, and the research theme's folders are answering a question you have not asked.

Where to go next

• Use it for two weeks, then ask whether it earned its place. If you cannot say what it fixed, delete it. The files were always the real thing.
• If you decided "not yet" — you are not behind, and you have a dated note saying what you were waiting for. That note is worth more than an empty board.
• When you want to go faster than one loop at a time, that is a different book: the developer track covers the same ideas built for agents rather than people.