canicode 0.11.0 → 0.11.2

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:
@@ -44,13 +52,40 @@ If `isReadyForCodeGen` is `true` or `questions` is empty:
 - Do NOT write to `.claude/skills/canicode-gotchas/SKILL.md`.
 - Stop here.
 
+### Step 3 — preamble: match the user's language
+
+Before rendering any question, detect the user's conversation language from their recent messages in **this** session. Korean vs. English vs. other is usually unambiguous; when ambiguous, default to English and ask the user once which language they prefer.
+
+When the user's language is non-English, localize only the **human-readable** strings rendered in the prompt templates below: the `question` text, the `why` line (if shown), the `Hint:` body, the `Example:` body, and the batch shared-prompt wording — including the "Reply with one answer to apply to all …, or **split** to answer each individually" sentence and the `skip` / `n/a` affordance sentence that follows it. Translate at render time only; the rule templates in `core/rules/*` stay English-only per CLAUDE.md and the issue's "Out of scope" list — do not rewrite source.
+
+Keep the following English even when localizing, because they are identifiers or structural markers that downstream tools grep for: `ruleId`, `nodeId`, `nodeName`, the severity label in brackets (`[blocking]`, `[risk]`, `[missing-info]`, `[suggestion]`), and the entire markdown scaffolding of the Step 4 upsert section (`## #NNN — …` headings, `Design key`, `#### Skipped (N)`, the per-record field labels). `renderGotchaSection` is the source of truth for that on-disk markdown (ADR-016) and its output stays English.
+
+In Step 4, pass the user's answer through **verbatim** into the `answers[<nodeId>].answer` field — do **not** back-translate answers to English. `figma-implement-design` is cross-language by design (see #461), and a round-trip to English introduces translation loss and defeats the "shared language for designer/PM" framing.
+
 ### Step 3: Present questions to the user
 
-The survey response carries a pre-computed `groupedQuestions.groups[].batches[]` shape so this skill never has to sort, partition, or maintain a batchable-rule whitelist in prose. The sort key, `_no-source` sentinel, and batchable-rule list all live in `core/gotcha/group-and-batch-questions.ts` with vitest coverage (per ADR-016). Iterate over it:
+The survey response carries a pre-computed `groupedQuestions.groups[].batches[]` shape so this skill never has to sort, partition, or maintain a batchable-rule whitelist in prose. The sort key, `_no-source` sentinel, and both batchable-rule lists (`BATCHABLE_RULE_IDS` for `safe` mode, `OPT_IN_BATCHABLE_RULE_IDS` for `opt-in` mode) all live in `core/gotcha/group-and-batch-questions.ts` with vitest coverage (per ADR-016). Iterate over it:
+
+**Before presenting the first batch**, display this shortcut notice once so the user knows they can exit early at any point:
+
+```
+Survey: {totalBatchCount} question(s) to answer.
+Tip: reply `skip remaining` at any point to bypass the rest with a default no-op annotation and finish immediately.
+```
+
+Where `totalBatchCount` is `groupedQuestions.groups.flatMap((g) => g.batches).length`.
+
+**After every 3rd batch** (i.e. after batches 3, 6, 9, …), re-surface the shortcut as a brief reminder before presenting the next batch:
 
-For every `batch` in `groupedQuestions.groups.flatMap((g) => g.batches)`:
+```
+(You can still reply `skip remaining` to bypass the remaining questions.)
+```
 
-- **Single-question batch (`batch.questions.length === 1`)** — render the standard prompt for `batch.questions[0]`:
+When the user replies `skip remaining` at any point during Step 3, immediately treat all unanswered batches as skipped (`{ "skipped": true }` for each unanswered `nodeId`) and proceed directly to Step 4 without asking further questions.
+
+For every `batch` in `groupedQuestions.groups.flatMap((g) => g.batches)`, branch on `batch.batchMode`:
+
+- **`batch.batchMode === "none"`** — single-question batch; the helper guarantees `batch.questions.length === 1`. Render the standard prompt for `batch.questions[0]`:
 
   ```
   **[{severity}] {ruleId}** — node: {nodeName}
@@ -61,7 +96,7 @@ For every `batch` in `groupedQuestions.groups.flatMap((g) => g.batches)`:
   > Example: {example}
   ```
 
-- **Batch of N ≥ 2 with `batch.batchable === true`** (#369) — render one shared prompt covering every member:
+- **`batch.batchMode === "safe"` with `batch.questions.length >= 2`** (#369) — rule in `BATCHABLE_RULE_IDS`; one answer is uniformly applicable. Render one shared prompt:
 
   ```
   **[{severity}] {ruleId}** — {batch.questions.length} instances:
@@ -79,13 +114,32 @@ For every `batch` in `groupedQuestions.groups.flatMap((g) => g.batches)`:
 
   Where `sharedQuestionPrompt` reuses the rule's `question` text with the per-node noun replaced by the rule's plural noun (e.g. "These layers all use FILL sizing without min/max constraints. What size boundaries should they share?" instead of repeating the singular phrasing N times).
 
-- **Any batch with `batch.batchable === false`** is always rendered as a single-question prompt — the helper guarantees `questions.length === 1` for those (identity-typed answers like `non-semantic-name`, structural-mod rules).
+- **`batch.batchMode === "opt-in"` with `batch.questions.length >= 2`** (#426) — rule in `OPT_IN_BATCHABLE_RULE_IDS` (currently `missing-prototype`). The same answer is usually shareable across siblings but may legitimately differ per node — signal that explicitly so the user can opt out of the shared answer with `split`:
+
+  ```
+  **[{severity}] {batch.ruleId}** — {batch.questions.length} instances of the same rule:
+    - {nodeName₁}
+    - {nodeName₂}
+    - …
+
+  {sharedQuestionPrompt}
+
+  Apply this answer to all {batch.questions.length} occurrences of `{batch.ruleId}`, or reply **split** to answer each individually.
+
+  > Hint: {hint}
+  > Example: {example}
+  ```
+
+  Unlike `safe` batches, the prompt frames the answer as a suggested default, not a uniform truth — reuse the rule's existing `example` (e.g. `missing-prototype`'s "navigates to `/product/{id}` detail page") so the user knows the answer can be a pattern, not a literal string shared character-for-character.
+
+- **Single-member `safe` or `opt-in` batch (`batch.questions.length === 1`)** — render the single-question template above; the shared-prompt framing collapses to the rule's own wording when there is only one node.
 
 Wait for the user's answer before moving to the next batch. The user may:
-- Answer the question / batch directly
-- Say **split** (batch only) to fall back to per-question prompting for that batch
+- Answer the question / batch directly (single value or pattern covers all batch members)
+- Say **split** (batch only) to fall back to per-question prompting for that batch — works the same for both `safe` and `opt-in` batches
 - Say **skip** to skip the question / the entire batch
 - Say **n/a** if the question / the entire batch is not applicable
+- Say **skip remaining** to immediately skip all remaining unanswered batches and proceed to Step 4
 
 When applying the batched answer, expand back to per-question records in Step 4 — the gotcha section format stores one record per `nodeId`.
 
@@ -115,77 +169,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 +220,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`).