@sun-asterisk/sungen 2.6.15 → 2.7.0-beta.1

package/dist/orchestrator/templates/ai-instructions/claude-skill-selector-keys.md

@@ -166,37 +166,47 @@ Resolver searches in this order:
 
 If no YAML key exists, the resolver infers from the Gherkin element type:
 
-| Gherkin | Inferred locator |
-|---|---|
-| `[X] button` | `getByRole('button', { name: 'X' })` |
-| `[X] link` | `getByRole('link', { name: 'X' })` |
-| `[X] heading` / `header` | `getByRole('heading', { name: 'X' })` |
-| `[X] checkbox` | `getByRole('checkbox', { name: 'X' })` |
-| `[X] radio` | `getByRole('radio', { name: 'X' })` |
-| `[X] field` | `getByPlaceholder('X')` |
-| `[X] text` / `message` / `label` | `getByText('X')` |
-| `[X] logo/image/icon` | `getByRole('img', { name: 'X' })` |
-| `[X] search` | `getByRole('searchbox', { name: 'X' })` |
-| `[X] option` | `getByRole('option', { name: 'X' })` |
-| `[X] slider` | `getByRole('slider', { name: 'X' })` |
-| `[X] toggle` | `getByRole('switch', { name: 'X' })` |
-| `[X] tab` | `getByRole('tab', { name: 'X' })` |
-| `[X] table` | `getByRole('table', { name: 'X' })` |
-| `[X] list` | `getByRole('list', { name: 'X' })` |
-| `[X] column` | `getByRole('columnheader', { name: 'X' })` |
-| `[X] dialog` / `modal` / `drawer` | `getByRole('dialog', { name: 'X' })` |
-| `[X] dropdown` / `select` | `getByRole('combobox', { name: 'X' })` |
-| `[X] menuitem` | `getByRole('menuitem', { name: 'X' })` |
-| `[X] progressbar` | `getByRole('progressbar', { name: 'X' })` |
-| `[X] section` | `getByRole('region', { name: 'X' })` |
-| `[X] card` | `getByRole('article', { name: 'X' })` |
-| `[X] item` | `getByRole('listitem', { name: 'X' })` |
-| `[X] cell` | `getByRole('cell', { name: 'X' })` |
-| `[X] spinner` | `getByRole('status', { name: 'X' })` |
-| `[X] breadcrumb` | `getByRole('navigation', { name: 'X' })` |
-| `[X] badge` / `tooltip` / `tag` | `getByText('X')` |
-
-**Only add a YAML entry when** the auto-inferred locator won't work (wrong name, need testid, need nth, etc.).
+> ⚠️ **Auto-infer pitfall — the #1 cause of selector failures in production.**
+>
+> `[X] button` auto-infers as `getByRole('button', { name: 'X' })`. This **only works** when the button's accessible name in the DOM is **exactly `X`** — same language, same text, same casing.
+>
+> The Gherkin `[Reference]` is your human label for the element, **not** the DOM name. If the app is in Vietnamese (or any language where the Gherkin label differs from DOM text), auto-infer will produce `No element found` at runtime. **Write an explicit YAML entry** with the real DOM name instead.
+>
+> **Decision rule**: auto-infer is safe ONLY when you have confirmed in the snapshot that the DOM element's accessible name / placeholder text is literally `X`. When in doubt → write YAML.
+
+| Gherkin | Inferred locator | Safe when… |
+|---|---|---|
+| `[X] button` | `getByRole('button', { name: 'X' })` | Button's accessible name = X |
+| `[X] link` | `getByRole('link', { name: 'X' })` | Link text = X |
+| `[X] heading` / `header` | `getByRole('heading', { name: 'X' })` | Heading text = X |
+| `[X] checkbox` | `getByRole('checkbox', { name: 'X' })` | Checkbox label = X |
+| `[X] radio` | `getByRole('radio', { name: 'X' })` | Radio label = X |
+| `[X] field` | `getByPlaceholder('X')` | Placeholder text = X AND field has a placeholder |
+| `[X] text` / `message` / `label` | `getByText('X')` | Visible text = X (partial match) |
+| `[X] logo/image/icon` | `getByRole('img', { name: 'X' })` | Image alt = X |
+| `[X] search` | `getByRole('searchbox', { name: 'X' })` | Searchbox label = X |
+| `[X] option` | `getByRole('option', { name: 'X' })` | Option text = X |
+| `[X] slider` | `getByRole('slider', { name: 'X' })` | Slider label = X |
+| `[X] toggle` | `getByRole('switch', { name: 'X' })` | Toggle label = X |
+| `[X] tab` | `getByRole('tab', { name: 'X' })` | Tab text = X |
+| `[X] table` | `getByRole('table', { name: 'X' })` | Table aria-label = X |
+| `[X] list` | `getByRole('list', { name: 'X' })` | List aria-label = X |
+| `[X] column` | `getByRole('columnheader', { name: 'X' })` | Column header text = X |
+| `[X] dialog` / `modal` / `drawer` | `getByRole('dialog', { name: 'X' })` | Dialog aria-label/heading = X |
+| `[X] dropdown` / `select` | `getByRole('combobox', { name: 'X' })` | Combobox label = X |
+| `[X] menuitem` | `getByRole('menuitem', { name: 'X' })` | Menu item text = X |
+| `[X] progressbar` | `getByRole('progressbar', { name: 'X' })` | Progressbar label = X |
+| `[X] section` | `getByRole('region', { name: 'X' })` | Section aria-label = X |
+| `[X] card` | `getByRole('article', { name: 'X' })` | Card aria-label = X |
+| `[X] item` | `getByRole('listitem', { name: 'X' })` | List item text = X |
+| `[X] cell` | `getByRole('cell', { name: 'X' })` | Cell text = X |
+| `[X] spinner` | `getByRole('status', { name: 'X' })` | Spinner aria-label = X |
+| `[X] breadcrumb` | `getByRole('navigation', { name: 'X' })` | Navigation aria-label = X |
+| `[X] badge` / `tooltip` / `tag` | `getByText('X')` | Visible text = X |
+
+**Special note on `[X] field`**: `getByPlaceholder('X')` only works when (1) the field has a placeholder attribute AND (2) the placeholder text equals X. For fields without placeholders (floating labels, aria-label), write explicit YAML: `type: label, value: "Actual label text"`.
+
+**Only add a YAML entry when** auto-infer cannot work: DOM name differs from Gherkin label, need `testid`, need `nth`, need `exact: true`, or the field type requires explicit config.
 
 ### Types requiring YAML entry (no auto-infer)