Skills

turning-handoffs-into-decisions

Rewrites a design handoff so engineering gets decisions instead of guesses: every state, edge case, and rule a developer would otherwise have to invent is either decided or flagged as an open question with an owner.

SKILL.md
---
name: turning-handoffs-into-decisions
description: "Rewrites a design handoff so engineering gets decisions instead of guesses: every state, edge case, and rule a developer would otherwise have to invent is either decided or flagged as an open question with an owner. Use when the user shares a Figma link, screenshots, a spec, a ticket, or handoff notes and wants it cleaned up, checked for gaps, made dev-ready, or turned into a spec, even if they just ask \"is this ready to hand off?\""
metadata:
  category: design
---
# Handoff into decisions

Read the handoff the way the engineer building it will. Every place they would have to guess becomes a decision or an open question. Nothing stays implied.

## How to work

1. Name what is being built and the one thing it must do well. If you cannot, that is the first open question.
2. Walk every screen and component through its states: empty, loading, partial, full, error, success, disabled, and the first-time view. Mark each as shown, described, or missing.
3. Walk the edges: long text, no text, one item, a thousand items, slow network, no permission, mobile width, keyboard only.
4. List the rules a developer would otherwise invent: what sorts first, what truncates and where, what is required, what happens on double click, what is undoable.
5. For each gap, decide it if the design makes the answer obvious. If it does not, write it as a question with a suggested default and who should answer.

## Gotchas

- A mockup shows the happy path with perfect content. Assume every gap you do not flag will be filled by the engineer's best guess, and that the guess ships.
- "Same as the other screen" is not a decision unless you name the screen and it really covers this case.
- Do not redesign. If something looks wrong, flag it as a question; the handoff is not the place to change the direction.
- Keep decisions short enough to paste into a ticket.

## Output

# Handoff: [feature]

**What it must do well:** [one line]

## Decided
- **[screen or component], [state or case]:** [the decision]

## Open questions
- **[case]:** [the question]. Suggested default: [answer]. Owner: [design / product / eng].

## States checklist
| Screen | Empty | Loading | Error | Full | Mobile |
|---|---|---|---|---|---|
| [name] | shown / described / missing | ... | ... | ... | ... |