Catalog chaos isn't a data problem, it's a transitions problem. Anyone can list the states a SKU can be in. The hard part is governing the moves between them — and that's exactly what ALLOWED_TRANSITIONS does. After running Linen House on it for a year, here's the field guide I wish I'd had.
The eight states
- draft — created, not yet live.
- active — live and sellable.
- throttled — live but velocity-capped pending confidence.
- promoted — actively boosted in merchandising.
- watch — flagged for a metric breach, still live.
- winding_down — being phased out, no new promotion.
- archived — removed from sale, retained for history.
- blocked — held by policy or a compliance flag.
The states are unremarkable. The power is in which arrows between them are legal, and what happens when an agent wants to draw an arrow that isn't.
Invalid transitions become rows, not errors
If the agent proposes archived → promoted, that's not a valid move. In a naive system it either silently does it or throws an exception nobody reads. In Magistry it becomes a review row: the agent's intent, the illegal transition it wanted, and a request for an operator to either open the transition or decline it.
{
"product_id": "sku_4471",
"from_state": "archived",
"to_state": "promoted",
"action": "PROMOTE",
"decision": "blocked_invalid_transition",
"note": "archived SKUs cannot be promoted directly; route via active",
"needs": "operator_review"
}That row is gold. It tells you the agent saw something promotable in an archived SKU — maybe the supplier came back, maybe demand returned — and it surfaced that as a question instead of forcing it as a mutation. You learn where your lifecycle rules are too strict, and you tune them with evidence instead of guesswork.
The first month, the review rows taught me my own catalog rules were wrong in four places. The agent wasn't misbehaving — it was reporting reality.
— Maya Chen, Linen House
How to run it
Start tight. Open transitions only after a review row proves you need one. A permissive state machine that lets anything move anywhere is just chaos with extra steps. A strict one that turns every exception into a logged question is a catalog that gets cleaner every week — and explains itself while it does.