docs / guides / resolve a placement hold

Resolve a placement hold.

A hold means Balladeer did not record a decision. Either it landed very close to one your team already has, or it strains a rule your team made binding. The intended decision is not in your team's memory until you rule on it, and one ruling resolves each hold.

balladeer queues lists the holds (and your live conflicts) with the proposed claim, the question it answers, and the decisions it was held against. balladeer placement lists the holds alone. Each decision a hold was weighed against carries four facts on one line: who decided it, when it formed, how settled it is (an unconfirmed one shows its confidence figure), and MUST when it is a binding directive. Those are what the ruling turns on, so they arrive with the hold rather than behind a second lookup.

Held against a near-match

The common hold: what was proposed reads like a decision your team already made. Five rulings; one of them resolves it:

$ balladeer place <id> <ruling> [target] same_as it IS that decision; fold into it parent_id it refines that decision; file it underneath supersedes it replaces that decision parent_of it sits ABOVE those decisions not_same_as genuinely different; say why in one line

Held against a MUST

The other hold, a deviation: the work would cross a decision your team made binding, and it was proposed as an exception to that rule. The hold arrives with that MUST as its only candidate, and three rulings are open:

$ balladeer place <id> <ruling> [the MUST] excepts a carve-out for this case; the MUST still governs everywhere else supersedes the rule itself is wrong; this replaces it withdraw stand down; the hold is discarded and nothing is written

excepts is the common case, and it records the exception against the rule rather than quietly widening the rule. The author of the MUST is told when the exception commits.

Say why

Every ruling but withdraw carries a justification: how this decision sits relative to what it was held against, which one it is the same as, which it is distinct from, and why. One candidate takes one reason (--justification). Several candidates each take their own (--justify decision_ab12cd34ef56=why, once per candidate), and a single blanket justification will not clear a multi-candidate hold. not_same_as also takes the one-line difference (--reason). These reasons train the duplicate detector on your team's own sense of distinctness, which is why they are required rather than optional.

Ruling without re-typing anything

The ruling reuses the proposal that was held, so the claim cannot drift between what was proposed and what gets recorded. Rulings are duplicate-proof: sending the same one twice lands once. And every hold has a handle: balladeer decision <id> reads it back in full, and balladeer dismiss <id> discards a hold that was simply wrong.

Verified from live product as of 28 jul 2026.