canicode 0.11.0 → 0.11.1

package/skills/canicode-roundtrip/helpers.js

@@ -78,8 +78,189 @@ ${footer}`;
     }
   }
 
+  // src/core/roundtrip/annotation-payload.ts
+  var CANICODE_JSON_FENCE = "```canicode-json";
+  function formatIntentValueForDisplay(value) {
+    if (value === void 0) return "undefined";
+    if (value === null) return "null";
+    if (typeof value === "object") {
+      try {
+        return `\`${JSON.stringify(value)}\``;
+      } catch {
+        return String(value);
+      }
+    }
+    return `\`${String(value)}\``;
+  }
+  function buildCodegenDirective(args) {
+    const { sceneNodeId, intent } = args;
+    const val = intent.value === void 0 ? "undefined" : JSON.stringify(intent.value);
+    return `When generating code for node ${sceneNodeId}, set ${intent.field} to ${val} (user intent, scope: ${intent.scope}). Prefer this over the current Figma scene value when they disagree.`;
+  }
+  function sceneOutcomeToAck(result, reason) {
+    return reason !== void 0 ? { result, reason } : { result };
+  }
+  function buildOutcomeHumanLine(args) {
+    if (args.skippedDefinitionDueToAdr012) {
+      const adrHint = " Canicode skipped writing the source component without `allowDefinitionWrite: true` (ADR-012 safer default). The instance-level change did not apply as intended in the scene.";
+      if (args.reason === "silent-ignore") {
+        return "**Scene write outcome:** The write ran, but the property value did not change on this instance (silent-ignore)." + adrHint;
+      }
+      return "**Scene write outcome:** Figma rejected an instance-level change" + (args.errorMessage ? `: ${args.errorMessage}` : "") + "." + adrHint;
+    }
+    if (args.reason === "silent-ignore") {
+      return "**Scene write outcome:** The write ran, but the property value did not change on this instance (silent-ignore). No source definition was available to escalate.";
+    }
+    if (args.reason === "override-error") {
+      return "**Scene write outcome:** Figma rejected an instance-level change" + (args.errorMessage ? `: ${args.errorMessage}` : "") + ". No source definition was available to escalate.";
+    }
+    return "**Scene write outcome:** Could not apply automatically" + (args.errorMessage ? `: ${args.errorMessage}` : "") + ".";
+  }
+  function buildAdr012PropagationParagraph(args) {
+    const { componentName, replicaCount } = args;
+    const fanOutHint = typeof replicaCount === "number" && replicaCount >= 2 ? ` This batched question covers ${replicaCount} instance scenes \u2014 changing **${componentName}** at the definition still affects every inheriting instance, not just one row in the batch.` : "";
+    return `Canicode's safer default (ADR-012) is to skip writing the source component **${componentName}** without explicit opt-in, because that write propagates to every non-overridden instance of **${componentName}** in the file.${fanOutHint} Prefer a manual override on **this** instance when you only need a local fix. Use \`allowDefinitionWrite: true\` only when you intend to change **${componentName}** for all inheriting instances \u2014 it is not a neutral shortcut for a single-instance tweak.`;
+  }
+  function buildDefinitionWriteSkippedBody(args) {
+    const {
+      ruleId,
+      sceneNodeId,
+      componentName,
+      reason,
+      errorMessage,
+      replicaCount,
+      intent
+    } = args;
+    const ackIntent = intent ? {
+      field: intent.field,
+      value: intent.value,
+      scope: intent.scope
+    } : void 0;
+    const sceneWriteOutcome = sceneOutcomeToAck("user-declined-propagation", "adr-012-opt-in-disabled");
+    const codegenDirective = intent !== void 0 ? buildCodegenDirective({ sceneNodeId, intent }) : void 0;
+    const jsonBlock = {
+      v: 1,
+      ruleId,
+      nodeId: sceneNodeId,
+      ...ackIntent ? { intent: ackIntent } : {},
+      sceneWriteOutcome,
+      ...codegenDirective ? { codegenDirective } : {}
+    };
+    const userAnswerLine = intent !== void 0 ? `**User answered:** ${formatIntentValueForDisplay(intent.value)} for **${intent.field}** (scope: ${intent.scope}).` : null;
+    const outcomeLine = buildOutcomeHumanLine({
+      reason,
+      ...errorMessage !== void 0 ? { errorMessage } : {},
+      skippedDefinitionDueToAdr012: true
+    });
+    const adrBlock = buildAdr012PropagationParagraph({
+      componentName,
+      ...replicaCount !== void 0 ? { replicaCount } : {}
+    });
+    const proseParts = [userAnswerLine, outcomeLine, adrBlock].filter(
+      (p) => p !== null
+    );
+    const prose = proseParts.join("\n\n");
+    return appendJsonFenceAndFooter(prose, jsonBlock, ruleId);
+  }
+  function buildNoDefinitionFallbackBody(args) {
+    const { ruleId, sceneNodeId, reason, errorMessage, intent } = args;
+    const ackIntent = intent ? { field: intent.field, value: intent.value, scope: intent.scope } : void 0;
+    const outcomeResult = reason === "silent-ignore" ? "silent-ignored" : reason === "override-error" ? "api-rejected" : "api-rejected";
+    const sceneWriteOutcome = sceneOutcomeToAck(
+      outcomeResult,
+      reason === "silent-ignore" ? "silent-ignore-no-definition" : "no-definition-escalation"
+    );
+    const codegenDirective = intent !== void 0 ? buildCodegenDirective({ sceneNodeId, intent }) : void 0;
+    const jsonBlock = {
+      v: 1,
+      ruleId,
+      nodeId: sceneNodeId,
+      ...ackIntent ? { intent: ackIntent } : {},
+      sceneWriteOutcome,
+      ...codegenDirective ? { codegenDirective } : {}
+    };
+    const userAnswerLine = intent !== void 0 ? `**User answered:** ${formatIntentValueForDisplay(intent.value)} for **${intent.field}** (scope: ${intent.scope}).` : null;
+    const outcomeLine = buildOutcomeHumanLine({
+      reason,
+      ...errorMessage !== void 0 ? { errorMessage } : {},
+      skippedDefinitionDueToAdr012: false
+    });
+    const prose = [userAnswerLine, outcomeLine].filter((p) => p !== null).join("\n\n");
+    return appendJsonFenceAndFooter(prose, jsonBlock, ruleId);
+  }
+  function buildDefinitionTierFailureBody(args) {
+    const { ruleId, sceneNodeId, intent, kind, errorMessage } = args;
+    const sceneWriteOutcome = sceneOutcomeToAck(
+      kind === "read-only-library" ? "api-rejected" : "api-rejected",
+      kind === "read-only-library" ? "definition-read-only" : "definition-write-failed"
+    );
+    const codegenDirective = intent !== void 0 ? buildCodegenDirective({ sceneNodeId, intent }) : void 0;
+    const jsonBlock = {
+      v: 1,
+      ruleId,
+      nodeId: sceneNodeId,
+      ...intent ? {
+        intent: {
+          field: intent.field,
+          value: intent.value,
+          scope: intent.scope
+        }
+      } : {},
+      sceneWriteOutcome,
+      ...codegenDirective ? { codegenDirective } : {}
+    };
+    const human = kind === "read-only-library" ? "source component lives in an external library and is read-only from this file \u2014 apply the fix in the library file itself." : `could not apply at source definition: ${errorMessage}`;
+    const userAnswerLine = intent !== void 0 ? `**User answered:** ${formatIntentValueForDisplay(intent.value)} for **${intent.field}** (scope: ${intent.scope}).` : null;
+    const outcomeLine = `**Scene write outcome:** ${human}`;
+    const prose = [userAnswerLine, outcomeLine].filter((p) => p !== null).join("\n\n");
+    return appendJsonFenceAndFooter(prose, jsonBlock, ruleId);
+  }
+  function appendJsonFenceAndFooter(prose, jsonBlock, ruleId) {
+    const footer = `\u2014 *${ruleId}*`;
+    const hasIntent = jsonBlock.intent !== void 0;
+    if (!hasIntent) {
+      return `${prose}
+
+${footer}`;
+    }
+    const jsonText = JSON.stringify(jsonBlock, null, 0);
+    return `${prose}
+
+${CANICODE_JSON_FENCE}
+${jsonText}
+\`\`\`
+
+${footer}`;
+  }
+  var FENCED_JSON_RE = new RegExp(
+    `${CANICODE_JSON_FENCE.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*([\\s\\S]*?)\\s*\`\`\``,
+    "m"
+  );
+  function parseCanicodeJsonPayloadFromMarkdown(text) {
+    const m = FENCED_JSON_RE.exec(text);
+    if (!m?.[1]) return void 0;
+    try {
+      const raw = JSON.parse(m[1].trim());
+      if (!raw || typeof raw !== "object") return void 0;
+      const o = raw;
+      if (o.v !== 1 || typeof o.ruleId !== "string") return void 0;
+      return raw;
+    } catch {
+      return void 0;
+    }
+  }
+
   // src/core/roundtrip/apply-with-instance-fallback.ts
   var DEFINITION_WRITE_SKIPPED_EVENT = "cic_roundtrip_definition_write_skipped";
+  function categoryIdForAnnotate(categories, kind, roundtripIntent) {
+    if (kind === "adr012-definition-skipped") {
+      return categories.fallback;
+    }
+    if (roundtripIntent !== void 0) {
+      return categories.gotcha;
+    }
+    return categories.flag;
+  }
   function resolveSourceComponentName(definition, question) {
     if (definition && typeof definition.name === "string" && definition.name) {
       return definition.name;
@@ -93,11 +274,24 @@ ${footer}`;
   async function routeToDefinitionOrAnnotate(definition, writeFn, ctx) {
     if (definition && !ctx.allowDefinitionWrite && ctx.reason !== "non-override-error") {
       const componentName = resolveSourceComponentName(definition, ctx.question);
+      const replicaCount = typeof ctx.question.replicas === "number" && Number.isInteger(ctx.question.replicas) ? ctx.question.replicas : void 0;
       if (ctx.categories) {
         upsertCanicodeAnnotation(ctx.scene, {
           ruleId: ctx.question.ruleId,
-          markdown: `The fix below could not be applied on this instance child \u2014 the property silently ignored the write or the override was rejected. Apply it on the source component **${componentName}** so every instance picks it up. Re-run with \`allowDefinitionWrite: true\` to let canicode propagate automatically.`,
-          categoryId: ctx.categories.fallback
+          markdown: buildDefinitionWriteSkippedBody({
+            ruleId: ctx.question.ruleId,
+            sceneNodeId: ctx.scene.id,
+            componentName,
+            reason: ctx.reason,
+            ...ctx.errorMessage !== void 0 ? { errorMessage: ctx.errorMessage } : {},
+            ...replicaCount !== void 0 ? { replicaCount } : {},
+            ...ctx.roundtripIntent !== void 0 ? { intent: ctx.roundtripIntent } : {}
+          }),
+          categoryId: categoryIdForAnnotate(
+            ctx.categories,
+            "adr012-definition-skipped",
+            ctx.roundtripIntent
+          )
         });
       }
       ctx.telemetry?.(DEFINITION_WRITE_SKIPPED_EVENT, {
@@ -111,11 +305,21 @@ ${footer}`;
     }
     if (!definition) {
       if (ctx.categories) {
-        const markdown = ctx.reason === "silent-ignore" ? "write accepted but value unchanged; no definition available" : ctx.reason === "override-error" ? `could not apply automatically: ${ctx.errorMessage ?? ""}` : `could not apply automatically: ${ctx.errorMessage ?? ""}`;
+        const markdown = buildNoDefinitionFallbackBody({
+          ruleId: ctx.question.ruleId,
+          sceneNodeId: ctx.scene.id,
+          reason: ctx.reason,
+          ...ctx.errorMessage !== void 0 ? { errorMessage: ctx.errorMessage } : {},
+          ...ctx.roundtripIntent !== void 0 ? { intent: ctx.roundtripIntent } : {}
+        });
         upsertCanicodeAnnotation(ctx.scene, {
           ruleId: ctx.question.ruleId,
           markdown,
-          categoryId: ctx.categories.fallback
+          categoryId: categoryIdForAnnotate(
+            ctx.categories,
+            "other-failure",
+            ctx.roundtripIntent
+          )
         });
       }
       return ctx.reason === "silent-ignore" ? { icon: "\u{1F4DD}", label: "silent-ignore, annotated" } : { icon: "\u{1F4DD}", label: `error: ${ctx.errorMessage ?? ""}` };
@@ -132,8 +336,18 @@ ${footer}`;
       if (ctx.categories) {
         upsertCanicodeAnnotation(ctx.scene, {
           ruleId: ctx.question.ruleId,
-          markdown: isRemoteReadOnly ? "source component lives in an external library and is read-only from this file \u2014 apply the fix in the library file itself." : `could not apply at source definition: ${defMsg}`,
-          categoryId: ctx.categories.fallback
+          markdown: buildDefinitionTierFailureBody({
+            ruleId: ctx.question.ruleId,
+            sceneNodeId: ctx.scene.id,
+            ...ctx.roundtripIntent !== void 0 ? { intent: ctx.roundtripIntent } : {},
+            kind: isRemoteReadOnly ? "read-only-library" : "definition-error",
+            errorMessage: defMsg
+          }),
+          categoryId: categoryIdForAnnotate(
+            ctx.categories,
+            "other-failure",
+            ctx.roundtripIntent
+          )
         });
       }
       return {
@@ -143,7 +357,7 @@ ${footer}`;
     }
   }
   async function applyWithInstanceFallback(question, writeFn, context = {}) {
-    const { categories, allowDefinitionWrite = false, telemetry } = context;
+    const { categories, allowDefinitionWrite = false, telemetry, roundtripIntent } = context;
     const scene = await figma.getNodeByIdAsync(question.nodeId);
     if (!scene) return { icon: "\u{1F4DD}", label: "missing node" };
     const definition = question.sourceChildId ? await figma.getNodeByIdAsync(question.sourceChildId) : null;
@@ -156,7 +370,8 @@ ${footer}`;
           categories,
           reason: "silent-ignore",
           allowDefinitionWrite,
-          telemetry
+          telemetry,
+          ...roundtripIntent !== void 0 ? { roundtripIntent } : {}
         });
       }
       return { icon: "\u2705", label: "instance/scene" };
@@ -171,7 +386,8 @@ ${footer}`;
           reason: "non-override-error",
           errorMessage: msg,
           allowDefinitionWrite,
-          telemetry
+          telemetry,
+          ...roundtripIntent !== void 0 ? { roundtripIntent } : {}
         });
       }
       return routeToDefinitionOrAnnotate(definition, writeFn, {
@@ -181,7 +397,8 @@ ${footer}`;
         reason: "override-error",
         errorMessage: msg,
         allowDefinitionWrite,
-        telemetry
+        telemetry,
+        ...roundtripIntent !== void 0 ? { roundtripIntent } : {}
       });
     }
   }
@@ -220,6 +437,39 @@ ${footer}`;
     target.setBoundVariable(prop, variable);
     return true;
   }
+  function buildRoundtripIntentFromPropertyAnswer(question, answerValue) {
+    const raw = question.targetProperty;
+    if (raw === void 0) return void 0;
+    const props = Array.isArray(raw) ? raw : [raw];
+    if (props.length === 0) return void 0;
+    if (props.length === 1) {
+      const prop = props[0];
+      const perProp = answerValue && typeof answerValue === "object" && !("variable" in answerValue) && !Array.isArray(answerValue) ? answerValue[prop] : answerValue;
+      const parsed = parseValueForIntent(perProp);
+      if (parsed === void 0) return void 0;
+      return { field: prop, value: parsed, scope: "instance" };
+    }
+    const obj = answerValue && typeof answerValue === "object" && !("variable" in answerValue) && !Array.isArray(answerValue) ? answerValue : void 0;
+    const picked = {};
+    for (const p of props) {
+      if (obj && p in obj && obj[p] !== void 0) picked[p] = obj[p];
+    }
+    if (Object.keys(picked).length === 0) return void 0;
+    return {
+      field: props.join(", "),
+      value: picked,
+      scope: "instance"
+    };
+  }
+  function parseValueForIntent(raw) {
+    if (raw && typeof raw === "object" && "variable" in raw) {
+      return { variable: raw.variable };
+    }
+    if (raw && typeof raw === "object" && "fallback" in raw) {
+      return raw.fallback;
+    }
+    return raw;
+  }
   function applyPropertyScalar(target, prop, scalar) {
     const rec = target;
     const before = rec[prop];
@@ -228,6 +478,10 @@ ${footer}`;
     return true;
   }
   async function applyPropertyMod(question, answerValue, context = {}) {
+    const roundtripIntent = buildRoundtripIntentFromPropertyAnswer(
+      question,
+      answerValue
+    );
     const props = Array.isArray(question.targetProperty) ? question.targetProperty : question.targetProperty !== void 0 ? [question.targetProperty] : [];
     return applyWithInstanceFallback(
       question,
@@ -258,7 +512,10 @@ ${footer}`;
         }
         return changed;
       },
-      context
+      {
+        ...context,
+        ...roundtripIntent !== void 0 ? { roundtripIntent } : {}
+      }
     );
   }
 
@@ -334,7 +591,15 @@ ${footer}`;
       }
       const ruleId = extractRuleId(text);
       if (!ruleId) continue;
-      out.push({ nodeId: node.id, ruleId });
+      const payload = parseCanicodeJsonPayloadFromMarkdown(text);
+      const payloadAligned = payload && payload.ruleId === ruleId;
+      out.push({
+        nodeId: node.id,
+        ruleId,
+        ...payloadAligned && payload.intent ? { intent: payload.intent } : {},
+        ...payloadAligned && payload.sceneWriteOutcome ? { sceneWriteOutcome: payload.sceneWriteOutcome } : {},
+        ...payloadAligned && payload.codegenDirective ? { codegenDirective: payload.codegenDirective } : {}
+      });
     }
     return out;
   }
@@ -360,17 +625,22 @@ ${footer}`;
     walk(root, canicodeCategoryIds, out);
     return out;
   }
+  function safeChildren(node) {
+    try {
+      const c = node.children;
+      return Array.isArray(c) ? c : [];
+    } catch {
+      return [];
+    }
+  }
   function walk(node, canicodeCategoryIds, out) {
     try {
       const local = extractAcknowledgmentsFromNode(node, canicodeCategoryIds);
       for (const a of local) out.push(a);
     } catch {
     }
-    const children = node.children;
-    if (Array.isArray(children)) {
-      for (const child of children) {
-        if (child && typeof child === "object") walk(child, canicodeCategoryIds, out);
-      }
+    for (const child of safeChildren(node)) {
+      if (child && typeof child === "object") walk(child, canicodeCategoryIds, out);
     }
   }
 

package/skills/cursor/canicode/SKILL.md

@@ -13,6 +13,12 @@ This skill works with either channel — the CLI or the canicode MCP server. Bot
 - A **saved fixture** (from `canicode calibrate-save-fixture`)
 - A **FIGMA_TOKEN** for live Figma URLs
 
+### Step 0: Verify canicode MCP tools are loaded (optional fast path)
+
+Before shelling out to `npx canicode analyze …`, check whether the **`analyze` MCP tool** is available in **this** session — not only whether `.mcp.json` lists `canicode`. New MCP registrations usually need a **restart or MCP reload** before tools appear.
+
+If you must use the CLI fallback, say so out loud: the user may have added `claude mcp add canicode …` but not restarted yet (#433). After restart/reload, `analyze` via MCP avoids the `npx` spawn. The fallback is valid — silence makes users think the MCP install failed.
+
 ## How to Analyze
 
 ### From a Figma URL

package/skills/cursor/canicode-gotchas/SKILL.md

@@ -5,6 +5,8 @@ description: Gotcha survey (Claude Code or Cursor) — Q&A workflow; answers acc
 
 # CanICode Gotchas — Design Gotcha Survey
 
+**Channel contrast:** **`canicode-gotchas`** (**this skill**) persists answers **only** in **local** `.claude/skills/canicode-gotchas/SKILL.md` — **memo-only**, no Plugin write to Figma. **`canicode-roundtrip`** writes to the **canvas**. Use gotchas when you want Q&A captured for code-gen context without mutating the file.
+
 Run a gotcha survey on a Figma design to collect implementation context that Figma cannot encode natively, capture developer/designer answers, and upsert them into **`.claude/skills/canicode-gotchas/SKILL.md`** so downstream `figma-implement-design` runs have annotation-ready context. In this model, rules do rule-based best-practice detection, and gotcha is the annotation output from that detection. Some gotchas come from violation rules (what is wrong and how to resolve it); others come from info-collection rules (neutral context Figma cannot represent, like interaction intent/state).
 
 **Install location:** The workflow prose may live under `.claude/skills/canicode-gotchas/SKILL.md` (default `canicode init`) or be copied to `.cursor/skills/canicode-gotchas/SKILL.md` (`canicode init --cursor-skills`). The **authoritative gotcha store** is always **`.claude/skills/canicode-gotchas/SKILL.md`** — the CLI `upsert-gotcha-section` writes there only. In the `.claude` copy, this file has two regions: the **Workflow** below (installed by `canicode init`, never overwritten manually) and the **Collected Gotchas** region at the bottom (one numbered section per design, replaced in place on re-runs).
@@ -18,6 +20,12 @@ Run a gotcha survey on a Figma design to collect implementation context that Fig
 
 ## Workflow
 
+### Step 0: Verify canicode MCP tools are loaded (optional fast path)
+
+Before Step 1, verify that `gotcha-survey` is callable in **this** session — not merely listed in `.mcp.json`. Newly registered MCP servers usually need a **host restart or MCP reload** before tools appear (same pattern as `/canicode-roundtrip` Step 0 for the Figma MCP).
+
+When you fall back to `npx canicode gotcha-survey … --json`, tell the user explicitly: the canicode MCP may not be loaded yet. They should register it (`claude mcp add canicode -- npx --yes --package=canicode canicode-mcp`, or the Cursor/`mcp.json` equivalent in the Customization guide) and **restart the IDE or reload MCP** — then the next session can use the MCP tool without spawning `npx`. The CLI fallback is correct behavior; silence makes users think registration failed (#433).
+
 ### Step 1: Run the gotcha survey
 
 If the `gotcha-survey` MCP tool is available, call it with the user's Figma URL:
@@ -115,77 +123,48 @@ The `core/contracts/design-key.ts` helper (`computeDesignKey`) handles every sha
 
 File-state detection (4-way: missing / valid / missing-heading / clobbered) and section walking (find existing `## #NNN — ...` by `Design key` substring, otherwise compute the next monotonic zero-padded NNN) are deterministic markdown operations and live in `core/gotcha/upsert-gotcha-section.ts` with vitest coverage — do not re-implement them in prose (per ADR-016).
 
-Render the per-design section markdown using the **Output Template** below with the literal string `{{SECTION_NUMBER}}` in the header (the CLI substitutes the right NNN for you — preserves it on replace, computes the next monotonic value on append). Then invoke:
+Build **one JSON object** on stdin for `upsert-gotcha-section`. The CLI renders the section markdown from `survey` + `answers` via `renderGotchaSection` in TypeScript (#439) — severity, rule text, node ids, and instance context come **verbatim** from `gotcha-survey --json`; the skill must not paste LLM-authored section prose.
+
+Payload shape:
+
+```json
+{
+  "survey": {
+    "designKey": "<same as Step 4a>",
+    "designGrade": "<from gotcha-survey>",
+    "questions": "<full questions[] array from gotcha-survey — preserve order>"
+  },
+  "answers": {
+    "<nodeId>": { "answer": "…" }
+  },
+  "designName": "<Figma file name or fixture label>",
+  "figmaUrl": "<the user's input URL or path>",
+  "analyzedAt": "<ISO 8601 timestamp when you upsert>",
+  "today": "<YYYY-MM-DD local date for the section title>"
+}
+```
+
+For skipped / n/a: use `{ "skipped": true }` for that `nodeId`, or omit the key. Skipped questions do **not** get per-question rows; `renderGotchaSection` appends a compact **`#### Skipped (N)`** block listing each `ruleId` with a count (`ruleId` lines sorted lexically — see `src/core/gotcha/render-gotcha-section.ts`).
+
+Invoke (cac requires `--input=-`, not `--input -`, so the stdin sentinel survives parsing — #420):
 
 ```bash
 npx canicode upsert-gotcha-section \
   --file .claude/skills/canicode-gotchas/SKILL.md \
   --design-key "<designKey from Step 4a>" \
-  --section -   # then pipe the rendered section markdown through stdin
+  --input=-
 ```
 
-The CLI prints a JSON result `{ state, action, sectionNumber, wrote, userMessage }`:
+Pipe the JSON object on stdin. `--design-key` must equal `survey.designKey` (the CLI validates the match).
+
+The CLI prints JSON `{ state, action, sectionNumber, wrote, userMessage, designKey }`:
 
 - `wrote: true` → success. `action` is `"replace"` (preserved `sectionNumber`) or `"append"` (next monotonic `sectionNumber`).
 - `wrote: false` with `state: "missing"` → tell the user: *"Your gotchas SKILL.md is not installed yet. Run `canicode init` first, then re-invoke this skill."* Stop here.
 - `wrote: false` with `state: "clobbered"` → tell the user: *"Your gotchas SKILL.md is missing the canicode YAML frontmatter (pre-#340 single-design clobber). Run `canicode init --force` to restore the workflow, then re-run this survey — your answers will land in a clean numbered section."* Stop here.
 - `wrote: true` with `state: "missing-heading"` → silent recovery. The CLI injected the `# Collected Gotchas` heading and appended the section; the workflow region above is untouched.
 
-The Workflow region above must never be touched. Do NOT copy Workflow prose into the per-design section; the section only carries metadata + gotcha answers.
-
-## Output Template
-
-Each per-design section in the `# Collected Gotchas` region has this exact shape:
-
-````markdown
-## #NNN — {designName} — {YYYY-MM-DD}
-
-- **Figma URL**: {figmaUrl}
-- **Design key**: {designKey}
-- **Grade**: {designGrade}
-- **Analyzed at**: {analyzedAt}
-
-### Gotchas
-
-#### {ruleId} — {nodeName}
-
-- **Severity**: {severity}
-- **Node ID**: {nodeId}
-- **Instance context** (omit this bullet if `instanceContext` was not in the survey question): parent instance `parentInstanceNodeId`, source node `sourceNodeId`, component `sourceComponentName` / `sourceComponentId` when present — roundtrip apply uses this to write on the source definition when instance overrides fail.
-- **Question**: {question}
-- **Answer**: {userAnswer}
-
-(repeat for each question)
-````
-
-### Field mapping
-
-| Field | Source |
-|-------|--------|
-| `NNN` | `sectionNumber` — zero-padded three-digit index. Preserved on re-run, incremented on append. |
-| `designName` | Figma file name or fixture name from the input |
-| `YYYY-MM-DD` | Today's date (the day you are running the survey) |
-| `figmaUrl` | The input URL or fixture path provided by the user |
-| `designKey` | `survey.designKey` from the gotcha-survey response (see Step 4a) |
-| `designGrade` | `designGrade` from gotcha-survey response |
-| `analyzedAt` | Current timestamp (ISO 8601) |
-| `ruleId` | `ruleId` from each question |
-| `nodeName` | `nodeName` from each question |
-| `severity` | `severity` from each question (blocking / risk / missing-info — the last surfaces only for info-collection rules per #406) |
-| `nodeId` | `nodeId` from each question |
-| `instanceContext` | When present on the question, copy `parentInstanceNodeId`, `sourceNodeId`, `sourceComponentId`, `sourceComponentName` into the bullet above (roundtrip / Plugin apply) |
-| `question` | `question` from each question |
-| `userAnswer` | The answer collected from the user in Step 3 |
-
-### Skipped questions
-
-If the user skipped a question or said "n/a", still include it in the section with:
-
-```markdown
-- **Answer**: _(skipped)_
-```
-
-This ensures the code generation agent knows the gotcha exists even if no answer was provided.
+The Workflow region above must never be touched.
 
 ## Edge Cases
 
@@ -195,5 +174,5 @@ This ensures the code generation agent knows the gotcha exists even if no answer
 - **Workflow region**: Never modified. If you notice the Workflow region has been edited by the user, leave their edits alone — only the `# Collected Gotchas` region is under skill control.
 - **Pre-#340 clobbered file** (the YAML frontmatter was rewritten to a per-design variant, so the canonical `canicode-gotchas` frontmatter is missing): tell the user to run `canicode init --force` to restore the workflow, then re-run the survey. The prior single-design content cannot be automatically migrated into a `## #001` section — the user re-runs and gets a clean section.
 - **MCP tool not available**: Fall back to `npx canicode gotcha-survey <input> --json` — the CLI returns the same `GotchaSurvey` shape. If the CLI is also unavailable (e.g. no node runtime), tell the user to install the canicode MCP server or the `canicode` npm package (see Prerequisites).
-- **Partial answers**: If the user stops mid-survey, upsert the section with answers collected so far. Mark remaining questions as _(skipped)_.
+- **Partial answers**: If the user stops mid-survey, upsert the section with answers collected so far. Remaining questions count toward **`#### Skipped (N)`** (omit keys or `{ "skipped": true }`).
 - **Manual section deletion**: If the user deletes a middle section by hand, do not renumber existing sections. The next new section still gets `(highest existing number) + 1`; numeric gaps are acceptable (same pattern as `.claude/docs/ADR.md`).