figma-comment-fix-loop

Closed pipeline: stakeholder comments -> clusters -> parallel read-only analysis -> fixes serialized through the bridge -> evidence package -> optional independent review -> rounds until closed. Distilled from 3 review rounds on one client project (field note, 2026-07). Every gotcha below was paid for in production. Do not skip any of them.

Required sub-skills: figma-bridge-doctor (connection), figma-canon + figma-preflight (before any write), figma-orient (file that is new to the session).

Tool names are written as base names. The prefix depends on the client. Tools named figma_* belong to the figma-console MCP server. With only the official Figma MCP server connected, Phase 2 writes go through use_figma on path B of figma-preflight Check 0 (not validated by this repo: keep writes small, read back every change), and get_screenshot replaces figma_capture_screenshot within the budget in figma-canon/references/rate-limit-recovery.md.

Resolving is a human step. Nothing can resolve a comment through the API. The REST API and the MCP tools can read, post, reply and delete comments, and @mentions post as plain text. This skill changes the screen and prepares the evidence. Then the human resolves the thread in Figma, or the agent replies in the thread when the designer asks for that (see Phase 3).

Phase 0: Comments (REST, never the Plugin API)

The Plugin API cannot read comments. Comments are read through the REST API, or through figma_get_comments, with the personal access token in the FIGMA_ACCESS_TOKEN environment variable. The figma-console MCP server reads the same variable, but it takes its own copy from its MCP config, and that copy can be older than the one in your shell. Never print the token, never write it to a file, never ask for its value in the chat. If the variable is not set in the shell, ask the user to export it there.

• figma_get_comments tends to return 403 when the token copy in the MCP server config is stale. Canonical path: call the REST endpoint directly, GET https://api.figma.com/v1/files/<fileKey>/comments with the X-Figma-Token header. Keep the raw JSON.