Generate the Edge-Case Spec Pack for Handoff

Workflow area: Handoff & Collaboration · Tier: Foundation · Hands-on time: ~25 minutes per flow

Handoff debt is the gap between what you designed and what the file says. Engineers fill that gap with guesses, and increasingly their coding agents fill it with statistically-plausible inventions — an unspecified error state doesn't stay unbuilt anymore, it gets hallucinated. The spec pack was always the right answer and never got written because it's tedious. It's also exactly the document type AI drafts well from the raw material you already have: frames, the pb-07 state matrix, critique notes, and your answers to pointed questions.

When to use — and when not to

• Use it for every flow crossing the design-engineering boundarythe pack is the review reference when the build comes back, whoever or whatever built it.
• Use it when engineering runs AI coding toolswritten rules are precisely what keeps a coding agent from inventing behavior your frames never specified.
• Use it for design-system contributionsa component without content rules and interaction specs isn't a component, it's a picture.
• Skip it for explorationsspec packs are for things being built; pb-04's throwaway pages must never acquire one, or they'll get built.
• Don't let it replace conversationthe pack is the record of shared understanding, not a substitute for the meeting that creates it.

The recipe

1. 1.

   Assemble the inputs. The pack drafts itself only if the material exists: exported frames (all states from pb-07's sweep), the curated state matrix, interaction notes and critique decisions (pb-09's records if you keep them), and your design system's relevant component names.

2. 2.

   Generate the pack skeleton per screen. In Claude or ChatGPT, attach the frames and run:

   Copy

   You are drafting an engineering-facing spec pack for this flow.
   Extract what the frames show; ASK rather than invent what they
   don't.
   
   Flow: [NAME + ONE-LINE PURPOSE]
   Design system: [e.g. "our DS component names are on each frame"]
   State matrix: [PASTE FROM pb-07]
   Notes: [PASTE INTERACTION/CRITIQUE NOTES]
   Frames: [ATTACH — ALL STATES]
   
   For each screen produce:
   1. STATE TABLE — every state, what triggers entry/exit, what
      persists across transitions
   2. INTERACTION RULES — per interactive element: action, result,
      disabled conditions, loading behavior, keyboard path
   3. CONTENT RULES — per text slot: min/max length, truncation
      behavior, empty behavior, localization stretch (+30%)
   4. A11Y ANNOTATIONS — focus order, semantic roles, alt-text
      intent, touch-target notes, reduced-motion behavior
   5. OPEN QUESTIONS — everything the frames and notes do NOT answer,
      as questions addressed to the designer. Do not resolve these
      yourself.
   

3. 3.

   Answer the open questions — this is the designing. The question list is the pack's most valuable output: it's every gap an engineer or agent would have filled with a guess. Good output looks like:

   Copy

   OPEN QUESTIONS — Review screen
   Q1: Amount field — behavior when currency has no decimal
       subunit? → A: hide decimals, spec added to CONTENT RULES
   Q2: What happens to a half-completed form on session timeout?
       → A: persist locally 24h, restore banner on return —
       NEW STATE added to matrix, frame needed
   Q3: Focus order after inline error appears? → A: focus moves to
       first errored field, error text in aria-describedby
   

   Note Q2: spec-drafting routinely discovers missing design work. That's the pack paying for itself before handoff.

4. 4.

   Verify the drafted tables against your frames. The model extracts, and extraction has error bars — it will misread a disabled state as default, or invent a hover behavior because most buttons have one. Walk each state table against its frame; anything in the spec not visible in a frame or written in your notes is either a discovered gap (design it) or a hallucination (delete it). Accessibility annotations get checked against your actual intent, not accepted as plausible defaults — the pack's a11y section feeds pb-31's gate, not replaces it.

5. 5.

   Publish the pack next to the frames and use it at review. A page in the Figma file (or the team's Notion, per your convention) — versioned with the design, linked from the ticket. When the build comes back, the pack is the checklist: state by state, rule by rule. Deviations are either bugs or undocumented decisions, and both get resolved in writing.

Make it yours

• Notion AI for the living-document version: if engineering works from Notion tickets, draft the pack there — tables stay editable through build, and the Q&A section becomes a running design-eng thread with history.
• Claude Project per product surface: store your DS component names, content-rule defaults and a11y conventions in Project instructions — every pack starts consistent, and repeated rules ("all currency fields behave like this") get stated once and inherited.
• Dev Mode annotations as the delivery channel: paste the per-element rules into Figma Dev Mode annotations on the frames themselves for teams that live in the file — the pack remains the master, annotations are its projection into the canvas (and pb-34's MCP-ready files inherit the same discipline).

Quality check

• Every state in the matrix appears in the packand every state in the pack exists as a frame; a specified-but-undrawn state is a work item, not a footnote.
• No invented behavior survivedeverything in the tables traces to a frame, a note, or an answered question; plausible defaults the model added get caught by the walk-through.
• All open questions are answeredan unanswered question ships as a guess; if it can't be answered yet, it's marked as a deliberate deferral with an owner.
• Content rules include the stretch casesmax lengths, truncation, and +30% localization on every user-visible string; these are the rules coding agents violate first.
• A11y annotations reflect intent, not boilerplatefocus order matches the actual reading logic of the screen; generic annotations fail real users while passing review.
• The pack is versioned with the designa spec describing last week's frames is actively worse than no spec.