An item’s life: fourteen states and three lanes

Design

Every state an idea for a tool can be in, the moves between them that are not a straight line, and the three priority lanes that decide what is worked on first.

J.1.34 min readLast revised November 2026

Status: Design. A specification. It describes how the component is meant to work, not something you can use on this site today. What the labels mean.

On this page

The fourteen states
Which worker makes each move
Three priority lanes
What does not get lost

Every idea for a tool is an item with an identifier of the form PA-0001 and exactly one state. This page lists the fourteen states, shows which worker moves an item from one to the next, and explains the order in which waiting items are taken.

The fourteen states#

An item does not always go straight from found to live. It can leave early, wait for something outside the project, or come back after it was finished.

StartDiscoveredA candidate address or a request has been captured.
- Moves to Recorded when it is given an identifier and is not a duplicate
RecordedOn the list, waiting to be looked at.
- Moves to Observed when its public pages have been read
ObservedWhat it does, and the rule it cites, are written down.
- Moves to Screened out when it fails any knockout gate
- Moves to Scored when it passes all five gates
- Moves to Needs a sub-tool when a worker has no rule for what it found
PausedNeeds a sub-toolWaiting for a rule to be written for this case.
- Moves to Observed when the rule ships and the item is run again
Can be reopenedScreened outFailed a gate. The reason is recorded.
- Moves to Observed when the owner overrides, or the idea is reshaped
ScoredRated on the 100-point rubric, with a recommendation.
- Moves to Approved when the owner chooses to build
- Moves to Linked when a free, private tool already does the job
- Moves to Merged when it belongs inside another tool
- Moves to Parked when it is worth doing but blocked
- Moves to Rejected when it falls below the threshold
WaitingParkedHeld, with the thing blocking it named.
- Moves to Observed when the blocker clears
Catalog: plannedApprovedTo be built. The credit note and the specification are written.
- Moves to Building when its repository is generated
Catalog: in developmentBuildingBeing built and checked.
- Moves to Live when it passes all five listing conditions
Catalog: liveLiveIn the catalog and being watched.
- Moves to Building when the rule it rests on changes
- Moves to Retired when the rule is repealed or replaced
EndRejectedDeclined. The reason and the score are kept.
End state
EndLinkedThe catalog points to the existing tool instead of rebuilding it.
End state
EndMergedFolded into another tool as a feature.
End state
EndRetiredTaken out of use, with a note of why.
End state

Figure The states of an item, from first sighting to the catalog or the archive

Which worker makes each move#

State	What it means	Usually goes to	Other moves
`discovered`	Trawl has seen a candidate	`recorded`	`rejected` if the address is dead or a duplicate
`recorded`	It has an identifier	`observed`	`needs_subtool` if the source is in a form intake has no rule for
`observed`	Sextant has read its public pages	`scored` or `screened-out`	`needs_subtool` if the page layout is unfamiliar
`screened-out`	Assay found it fails a gate	Stays there	The owner can send it back to `observed`
`scored`	Assay has rated it	`approved`	The owner can choose `parked`, `linked`, `merged` or `rejected`
`approved`	The owner chose to build, and Waybill wrote the specification	`building`	`needs_subtool` if there is no profile for that kind of tool
`building`	Moldloft generated it and Shakedown is checking it	`live`	`parked` if the rule turns out to be unclear
`live`	Chartroom published it	Watched by Tidegauge	Back to `building` when the rule changes, or `retired` when it is repealed
`parked`	A good idea that is blocked	Stays there	Back to `observed` when Tidegauge sees the blocker clear
`linked`	The catalog points at an existing tool	Watched by Tidegauge	Back to `observed` if that tool breaks or starts tracking users
`merged`	Folded into another tool	Stays there	Back to `observed` only if the other tool is retired
`rejected`	Declined, with the reason public	Stays there	None, unless it is sent in again as a new candidate
`retired`	Removed from use, with a note	Stays there	None
`needs_subtool`	A worker stopped instead of guessing	Back to the worker that paused it	Runs again automatically once the missing rule ships

The three catalog labels a reader sees come from these states: approved shows as Planned, building as In development and live as Live.

Three priority lanes#

Every waiting item is in one of three lanes. Each worker empties the urgent lane before it touches the normal one, and the normal one before backfill. That keeps a small machine responsive while a large sweep is running.

Lane	What goes in it	How it is handled
`urgent`	A change in a regulation that affects a live tool, an edit the owner has approved, and items being run again after a missing rule shipped	Taken first at every worker, so fixes to live tools finish before anything else
`normal`	Single candidates from requests or the owner’s own research, and routine scheduled checks	Taken in the order they arrived, once the urgent lane is empty
`backfill`	Bulk finds from automated sweeps, and old records	Taken only when both other lanes are empty

What does not get lost#

Two things protect work in progress. An item a worker has claimed goes back in the queue if that worker stops, because its lease runs out. And a result a worker has finished is kept on the worker’s own disk until the queue service confirms it has it, so a restart in the middle loses nothing. Cluster architecture describes both.

Found a mistake, or something that has gone out of date? Open an issue or write to [email protected]. This page is a text file you can read and correct: Source of this page.