splicedeck: Skill for Claude Code

Recovering from a refusal

A splicedeck refusal is a successful call that carries its own correction. It is not an error to report and not a wall to work around. Ninety-four codes exist so that recovery is one turn rather than a diagnosis.

The full catalogue, generated from the code, is in references/refusal-codes.md. Read it when you need a specific code. The four rules below are what you need every time.

The four rules

1. When retry_with is non-empty, send one of those calls verbatim.

The server built them from what it already knows — the handles that exist, the bookmarks that are shipped, the rung that is proven. Re-deriving the arguments yourself turns a one-turn recovery into a guessing loop, and you will get it wrong in exactly the places the server would not.

{"ok": false, "refused": "SHEET_NOT_VERIFIED",
 "retry_with": [{"verb": "verify", "args": {"sheet": "c1"}}]}

Send verify(sheet="c1"). Do not construct something similar.

2. When needs_human is true, stop and report human_step.

No call you can send fixes it. Saying so plainly is the correct outcome. Inventing a workaround here is worse than stopping, because the workaround usually means disabling the thing that refused.

3. Never install anything in response to a refusal.

FFMPEG_ABSENT does not mean "go and get ffmpeg". This project never installs, downloads, vendors or bundles ffmpeg — that is a deliberate rule, not an omission, and docs/first-run.md §4 gives the three reasons. The same holds for TIER_BINARY_ABSENT. Report the step; the human runs it.

4. A refusal is not a reason to change the plan.

Most refusals mean one call is missing, not that the approach is wrong. Add the call and continue.

The ones you will actually hit

Code	What it really means	Do this
UNKNOWN_HANDLE	The handle was never minted here — or, on splice, you passed a source handle where a sheet source key belongs	inspect first; for splice, read sources[].key out of the sheet
SHEET_NOT_VERIFIED	The sheet changed since verify	run verify again, then retry
GATE_BLOCKING	A gate fails, commonly an empty body lane	run verify to see which; splice a segment if the body is empty
BOOKMARK_UNKNOWN	No bookmark by that name	retry_with lists the ones that exist; only baseline ships
UNKNOWN_PARTY	No directory at casebook/parties/<party>/	a human creates it; mkdir is the whole step
ENCODER_UNPROVEN	ffmpeg lists it, this machine cannot run it	run trial; never substitute an encoder yourself
NOT_ON_WORD_EDGE	A cut edge falls inside a word	retry_with carries two calls, one keeping the word and one excluding it — pick by meaning
VALUE_NOT_PERMITTED	An argument carried a value where an identifier belongs, usually a key that looks like a path	send a plain identifier
RIGHTS_MISSING	An asset has no licence record	human step; delivery will not proceed without one
LANE_DISK_SHORT	Not enough free space for the planned run	report the numbers; the human frees space