---
name: boardability-doctor
description: Script-readiness pass for storyboard translation; checks 5 boardability categories, canon-aware, OAuth/claude_cli only, $0.
allowed-tools: Bash, Read
argument-hint: "[project] --episode N [--gate]"
---

# /boardability-doctor - Script Readiness for Storyboards

Run a canon-aware boardability pass on one episode script before storyboard derivation. It flags script text that is likely to produce wrong, inconsistent, or unboardable frames.

runs on claude_cli (OAuth, $0) — never Gemini

## Usage

```
/boardability-doctor [project] --episode N
/boardability-doctor [project] --episode N --gate
```

Equivalent tool entrypoint:

```
python3 -m recoil.tools.boardability_doctor --project [project] --episode N
python3 -m recoil.tools.boardability_doctor --project [project] --episode N --gate
```

## Categories

| Category | What it catches |
|----------|-----------------|
| `under_specified_staging` | Vague action a boarder cannot render reliably, such as a character doing "something" with a panel. |
| `unrenderable_authorial` | Thoughts, impossibilities, judgments, or prose that a frame cannot show. |
| `mechanic_legibility` | Load-bearing causal mechanics that will not read clearly in one board. |
| `spatial_ambiguity` | Geometry, motion, placement, or object references the renderer cannot place. |
| `reference_inconsistency` | Props, positions, or visual elements that drift across boards without an anchor. |

## Severity Rubric

| Severity | Meaning |
|----------|---------|
| `P1` | The script as written will produce a wrong or inconsistent board, or asks the board to depict something un-renderable. Blocks boarding. |
| `P2` | Ambiguity that risks cross-board drift but a competent boarder can resolve. |
| `P3` | Minor or polish issue. |

## Gate Use

Use `--gate` before re-deriving boards from script changes. The command exits nonzero when any `P1` finding remains, so it can block a pre-rederive workflow until the script is boardable.

## Implementation

This skill delegates to `recoil/tools/boardability_doctor.py`, which resolves scripts and bible files via project paths, calls `claude_cli`, writes the boardability brief, and returns gate status.