@sun-asterisk/sungen 2.4.0 → 2.4.1

package/src/orchestrator/templates/ai-instructions/claude-cmd-run-test.md

@@ -1,29 +1,32 @@
 ---
 name: run-test
-description: 'Generate selectors, compile, and run Playwright tests — auto-fixes selectors on failure'
+description: 'Compile and run Playwright tests — auto-fixes selectors on failure'
 argument-hint: [screen-name]
 allowed-tools: Read, Grep, Bash, Glob, Edit, AskUserQuestion
 ---
 
 ## Role
 
-You are a **Senior Developer** specialized in Playwright test debugging. You generate selectors from live pages, diagnose test failures, and fix selectors/test-data using the `sungen-selector-fix`, `sungen-selector-keys`, and `sungen-error-mapping` skills.
+You are a **Senior Developer**. Use `sungen-selector-fix`, `sungen-selector-keys`, and `sungen-error-mapping` skills.
 
 ## Parameters
 
 Parse **screen** from `$ARGUMENTS`. If missing, ask the user.
 
-## Steps
-
-1. Verify `qa/screens/<screen>/` has `.feature` + `test-data.yaml`. If not → `/sungen:create-test` first.
-2. **Generate selectors** — explore live page via MCP, build `selectors.yaml` using `sungen-selector-fix` and `sungen-selector-keys` skills.
-3. **Proactive validation** — verify EVERY selector against the live page using `browser_snapshot` + `browser_evaluate` BEFORE running any test. Fix mismatches immediately. See `sungen-selector-fix` skill "Proactive Selector Validation" section. Target: 80%+ issues fixed before first run.
-4. **Compile**: `sungen generate --screen <screen>`
-5. **Batched test run** — run tests in batches of 20 via `--grep`:
-   `npx playwright test specs/generated/<screen>/*.spec.ts --grep "VP-UI-001|...|VP-UI-020" --reporter=line`
-   - If failures in batch → group by root cause, fix, recompile, re-run only failing tests
-   - If batch passes → move to next 20 tests
-   - Max 5 fix attempts per batch
-6. **Final confirmation** — run ALL tests once to catch regressions.
-7. After 5 fix attempts still failing → ask user about direct `.spec.ts` fix.
-8. Show: pass/fail, attempt count, files changed.
+## Phase 1: Compile & Run (no MCP)
+
+1. Verify `qa/screens/<screen>/` has `.feature` + `test-data.yaml`
+2. Ensure `selectors.yaml` has page selector. If missing, ask user for URL path
+3. `sungen generate --screen <screen>`
+4. `npx playwright test specs/generated/<screen>/*.spec.ts --reporter=line`
+5. If all pass → done
+
+## Phase 2: Targeted Fix (only if failures)
+
+6. Parse failures → group by root cause
+7. Navigate to page ONCE via MCP → ONE `browser_snapshot`
+8. Fix broken selectors per `sungen-selector-fix` skill
+9. Recompile → re-run only failing tests
+10. Repeat up to 3 attempts
+11. Final full run for regression check
+12. Still failing → ask user

package/src/orchestrator/templates/ai-instructions/claude-skill-error-mapping.md

@@ -81,12 +81,12 @@ If `toHaveText` fails on an input → the Gherkin step has wrong target type. Fi
 
 | Symptom | Fix |
 |---|---|
-| Redirect to login page | Auth expired. Tell user: `sungen makeauth <role> --url <baseURL>` |
-| `storageState` file not found | Run `sungen makeauth <role> --url <baseURL>` |
-| Most tests timeout on first step | Auth expired — re-run makeauth |
-| Page shows home instead of target | SPA + expired auth. Re-run makeauth + add `wait for` step |
+| Redirect to login page | Auth expired. Ask user to log in manually via MCP browser |
+| `storageState` file not found | Ask user to log in manually via MCP browser, then save storage state |
+| Most tests timeout on first step | Auth expired — ask user to re-authenticate via MCP browser |
+| Page shows home instead of target | SPA + expired auth. Re-authenticate + add `wait for` step |
 
-**Never run `sungen makeauth` yourself.** Tell the user.
+**Never use `sungen makeauth`.** Always let the user log in manually via the MCP browser.
 
 ---
 

package/src/orchestrator/templates/ai-instructions/claude-skill-gherkin-syntax.md

@@ -50,7 +50,7 @@ User check [T] radio                             # select radio
 User uncheck [T] checkbox                        # uncheck
 User uncheck [T] toggle                          # toggle off
 User select [T] dropdown with {{v}}              # select option
-User upload [T] uploader with {{f}}              # file upload
+User fill [T] uploader with {{f}}                # file upload
 ```
 
 ### Interaction
@@ -161,10 +161,17 @@ User see [Table] table with {{count}}                           # row count
 User see [Table] table is empty                                 # empty table
 User see [Col] column with {{v}}                                # cell value (row scoped)
 User click [Act] button in [Table] table with {{v}}             # action in row
+User see [Table] table match data:                              # exact table match (inline DataTable)
+    | Header1    | Header2    |
+    | {{value1}} | {{value2}} |
 ```
 
+**Priority**: Use row scope patterns for single-row verification + actions. Use `table match data` only when verifying multiple rows at once.
+
 Row scope: `see [Ref] row in [Table] table with {{v}}` defines `tableRow`. Subsequent `see [Col] column with {{v}}` checks the cell in that row. With `columns` config → exact `nth(index)`, without → `filter({ hasText })`.
 
+Table match data: `see [Table] table match data:` followed by a Cucumber DataTable. First row = headers, remaining rows = expected data. Uses **filter-based matching** — verifies rows containing expected values exist, resilient to data changes, extra rows, and row reordering. Use `{{variable}}` for cell values.
+
 ### States
 
 `hidden` `visible` `disabled` `enabled` `checked` `unchecked` `focused` `empty` `loading` `selected` `sorted ascending` `sorted descending`

package/src/orchestrator/templates/ai-instructions/claude-skill-selector-fix.md

@@ -1,41 +1,51 @@
 ---
 name: sungen-selector-fix
-description: 'Selector generation and fixing strategy — explore live page, generate selectors.yaml, validate, auto-fix. Auto-loaded by run-test command.'
+description: 'Selector fixing strategy — diagnose failures, explore live page targeted, fix broken selectors. Auto-loaded by run-test command.'
 user-invocable: false
 ---
 
-## When to Generate
+## Strategy: Fix Only What Breaks
 
-Selectors are generated during `/sungen:run-test`, NOT during `/sungen:create-test`.
+Most selectors auto-infer from Gherkin element types (see `sungen-selector-keys` skill). Only add YAML entries for selectors that fail during test execution.
+
+**Minimal `selectors.yaml`**: page selectors (required), overrides for elements where auto-infer doesn't work. Never generate a full page catalog upfront.
 
 ---
 
-## Step 1: Authenticate & Snapshot
+## Step 1: Diagnose Failures
 
-1. Read `baseURL` from `playwright.config.ts`
-2. `browser_navigate` to `baseURL`
-3. If redirected to login → ask user to log in manually via MCP browser
-4. Navigate to target page → `browser_snapshot`
+Parse Playwright error output to categorize failures:
 
-**Never use `sungen makeauth`.** Never use `browser_evaluate` to inject cookies.
+| Error pattern | Root cause | Fix target |
+|---|---|---|
+| `No element found` / `strict mode violation` | Selector mismatch | `selectors.yaml` |
+| `toBeVisible` timeout | Wrong name or missing element | `selectors.yaml` |
+| `toHaveText` / `toHaveValue` mismatch | Wrong expected data | `test-data.yaml` |
+| `page.goto` error | Wrong URL | page selector in `selectors.yaml` |
+| `frame` error | Element inside iframe | add `frame` field |
+
+**Group by root cause** — if 5 tests fail because `[Submit]` button has a different name, that's 1 fix, not 5.
+
+**Check `test-results/` first** — Playwright captures failure screenshots automatically. Use these to diagnose before any MCP exploration.
 
 ---
 
-## Step 2: Build Element Catalog
+## Step 2: Targeted MCP Exploration
 
-**Never guess names from Gherkin labels. Copy exact values from snapshot.**
+Only when `test-results/` screenshots are insufficient:
 
-Catalog all accessible elements from snapshot: buttons, links, headings, inputs, regions, images.
+1. Read `baseURL` from `playwright.config.ts`
+2. `browser_navigate` to target page
+3. If redirected to login → ask user to log in manually via MCP browser
+4. Take **ONE** `browser_snapshot` — fix all broken selectors from this single snapshot
 
-Then check for `data-testid` attributes:
-```js
-Array.from(document.querySelectorAll('[data-testid]'))
-  .map(e => ({ testid: e.dataset.testid, tag: e.tagName, text: e.textContent.trim().slice(0, 60) }))
-```
+**Never use `sungen makeauth`.** Never use `browser_evaluate` to inject cookies.
 
 ---
 
-## Step 3: Map Gherkin Labels → Selectors
+## Step 3: Fix Broken Selectors
+
+For each failed selector, find the correct locator from the snapshot:
 
 Selector priority (use first applicable):
 
@@ -50,24 +60,24 @@ Selector priority (use first applicable):
 
 **Exact name rule**: copy name character-for-character from snapshot. Never infer from Gherkin label.
 
-**No accessible name**: use `locator` with CSS/ARIA attribute:
-```yaml
-search field:
-  type: 'locator'
-  value: '[role="searchbox"]'
+Check for `data-testid` attributes if role-based matching fails:
+```js
+Array.from(document.querySelectorAll('[data-testid]'))
+  .map(e => ({ testid: e.dataset.testid, tag: e.tagName, text: e.textContent.trim().slice(0, 60) }))
 ```
 
-**Dynamic content**: never use `type: text` with specific value. Use `testid` or structural `role` + `nth`.
-
-**Multiple matches**: add `nth: 0` for first occurrence.
-
-Auto-infer rules and lookup priority → see `sungen-selector-keys` skill.
+Common fixes:
+- Name mismatch → copy exact name from snapshot
+- Multiple matches → add `nth` or `exact: true`
+- No accessible name → use `testid` or `locator` (CSS)
+- Element in iframe → add `frame` field
+- Dynamic content → use `testid` or structural `role` + `nth`
 
 ---
 
 ## Step 4: Table Selectors
 
-For table patterns using the v2.3 syntax, generate table selectors with `columns` config:
+For table patterns, add table selectors with `columns` config:
 
 ```yaml
 users:
@@ -88,15 +98,6 @@ users:
 
 **How to build `columns`**: count column headers in snapshot (left to right, 0-indexed). Map each `[Col] column` reference from feature file to its index.
 
-**Why**: enables exact cell assertion via `cell.nth(index).toHaveText(value)` instead of approximate `cell.filter({ hasText })`.
-
-**Row scope Gherkin** — these patterns use the table selector:
-```gherkin
-Then User see [Username] row in [Users] table with {{user_name}}
-Then User see [Status] column with {{expected_status}}
-When User click [Edit] button in [Users] table with {{user_name}}
-```
-
 ---
 
 ## Step 5: Detail Screens with Dynamic IDs
@@ -113,28 +114,12 @@ user detail:
 
 ---
 
-## Step 6: Validate Before Running
-
-**Fix 80%+ of selector issues before first test run.**
-
-After generating `selectors.yaml`, verify each entry against the live snapshot:
-- `role` + `name` → search snapshot for `role "name"`
-- `testid` → `browser_evaluate`: `document.querySelector('[data-testid="xxx"]')`
-- `placeholder` → search snapshot for textbox with placeholder
-- `page` → verify URL path exists
-
-Common fixes: name mismatch → copy from snapshot, element in iframe → add `frame`, multiple matches → add `nth` or `exact: true`.
-
----
-
-## Step 7: Run & Fix Loop
-
-Run tests in batches of 20. Group failures by root cause (same selector, same error type). Fix once, verify batch, move to next.
-
-```
-compile → batch run 20 → fix root cause → recompile → re-run failures → next batch
-```
+## Step 6: Fix Loop
 
-After all batches pass → run ALL tests once for regression check.
+After fixing selectors:
+1. Recompile: `sungen generate --screen <screen>`
+2. Re-run only failing tests: `npx playwright test --grep "VP-XXX-001|VP-XXX-002" --reporter=line`
+3. If new failures → repeat (max 3 attempts)
+4. After all fixes → run ALL tests once for regression check
 
-If still failing after 5 attempts per batch → ask user about direct `.spec.ts` fix.
+If still failing after 3 attempts → ask user for guidance.

package/src/orchestrator/templates/ai-instructions/claude-skill-tc-generation.md

@@ -100,8 +100,28 @@ Feature: <Screen> Screen
     Then User see [Name] column in [Users] table
     And User see [Email] column in [Users] table
     And User see [Status] column in [Users] table
+
+  # --- Data & Validate ---
+
+  Scenario: VP-VAL-010 Table displays correct data
+    Then User see [Users] table match data:
+      | Name         | Email          | Status       |
+      | {{name_1}}   | {{email_1}}    | {{status_1}} |
+      | {{name_2}}   | {{email_2}}    | {{status_2}} |
+
+  Scenario: VP-VAL-011 Edit button targets correct row
+    Given User see [Target] row in [Users] table with {{name_1}}
+    When User click [Edit] button in [Users] table with {{name_1}}
+    Then User see [Name] field with {{name_1}}
 ```
 
+### When to use DataTable vs Row Scope
+
+| Pattern | Use when |
+|---|---|
+| `table match data:` + DataTable | Verifying **multiple rows** exist with expected values |
+| `row in [Table] table with {{v}}` + `column with {{v}}` | Checking **single row** details or **acting** on a row (click, edit) |
+
 **Naming**: `VP-<CATEGORY>-<NNN>` prefix.
 
 **Test data** — `qa/screens/<screen>/test-data/<screen>.yaml`, grouped by section.

package/src/orchestrator/templates/ai-instructions/claude-skill-viewpoint.md

@@ -52,6 +52,8 @@ user-invocable: false
 - Consistency: total record count on UI matches server data
 - Row Limit: displayed rows never exceed page size/limit
 - Cell Integrity: cell data matches database, correct format (date, currency, status)
+- **Use `table match data:` with inline DataTable** for multi-row content verification (filter-based, resilient to data changes)
+- Use row scope (`row in [Table] table with {{v}}` + `column with {{v}}`) for single-row detail checks or when you need actions on a row
 
 **Logic**
 - Sorting: column sort refreshes data with correct order, updates header icon
@@ -82,7 +84,7 @@ user-invocable: false
 
 **Security**
 - Injection: XSS/SQL encoded as plain text, never executed
-- Wildcards: %, _, * treated as normal text (escaped)
+- Wildcards: `%, _, *` treated as normal text (escaped)
 
 ---
 

package/src/orchestrator/templates/ai-instructions/copilot-cmd-run-test.md

@@ -1,6 +1,6 @@
 ---
 name: sungen-run-test
-description: 'Generate selectors, compile, and run Playwright tests — auto-fixes selectors on failure. Uses sungen-selector-fix, sungen-selector-keys, and sungen-error-mapping skills.'
+description: 'Compile and run Playwright tests — auto-fixes selectors on failure. Uses sungen-selector-fix, sungen-selector-keys, and sungen-error-mapping skills.'
 argument-hint: '[screen-name]'
 agent: 'agent'
 tools: [vscode, execute, read, agent, edit, search, web, browser, todo, 'playwright/*']
@@ -10,23 +10,26 @@ tools: [vscode, execute, read, agent, edit, search, web, browser, todo, 'playwri
 
 ## Role
 
-You are a **Senior Developer** specialized in Playwright test debugging. You generate selectors from live pages, diagnose test failures, and fix selectors/test-data using the `sungen-selector-fix`, `sungen-selector-keys`, and `sungen-error-mapping` skills.
+You are a **Senior Developer**. Use `sungen-selector-fix`, `sungen-selector-keys`, and `sungen-error-mapping` skills.
 
 ## Parameters
 
 - **screen** — ${input:screen:screen name (e.g., login, dashboard)}
 
-## Steps
-
-1. Verify `qa/screens/${input:screen}/` has `.feature` + `test-data.yaml`. If not → run `/sungen-create-test` first.
-2. **Generate selectors** — explore live page via #tool:playwright, build `selectors.yaml` (per `sungen-selector-fix` skill).
-3. **Proactive validation** — verify EVERY selector against the live page using `browser_snapshot` + `browser_evaluate` BEFORE running any test. Fix mismatches immediately. See `sungen-selector-fix` skill "Proactive Selector Validation" section. Target: 80%+ issues fixed before first run.
-4. **Compile** with #tool:terminal: `sungen generate --screen ${input:screen}`
-5. **Batched test run** — run tests in batches of 20 via `--grep`:
-   `npx playwright test specs/generated/${input:screen}/*.spec.ts --grep "VP-UI-001|...|VP-UI-020" --reporter=line`
-   - If failures in batch → group by root cause, fix, recompile, re-run only failing tests
-   - If batch passes → move to next 20 tests
-   - Max 5 fix attempts per batch
-6. **Final confirmation** — run ALL tests once to catch regressions.
-7. After 5 fix attempts still failing → ask user about direct `.spec.ts` fix.
-8. Show: pass/fail, attempt count, files changed.
+## Phase 1: Compile & Run (no MCP)
+
+1. Verify `qa/screens/${input:screen}/` has `.feature` + `test-data.yaml`
+2. Ensure `selectors.yaml` has page selector. If missing, ask user for URL path
+3. `sungen generate --screen ${input:screen}`
+4. `npx playwright test specs/generated/${input:screen}/*.spec.ts --reporter=line`
+5. If all pass → done
+
+## Phase 2: Targeted Fix (only if failures)
+
+6. Parse failures → group by root cause
+7. Navigate to page ONCE via #tool:playwright → ONE `browser_snapshot`
+8. Fix broken selectors per `sungen-selector-fix` skill
+9. Recompile → re-run only failing tests
+10. Repeat up to 3 attempts
+11. Final full run for regression check
+12. Still failing → ask user

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-error-mapping.md

@@ -81,12 +81,12 @@ If `toHaveText` fails on an input → the Gherkin step has wrong target type. Fi
 
 | Symptom | Fix |
 |---|---|
-| Redirect to login page | Auth expired. Tell user: `sungen makeauth <role> --url <baseURL>` |
-| `storageState` file not found | Run `sungen makeauth <role> --url <baseURL>` |
-| Most tests timeout on first step | Auth expired — re-run makeauth |
-| Page shows home instead of target | SPA + expired auth. Re-run makeauth + add `wait for` step |
+| Redirect to login page | Auth expired. Ask user to log in manually via MCP browser |
+| `storageState` file not found | Ask user to log in manually via MCP browser, then save storage state |
+| Most tests timeout on first step | Auth expired — ask user to re-authenticate via MCP browser |
+| Page shows home instead of target | SPA + expired auth. Re-authenticate + add `wait for` step |
 
-**Never run `sungen makeauth` yourself.** Tell the user.
+**Never use `sungen makeauth`.** Always let the user log in manually via the MCP browser.
 
 ---
 

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-gherkin-syntax.md

@@ -50,7 +50,7 @@ User check [T] radio                             # select radio
 User uncheck [T] checkbox                        # uncheck
 User uncheck [T] toggle                          # toggle off
 User select [T] dropdown with {{v}}              # select option
-User upload [T] uploader with {{f}}              # file upload
+User fill [T] uploader with {{f}}                # file upload
 ```
 
 ### Interaction
@@ -161,10 +161,17 @@ User see [Table] table with {{count}}                           # row count
 User see [Table] table is empty                                 # empty table
 User see [Col] column with {{v}}                                # cell value (row scoped)
 User click [Act] button in [Table] table with {{v}}             # action in row
+User see [Table] table match data:                              # exact table match (inline DataTable)
+    | Header1    | Header2    |
+    | {{value1}} | {{value2}} |
 ```
 
+**Priority**: Use row scope patterns for single-row verification + actions. Use `table match data` only when verifying multiple rows at once.
+
 Row scope: `see [Ref] row in [Table] table with {{v}}` defines `tableRow`. Subsequent `see [Col] column with {{v}}` checks the cell in that row. With `columns` config → exact `nth(index)`, without → `filter({ hasText })`.
 
+Table match data: `see [Table] table match data:` followed by a Cucumber DataTable. First row = headers, remaining rows = expected data. Uses **filter-based matching** — verifies rows containing expected values exist, resilient to data changes, extra rows, and row reordering. Use `{{variable}}` for cell values.
+
 ### States
 
 `hidden` `visible` `disabled` `enabled` `checked` `unchecked` `focused` `empty` `loading` `selected` `sorted ascending` `sorted descending`

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-selector-fix.md

@@ -1,41 +1,51 @@
 ---
 name: sungen-selector-fix
-description: 'Selector generation and fixing strategy — explore live page, generate selectors.yaml, validate, auto-fix. Auto-loaded by run-test command.'
+description: 'Selector fixing strategy — diagnose failures, explore live page targeted, fix broken selectors. Auto-loaded by run-test command.'
 user-invocable: false
 ---
 
-## When to Generate
+## Strategy: Fix Only What Breaks
 
-Selectors are generated during `/sungen:run-test`, NOT during `/sungen:create-test`.
+Most selectors auto-infer from Gherkin element types (see `sungen-selector-keys` skill). Only add YAML entries for selectors that fail during test execution.
+
+**Minimal `selectors.yaml`**: page selectors (required), overrides for elements where auto-infer doesn't work. Never generate a full page catalog upfront.
 
 ---
 
-## Step 1: Authenticate & Snapshot
+## Step 1: Diagnose Failures
 
-1. Read `baseURL` from `playwright.config.ts`
-2. `browser_navigate` to `baseURL`
-3. If redirected to login → ask user to log in manually via MCP browser
-4. Navigate to target page → `browser_snapshot`
+Parse Playwright error output to categorize failures:
 
-**Never use `sungen makeauth`.** Never use `browser_evaluate` to inject cookies.
+| Error pattern | Root cause | Fix target |
+|---|---|---|
+| `No element found` / `strict mode violation` | Selector mismatch | `selectors.yaml` |
+| `toBeVisible` timeout | Wrong name or missing element | `selectors.yaml` |
+| `toHaveText` / `toHaveValue` mismatch | Wrong expected data | `test-data.yaml` |
+| `page.goto` error | Wrong URL | page selector in `selectors.yaml` |
+| `frame` error | Element inside iframe | add `frame` field |
+
+**Group by root cause** — if 5 tests fail because `[Submit]` button has a different name, that's 1 fix, not 5.
+
+**Check `test-results/` first** — Playwright captures failure screenshots automatically. Use these to diagnose before any MCP exploration.
 
 ---
 
-## Step 2: Build Element Catalog
+## Step 2: Targeted MCP Exploration
 
-**Never guess names from Gherkin labels. Copy exact values from snapshot.**
+Only when `test-results/` screenshots are insufficient:
 
-Catalog all accessible elements from snapshot: buttons, links, headings, inputs, regions, images.
+1. Read `baseURL` from `playwright.config.ts`
+2. `browser_navigate` to target page
+3. If redirected to login → ask user to log in manually via MCP browser
+4. Take **ONE** `browser_snapshot` — fix all broken selectors from this single snapshot
 
-Then check for `data-testid` attributes:
-```js
-Array.from(document.querySelectorAll('[data-testid]'))
-  .map(e => ({ testid: e.dataset.testid, tag: e.tagName, text: e.textContent.trim().slice(0, 60) }))
-```
+**Never use `sungen makeauth`.** Never use `browser_evaluate` to inject cookies.
 
 ---
 
-## Step 3: Map Gherkin Labels → Selectors
+## Step 3: Fix Broken Selectors
+
+For each failed selector, find the correct locator from the snapshot:
 
 Selector priority (use first applicable):
 
@@ -50,24 +60,24 @@ Selector priority (use first applicable):
 
 **Exact name rule**: copy name character-for-character from snapshot. Never infer from Gherkin label.
 
-**No accessible name**: use `locator` with CSS/ARIA attribute:
-```yaml
-search field:
-  type: 'locator'
-  value: '[role="searchbox"]'
+Check for `data-testid` attributes if role-based matching fails:
+```js
+Array.from(document.querySelectorAll('[data-testid]'))
+  .map(e => ({ testid: e.dataset.testid, tag: e.tagName, text: e.textContent.trim().slice(0, 60) }))
 ```
 
-**Dynamic content**: never use `type: text` with specific value. Use `testid` or structural `role` + `nth`.
-
-**Multiple matches**: add `nth: 0` for first occurrence.
-
-Auto-infer rules and lookup priority → see `sungen-selector-keys` skill.
+Common fixes:
+- Name mismatch → copy exact name from snapshot
+- Multiple matches → add `nth` or `exact: true`
+- No accessible name → use `testid` or `locator` (CSS)
+- Element in iframe → add `frame` field
+- Dynamic content → use `testid` or structural `role` + `nth`
 
 ---
 
 ## Step 4: Table Selectors
 
-For table patterns using the v2.3 syntax, generate table selectors with `columns` config:
+For table patterns, add table selectors with `columns` config:
 
 ```yaml
 users:
@@ -88,15 +98,6 @@ users:
 
 **How to build `columns`**: count column headers in snapshot (left to right, 0-indexed). Map each `[Col] column` reference from feature file to its index.
 
-**Why**: enables exact cell assertion via `cell.nth(index).toHaveText(value)` instead of approximate `cell.filter({ hasText })`.
-
-**Row scope Gherkin** — these patterns use the table selector:
-```gherkin
-Then User see [Username] row in [Users] table with {{user_name}}
-Then User see [Status] column with {{expected_status}}
-When User click [Edit] button in [Users] table with {{user_name}}
-```
-
 ---
 
 ## Step 5: Detail Screens with Dynamic IDs
@@ -113,28 +114,12 @@ user detail:
 
 ---
 
-## Step 6: Validate Before Running
-
-**Fix 80%+ of selector issues before first test run.**
-
-After generating `selectors.yaml`, verify each entry against the live snapshot:
-- `role` + `name` → search snapshot for `role "name"`
-- `testid` → `browser_evaluate`: `document.querySelector('[data-testid="xxx"]')`
-- `placeholder` → search snapshot for textbox with placeholder
-- `page` → verify URL path exists
-
-Common fixes: name mismatch → copy from snapshot, element in iframe → add `frame`, multiple matches → add `nth` or `exact: true`.
-
----
-
-## Step 7: Run & Fix Loop
-
-Run tests in batches of 20. Group failures by root cause (same selector, same error type). Fix once, verify batch, move to next.
-
-```
-compile → batch run 20 → fix root cause → recompile → re-run failures → next batch
-```
+## Step 6: Fix Loop
 
-After all batches pass → run ALL tests once for regression check.
+After fixing selectors:
+1. Recompile: `sungen generate --screen <screen>`
+2. Re-run only failing tests: `npx playwright test --grep "VP-XXX-001|VP-XXX-002" --reporter=line`
+3. If new failures → repeat (max 3 attempts)
+4. After all fixes → run ALL tests once for regression check
 
-If still failing after 5 attempts per batch → ask user about direct `.spec.ts` fix.
+If still failing after 3 attempts → ask user for guidance.

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-tc-generation.md

@@ -100,8 +100,28 @@ Feature: <Screen> Screen
     Then User see [Name] column in [Users] table
     And User see [Email] column in [Users] table
     And User see [Status] column in [Users] table
+
+  # --- Data & Validate ---
+
+  Scenario: VP-VAL-010 Table displays correct data
+    Then User see [Users] table match data:
+      | Name         | Email          | Status       |
+      | {{name_1}}   | {{email_1}}    | {{status_1}} |
+      | {{name_2}}   | {{email_2}}    | {{status_2}} |
+
+  Scenario: VP-VAL-011 Edit button targets correct row
+    Given User see [Target] row in [Users] table with {{name_1}}
+    When User click [Edit] button in [Users] table with {{name_1}}
+    Then User see [Name] field with {{name_1}}
 ```
 
+### When to use DataTable vs Row Scope
+
+| Pattern | Use when |
+|---|---|
+| `table match data:` + DataTable | Verifying **multiple rows** exist with expected values |
+| `row in [Table] table with {{v}}` + `column with {{v}}` | Checking **single row** details or **acting** on a row (click, edit) |
+
 **Naming**: `VP-<CATEGORY>-<NNN>` prefix.
 
 **Test data** — `qa/screens/<screen>/test-data/<screen>.yaml`, grouped by section.

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-viewpoint.md

@@ -52,6 +52,8 @@ user-invocable: false
 - Consistency: total record count on UI matches server data
 - Row Limit: displayed rows never exceed page size/limit
 - Cell Integrity: cell data matches database, correct format (date, currency, status)
+- **Use `table match data:` with inline DataTable** for multi-row content verification (filter-based, resilient to data changes)
+- Use row scope (`row in [Table] table with {{v}}` + `column with {{v}}`) for single-row detail checks or when you need actions on a row
 
 **Logic**
 - Sorting: column sort refreshes data with correct order, updates header icon
@@ -82,7 +84,7 @@ user-invocable: false
 
 **Security**
 - Injection: XSS/SQL encoded as plain text, never executed
-- Wildcards: %, _, * treated as normal text (escaped)
+- Wildcards: `%, _, *` treated as normal text (escaped)
 
 ---