1. Read project-specific E2E patterns (REQUIRED)

<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:START -->

[BLOCKING] Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. [BLOCKING] Before each step or sub-skill call, update task tracking: set in_progress when step starts, set completed when step ends. [BLOCKING] Every completed/​skipped step MUST include brief evidence or explicit skip reason. [BLOCKING] If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.

<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:END -->

Quick Summary

Goal: Produce maintainable, spec-traceable E2E tests (TC-{MODULE}-E2E-{NNN}) from recordings, specs, or code changes that protect business behavior using the project's configured framework (Playwright, Selenium, Cypress, others) — so future UI changes break tests only when intended behavior breaks.

Workflow:

1. Detect — classify request scope, target artifacts, framework.
2. Execute — apply required steps, evidence-backed actions.
3. Verify — confirm constraints, output quality, completion evidence.

Key Rules:

• MUST ATTENTION keep claims evidence-based (file:line), confidence >80% to act.
• MUST ATTENTION keep task tracking updated as each step starts/​completes.
• NEVER skip mandatory workflow or skill gates.

⚠️ MANDATORY: Read Project E2E Reference (FIRST)

BEFORE ANY E2E WORK, you MUST ATTENTION:

# 1. Read project-specific E2E patterns (REQUIRED)
head -100 docs/​project-reference/​e2e-test-reference.md

# 2. Read project config for framework, paths, commands
grep -A 50 '"e2eTesting"' docs/​project-config.json

# 3. Find TC codes you need to implement
grep -r "TC-.*-E2E-" docs/​specs/ docs/​specs/

The e2eTesting section in docs/​project-config.json contains:

• Framework, language, paths, run commands, TC code format
• Project-specific best practices and entry points

When investigating/​fixing E2E failures, update docs/​project-reference/​e2e-test-reference.md with learnings.

• docs/​project-reference/​domain-entities-reference.md — Domain entity catalog, relationships, cross-service sync (read when task involves business entities/​models)

---

Framework Detection (SECOND STEP)

Detect the project's E2E stack before generating tests:

# Use project config, project-reference docs, and existing test config files as the source of truth
rg "playwright|cypress|selenium|webdriver|e2e" docs/​project-config.json docs/​project-reference/ . 2>/​dev/​null
rg --files | rg "(playwright|cypress|webdriver|selenium|e2e|test).*config|manifest|project"

---

Workflow Modes

---

First Principle — Easy to Change

The success metric of every coding decision is future change cost. DRY, SRP, abstraction, design patterns, naming, layering, tests — every technique exists to serve one goal: making the next change cheaper.

Evaluating code, refactor, test, abstraction, ask: does this make next change cheaper or more expensive?

• Reject "best practices" raising change cost (premature abstraction, speculative generality, leaky indirection, ceremony without payoff).
• Name real enemies in findings: coupling, hidden state, duplicated knowledge, unclear intent, irreversible decisions exposed too early.
• Simpler design easy to change beats sophisticated design that isn't.

Apply this lens before invoking any specific rule, pattern, checklist below — if downstream rule would raise change cost, this principle wins.

---

Core Principles

1. TC Code Traceability (MANDATORY)

Every E2E test MUST ATTENTION have:

• TC code in test name: TC-{MODULE}-E2E-{NNN}
• Tag/​annotation linking to spec
• Comment linking to feature doc

// TypeScript
test('TC-RT-E2E-001: Submit return request', async () => { ... });

Use repository's configured test-case annotation mechanism for non-TypeScript E2E tests; NEVER invent a framework-specific marker.

2. Page Object Model

All frameworks use Page Object pattern:

• Encapsulate page locators in page class
• Methods represent user actions
• Assertions in test file, not page object

3. Selector Strategy (Priority Order)

1. Semantic classes — BEM (.block__element), component classes
2. Data attributes — [data-testid], [data-cy], [data-test]
3. ARIA/​Role — role=button, aria-label
4. Text content — Visible user text (last resort)

AVOID: Generated classes (.ng-star-inserted, .MuiButton-root), positional selectors (:nth-child), XPath

4. Unique Test Data

Tests MUST generate unique data to be repeatable:

• Append GUIDs/​timestamps to test data
• Make each test self-sufficient with own generated data; NEVER depend on specific pre-existing database state
• Leave seeded data in place after run, NEVER clean up — why: teardown across shared runs creates side effects for parallel/​repeat tests

5. Preconditions Documentation

Document what must exist before test runs:

• System: Infrastructure running, APIs healthy
• Data: Seed data exists (users, companies)
• Feature: Configurations complete

---

Steps

1. Detect framework from project files
2. Read project E2E docs for conventions and patterns
3. Load test specs with TC codes from feature docs
4. Generate/​update tests following Page Object pattern
5. Run tests using project's configured commands
6. Update e2e-test-reference.md with any learnings

---

Output

Report:

• Files created/​modified
• TC codes covered
• Run command to execute tests
• Any preconditions or setup needed

---

Sub-Agent Type Override

MANDATORY: E2E test generation and baseline updates spawn e2e-runner sub-agent (subagent_type: "e2e-runner"), NOT the main agent directly. Rationale: e2e-runner auto-detects the project's E2E stack, maintains test-to-spec TC traceability, and handles visual baseline updates across Playwright, Selenium, Cypress, and other frameworks.

Spawn e2e-runner sub-agent for:

• Generating new E2E tests from recordings or TC codes from specs
• Updating visual screenshot baselines after UI changes
• Maintaining TC code traceability (TC-{MODULE}-E2E-{NNN}) in test implementations

---

Workflow Recommendation

MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS: If you are NOT already in a workflow, you MUST ATTENTION use AskUserQuestion to ask the user. Do NOT judge task complexity or decide this is "simple enough to skip" — the user decides whether to use a workflow, not you:

1. Activate e2e --source=changes workflow (Recommended) — scout → e2e-test → test → watzup
2. Execute /​e2e-test directly — run this skill standalone

---

Skill: e2e-test

Category: [Testing] Trigger: e2e test, e2e from recording, generate e2e, playwright test, cypress test, selenium test, webdriver, puppeteer

Generate and maintain E2E tests using project's configured testing framework.

• docs/​specs/ — Test specifications by module (read existing TCs for E2E scenario coverage; match TC codes to E2E test implementations)

Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).

---

<!-- SYNC:sub-agent-selection -->

Sub-Agent Selection — Full routing contract: .claude/​skills/​shared/​sub-agent-selection-guide.md Rule: Route specialized domains (architecture, security, performance, DB, E2E, integration-test, git) to the matching specialist agent (see guide above) — NEVER use code-reviewer for these. — why: code-reviewer lacks each domain's checklist, so specialized issues slip through.

<!-- /​SYNC:sub-agent-selection --> <!-- SYNC:source-test-drift-check -->

Source/​test drift check. For coding, fix, debug, investigation, test, or review work: when source behavior changes, inspect affected unit/​integration/​E2E tests and decide from evidence whether tests should change to match intended behavior or the source change is an unintended bug to fix. Do not write tests for migration code; schema/​data migrations are one-time execution paths, not core application logic.

<!-- /​SYNC:source-test-drift-check --> <!-- SYNC:ai-mistake-prevention -->

AI Mistake Prevention — Failure modes to avoid on every task:

Check downstream references before deleting. Deleting components causes documentation and code staleness cascades. Map all referencing files before removal. Verify AI-generated content against actual code. AI hallucinates APIs, class names, and method signatures. Always grep to confirm existence before documenting or referencing. Trace full dependency chain after edits. Changing a definition misses downstream variables and consumers derived from it. Always trace the full chain. Trace ALL code paths when verifying correctness. Confirming code exists is not confirming it executes. Always trace early exits, error branches, and conditional skips — not just happy path. When debugging, ask "whose responsibility?" before fixing. Trace whether bug is in caller (wrong data) or callee (wrong handling). Fix at responsible layer — never patch symptom site. Assume existing values are intentional — ask WHY before changing. Before changing any constant, limit, flag, or pattern: read comments, check git blame, examine surrounding code. Verify ALL affected outputs, not just the first. Changes touching multiple stacks require verifying EVERY output. One green check is not all green checks. Holistic-first debugging — resist nearest-attention trap. When investigating any failure, list EVERY precondition first (config, env vars, DB names, endpoints, DI registrations, data preconditions), then verify each against evidence before forming any code-layer hypothesis. Surgical changes — apply the diff test. Bug fix: every changed line must trace directly to the bug. Don't restyle or improve adjacent code. Enhancement task: implement improvements AND announce them explicitly. Surface ambiguity before coding — don't pick silently. If request has multiple interpretations, present each with effort estimate and ask. Never assume all-records, file-based, or more complex path. Keep domain concepts out of generic/​shared/​infrastructure layers. A reusable layer (shared library, framework, infra module) must reference NO consumer-specific domain concept — tenant/​customer/​product IDs, business entities, feature rules. The leak compiles and runs, so it passes review silently while coupling the "reusable" layer to one consumer. Push domain fields/​logic down into the consumer via subclass or composition.

<!-- /​SYNC:ai-mistake-prevention --> <!-- SYNC:critical-thinking-mindset -->

Critical Thinking Mindset — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act. Anti-hallucination: Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination.

<!-- /​SYNC:critical-thinking-mindset --> <!-- SYNC:critical-thinking-mindset:reminder -->

MUST ATTENTION apply critical thinking — every claim needs traced proof, confidence >80% to act. Anti-hallucination: never present guess as fact.

<!-- /​SYNC:critical-thinking-mindset:reminder --> <!-- SYNC:ai-mistake-prevention:reminder -->

MUST ATTENTION apply AI mistake prevention — holistic-first debugging, fix at responsible layer, surface ambiguity before coding, re-read files after compaction.

<!-- /​SYNC:ai-mistake-prevention:reminder --> <!-- PROMPT-ENHANCE:STEP-TASK-CLOSING:START -->

Prompt-Enhance Closing Anchors

IMPORTANT MUST ATTENTION follow declared step order for this skill; NEVER skip, reorder, or merge steps without explicit user approval IMPORTANT MUST ATTENTION for every step/​sub-skill call: set in_progress before execution, set completed after execution IMPORTANT MUST ATTENTION every skipped step MUST include explicit reason; every completed step MUST include concise evidence IMPORTANT MUST ATTENTION if Task tools unavailable, maintain an equivalent step-by-step plan tracker with synchronized statuses

<!-- PROMPT-ENHANCE:STEP-TASK-CLOSING:END -->

Closing Reminders

IMPORTANT MUST ATTENTION Goal: Produce maintainable, spec-traceable E2E tests (TC-{MODULE}-E2E-{NNN}) that protect business behavior using the project's configured framework — so future UI changes break tests only when intended behavior breaks.

• MANDATORY IMPORTANT MUST ATTENTION break work into small todo tasks using TaskCreate BEFORE starting
• MANDATORY IMPORTANT MUST ATTENTION search codebase for 3+ similar patterns before creating new code
• MANDATORY IMPORTANT MUST ATTENTION cite file:line evidence for every claim (confidence >80% to act)
• MANDATORY IMPORTANT MUST ATTENTION every E2E test carries its TC code; NEVER use generated/​positional selectors — prefer semantic > data-attr > ARIA > text
• MANDATORY IMPORTANT MUST ATTENTION add a final review todo task to verify work quality

[TASK-PLANNING] Before acting, analyze task scope and systematically break it into small todo tasks and sub-tasks using TaskCreate.

[IMPORTANT] Analyze how big the task is and break it into many small todo tasks systematically before starting — this is very important.

---

Closing reminder — Easy to Change is the success metric. Every finding, test, refactor, and abstraction must answer one question: does this make the next change cheaper or more expensive? If it doesn't reduce future change cost, reject it. Coupling, hidden state, duplicated knowledge, and unclear intent are the real enemies — call them out by name.