/balise-handoff

name: balise-handoff
description: Audits and prepares designs, specifications, prototypes, design-system artifacts, and implemented interfaces for developer handoff using explicit scope, source-of-truth mapping, evidence levels, risk-based gates, open-decision ownership, and acceptance criteria. Use to assess whether a Figma selection or product surface is ready for implementation, improve developer handoff, review Ready for dev claims, assemble a handoff contract, trace design-to-code provenance, or revalidate a design after changes.

Handoff Readiness

Determine whether a specific version can be implemented without unresolved critical ambiguity. Treat readiness as an evidence-based agreement between people, artifacts, and systems—not as file cleanliness, a universal checklist, or a promise that future code will be correct.

Operating contract

• Audit the requested selection, flow, component, feature, or release—not the entire workspace by default.
• Preserve source designs, components, specifications, code, tickets, and status markers unless the user explicitly authorizes edits.
• Identify the target platform, implementation team, release context, design-system relationship, and risk before applying gates.
• Reuse the team's existing vocabulary, components, tokens, documentation, tickets, tests, and delivery workflow.
• Distinguish **observed**, **structurally inferred**, **documented**, **simulated**, **linked to code**, **runtime verified**, and **unknown**.
• Never treat a Figma status, annotation, prototype, generated snippet, component name, or visual match as runtime proof.
• Never invent API behavior, data shape, permissions, breakpoints, accessibility semantics, analytics, asset rights, or implementation constraints as facts.
• Do not require every dimension mechanically. Apply gates proportionally, but never average away an unresolved critical blocker.
• Make every open critical decision actionable with impact, owner, next action, and fallback when one exists.
• Do not turn handoff into a final ceremony. Prefer evidence produced and maintained throughout product work.

Choose the mode

Infer the mode from the request. Default to **Audit** when edit intent is absent.

| Mode | Action | | --- | --- | | **Audit** | Inspect evidence, apply gates, and issue a readiness verdict without editing. | | **Prepare** | Add or repair handoff structure, annotations, mappings, links, and decision records after explicit edit intent. | | **Verify** | Reinspect affected gates after corrections, implementation, or design-system changes. | | **Contract** | Produce a durable handoff summary from available evidence without changing the source. | | **Complete** | Audit, prepare authorized changes, reverify, and deliver the contract. |

Audit and Verify are read-only. In a design tool, Prepare should use a labeled handoff area or copy by default. Edit source frames, shared components, status markers, or production code only when the user explicitly requests that mutation.

Load only the needed references

• Read [readiness-model.md](references/readiness-model.md) when selecting gates, classifying severity, assigning evidence, or deciding the verdict.
• Read [figma-execution.md](references/figma-execution.md) when the source or output includes Figma frames, components, variables, prototypes, annotations, Dev Mode, Code Connect, or MCP context.
• Read [source-of-truth-and-change.md](references/source-of-truth-and-change.md) when design and code disagree, sources are distributed, dependencies changed after handoff, or provenance is unclear.
• Read [implementation-evidence.md](references/implementation-evidence.md) when inspecting code, Storybook, tests, runtime behavior, accessibility, assets, data contracts, or acceptance proof.
• Use [handoff-readiness-contract-template.md](assets/handoff-readiness-contract-template.md) when the user requests a durable readiness report or implementation package.

Workflow

1. Frame the handoff candidate

Establish:

• selected surface and stable artifact link or path;
• exact version, branch, revision, status, or review date;
• included and excluded flows, states, platforms, and viewports;
• intended release, implementation audience, and decision owner;
• user and product goal;
• known design-system, codebase, data, asset, and policy dependencies;
• risk profile and requested outcome.

If scope or version cannot be identified, do not inspect arbitrary nearby work and call it the target. Mark the candidate **Not assessable** until the missing boundary can be resolved.

2. Choose a proportional profile

Use the lightest profile that still controls the real risk:

• **Quick:** small, reversible change; colocated team; known implementation; low consequence.
• **Standard:** ordinary feature or component handoff; inspect every dimension and activate applicable gates.
• **Deep:** external or distant team, new platform, wide reuse, migration, money, identity, permissions, sensitive data, safety, security, localization, or consequential accessibility risk.

State the profile and why. A Deep profile changes evidence requirements; it does not justify auditing unrelated surfaces.

3. Inspect the real delivery ecosystem

Inspect the selected artifact and relevant adjacent evidence:

• parent flow, alternate branches, states, prototypes, and annotations;
• components, instances, properties, overrides, libraries, variables, modes, styles, tokens, and layout rules;
• product requirements, decisions, tickets, API or data contracts, content sources, asset sources, and analytics requirements;
• canonical code components, routes, state owners, tests, Storybook stories, Code Connect mappings, and release history;
• status, version history, change notes, owners, and communication channel.

Presence is not freshness. A linked ticket may be stale; a matching name may represent a different concept; a clean frame may omit behavior. Record access limitations in