evizi-kit 1.0.0

package/kits/shared/skills/web-auto-fix-and-run-test/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: web-auto-fix-and-run-test
+description: Fix code issues from a review report (issues.md), run the test command once, and report a structured PASS/FAIL result. Reads issues.md and ticket-playbook.md for a given ticket, applies fixes in priority order (Critical → Warnings → Suggestions), executes the test command once, and on failure emits a structured failure summary for the master agent to route to web-auto-assisted-fix-and-run. Use this skill whenever someone mentions fixing review issues and running tests, resolving code review feedback, running a ticket after review, or any variation of "fix and run". Also trigger for requests like "apply fixes and test ticket X", "resolve issues for ABC-123", "run tests after code review for fe-2026", "fix the review report issues", or "process issues.md for ticket Y" — even if the user doesn't explicitly say "fix and run".
+---
+
+# Web Automation Fix and Run Test
+
+Read a review report (`issues.md`) for a given ticket ID, fix all identified issues in priority order, and run the test command once. Report a structured PASS/FAIL result — on failure the master agent routes to `web-auto-assisted-fix-and-run` for user-assisted retry.
+
+This skill occupies a specific position in the pipeline: it receives output from `web-auto-self-reviewer` (which creates `issues.md`) and hands off to either `push-code` (on success) or `web-auto-assisted-fix-and-run` (on failure). The structured result block at the end is how the master agent reads the outcome and decides what to do next.
+
+## Input Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `TICKET_ID` | string | Yes | The ticket identifier (e.g., TKT-001, ABC-123) |
+
+**If `TICKET_ID` is not provided:** Ask the user for the ticket ID before proceeding.
+
+## Workflow
+
+### Step 1: Read and Parse the Review Report
+
+Search for the issues file:
+
+```
+.tickets/{TICKET_ID}/issues.md
+```
+
+**If not found:** Inform the user and stop:
+
+```
+Error: issues.md not found for ticket {TICKET_ID}.
+Run the review step first to create it.
+```
+
+**If found:** Extract:
+- **Verdict** — APPROVED / APPROVED WITH WARNINGS / NEEDS CHANGES
+- **Critical Issues** — must fix before running
+- **Warnings** — should fix after critical issues
+- **Suggestions** — optional improvements
+- **Notes for Fix-and-Run** — special instructions including the test run command
+
+Organize by priority:
+1. **Critical** — fix first because they are bugs or breaking changes that will definitely cause test failures
+2. **Warnings** — fix after critical issues because they are code quality concerns that could cause flaky or unreliable behavior
+3. **Suggestions** — fix if time permits (optional); these are style and readability improvements that won't affect test outcomes
+
+### Step 2: Read Context Files
+
+Before touching any code, build a mental model of what the code does and how it should look. This prevents blind fix application that introduces more problems than it solves.
+
+1. **Ticket Playbook:** Read `ticket-playbook.md` in the same ticket directory
+   - Understand what the code implements, its dependencies, and the expected file structure
+   - **If not found:** Inform the user and stop — without the playbook you have no context for whether a fix is correct
+
+2. **Instructions Used:** Location specified in Section 1 of the ticket playbook
+   - Understand the specific coding standards, naming conventions, and patterns to follow
+
+### Step 3: Fix All Issues
+
+Work through issues in priority order. Group issues that target the same file so you can read the file once, apply all relevant fixes, then verify — this reduces the chance of stale reads and conflicting edits.
+
+For each issue:
+
+**3.1 — Understand**
+- Read the issue description, file path, line number, and category
+- Read the recommended fix
+- Confirm the referenced code still exists at the expected location — the code may have shifted since the review. If the exact line doesn't match, search the file for the relevant code pattern
+
+**3.2 — Fix**
+- Read the target file (or use the already-loaded content if you grouped same-file issues)
+- Locate the problematic code
+- Apply the recommended fix following project patterns and coding standards from Step 2
+- If two issues recommend conflicting changes to the same code (e.g., one says rename a method, another says relocate it), apply the higher-severity fix first and then adapt the lower-severity fix to work with the result
+
+**3.3 — Verify**
+- Check for syntax and linting errors in the modified file
+- If a fix introduces a new error (broken import, syntax issue, type mismatch), **revert that specific fix** and move on — a bad fix is worse than the original issue because it may cascade across the codebase
+- Check cross-file impacts: if you changed a method signature, export name, or file path, verify that other files importing or calling it are still compatible. The playbook's dependency map (from Step 2) tells you which files reference which
+
+Fix all Critical Issues and Warnings before proceeding to Step 4. Suggestions are optional — skip them if fixing them risks introducing instability.
+
+### Step 4: Run Tests
+
+**Get the run command:**
+- Use the command from the "Notes for Fix-and-Run" section of `issues.md`
+- If unclear, check the project configuration file (e.g., `package.json`) for available test scripts
+
+**Execute:**
+1. Run the command and capture full output (stdout and stderr)
+2. Analyze the result:
+   - **Success** → proceed to Step 6
+   - **Failure** → proceed to Step 5 (diagnose runtime error)
+
+### Step 5: Diagnose Runtime Error
+
+Do not apply any fixes in this step. The purpose is to produce a precise diagnosis so that `web-auto-assisted-fix-and-run` (or the user) can act on it with full context. A good diagnosis saves the next step significant time; a vague one wastes it.
+
+**5.1 — Parse error output**
+- Identify error type, file, line number, error message, and stack trace
+- Capture the relevant stack trace excerpt (the first 5-10 meaningful frames, skipping framework internals)
+
+**5.2 — Classify the error**
+
+| Error Type | Description | Common Cause |
+|------------|-------------|--------------|
+| SyntaxError | Malformed code — brackets, quotes, semicolons | A fix introduced a typo or unclosed bracket |
+| TypeError | Null/undefined reference or wrong variable type | Accessing a property on a variable that doesn't exist yet |
+| ReferenceError | Variable or function not defined | Missing import or misspelled identifier |
+| TimeoutError | Element not found in time or navigation too slow | Wrong selector, page hasn't loaded, or element is conditionally rendered |
+| AssertionError | Test expectation did not match actual result | Wrong expected value or test logic issue |
+| LocatorError | Selector did not match any element in the DOM | Element has changed, was renamed, or doesn't exist on the page |
+| ImportError | Wrong import path or missing export | Typo in path, missing barrel export, or wrong package name |
+| NetworkError | API call failed, connection refused, or timeout | Wrong endpoint, auth failure, or test environment down |
+| ConfigurationError | Missing environment variable, wrong config, or setup issue | Test environment misconfigured or missing prerequisite |
+| Other | Does not fit the above categories | Include the raw error name and classify as best as possible |
+
+**5.3 — Summarize findings**
+- State the error type, exact location (file:line), and the verbatim error message
+- Include the relevant stack trace excerpt
+- Note the likely cause based on the classification and surrounding context
+- If the error is selector-related (LocatorError, element TimeoutError), note this for `web-auto-assisted-fix-and-run` so it can apply the selector resolution cascade from `references/resolve-selector.md`
+- If the error is API-related (NetworkError with HTTP status, auth failure), note this for the API error resolution cascade from `references/resolve-api-error.md`
+- Do NOT apply any code changes — proceed directly to Step 7
+
+### Step 6: Success — Create Resolution Report
+
+Create `issues-resolution-report.md` in the same ticket directory using the **Success Template** from [templates/issues-resolution-report.template.md](templates/issues-resolution-report.template.md).
+
+```
+.tickets/{TICKET_ID}/issues-resolution-report.md
+```
+
+Emit the following result block so the master agent can detect the outcome and route to `push-code`:
+
+```
+FIX-AND-RUN RESULT: PASSED
+Issues Fixed: Critical: {count}, Warnings: {count}
+Files Modified: {comma-separated list}
+Report saved to: .tickets/{TICKET_ID}/issues-resolution-report.md
+```
+
+### Step 7: Failure — Create Resolution Report and Emit Failure Summary
+
+Create `issues-resolution-report.md` in the same ticket directory using the **Failure Template** from [templates/issues-resolution-report.template.md](templates/issues-resolution-report.template.md).
+
+```
+.tickets/{TICKET_ID}/issues-resolution-report.md
+```
+
+Emit the following structured failure block so the master agent can pass it to `web-auto-assisted-fix-and-run`:
+
+```
+FIX-AND-RUN RESULT: FAILED
+Ticket: {TICKET_ID}
+Error Type: {error type}
+Location: {file:line}
+Message: {error message}
+Stack Trace:
+{first 5-10 meaningful stack frames}
+Likely Cause: {diagnosis from Step 5}
+Issues Fixed Before Run: Critical: {count}, Warnings: {count}
+Files Modified: {comma-separated list}
+Report saved to: .tickets/{TICKET_ID}/issues-resolution-report.md
+```
+
+## Why This Skill Only Runs Once
+
+This skill gets exactly one test run. If that run fails, it diagnoses the error and hands off to `web-auto-assisted-fix-and-run`, which has access to user hints and specialized reference guides (selector resolution cascades, API error resolution) to handle runtime failures. Trying to autonomously fix runtime errors here would duplicate that skill's logic and often leads to cascading bad fixes — a wrong selector guess triggers a different error, which triggers another guess, and so on. The clean separation means this skill focuses on what it's good at (applying known review fixes) and delegates runtime debugging to the right specialist.
+
+## Important Rules
+
+- **1 run attempt maximum** — the test runs exactly once. If it fails, diagnose and report. Runtime fixing is handled downstream by `web-auto-assisted-fix-and-run`, which has user hints and specialized tools for it
+- **Read issues.md first** — it is the primary input and contains the run command
+- **Fix Critical issues before running** — critical issues are bugs that will definitely cause test failures; running with unresolved criticals wastes the single run attempt
+- **Understand before fixing** — read each issue fully and confirm the code still matches before applying any change; blind fixes on shifted code introduce new bugs
+- **Group same-file fixes** — reading a file once and applying all its fixes together avoids stale-read conflicts where fix 2 overwrites fix 1
+- **Revert bad static fixes** — if a fix from issues.md introduces a new linter or syntax error, revert that fix rather than trying to patch on top of it; a clean codebase going into the test run is more important than fixing every review item
+- **Check cross-file impacts** — when a fix changes a method signature, export name, or file path, verify callers and importers are still compatible
+- **Always emit the result block** — the structured `FIX-AND-RUN RESULT:` block (on both success and failure) is how the master agent reads the outcome; without it the pipeline stalls
+- **No runtime fixes** — after the test run, do not touch code; only diagnose and report
+- **Document all fixes** — create issues-resolution-report.md using the resolution report template so the next step has a full history of what changed

package/kits/shared/skills/web-auto-fix-and-run-test/templates/issues-resolution-report.template.md

@@ -0,0 +1,77 @@
+# Issues Resolution Report Template
+
+Use one of the templates below to create `issues-resolution-report.md` in the ticket directory after completing the fix-and-run process.
+
+---
+
+## Success Template
+
+```markdown
+# Fix-and-Run Resolution
+
+| Field | Value |
+|-------|-------|
+| Run Status | SUCCESS |
+
+### Issues Fixed
+
+| # | Severity | File | Line | Description | Fix Applied |
+|---|----------|------|------|-------------|-------------|
+| 1 | Critical | {file} | {line} | {description} | {fix} |
+| 2 | Warning  | {file} | {line} | {description} | {fix} |
+
+### Final Run Output
+
+\`\`\`
+{paste the final successful run output here}
+\`\`\`
+```
+
+---
+
+## Failure Template
+
+```markdown
+# Fix-and-Run Resolution
+
+| Field | Value |
+|-------|-------|
+| Run Status | FAILED (Autonomous Attempt) |
+| Total Run Attempts | 1/1 |
+
+### Issues Fixed Before Failure
+
+| # | Severity | File | Line | Description | Fix Applied |
+|---|----------|------|------|-------------|-------------|
+| 1 | Critical | {file} | {line} | {description} | {fix} |
+
+### Issues Skipped / Reverted
+
+| # | Severity | File | Line | Description | Reason |
+|---|----------|------|------|-------------|--------|
+| 1 | Warning  | {file} | {line} | {description} | {reason — e.g., "Fix introduced SyntaxError, reverted"} |
+
+_(Omit this section if all issues were fixed successfully.)_
+
+### Runtime Error Diagnosis
+
+| Field | Value |
+|-------|-------|
+| Error Type | {error type} |
+| File | {file path} |
+| Line | {line number} |
+| Message | {error message} |
+| Likely Cause | {diagnosis from Step 5} |
+
+### Stack Trace Excerpt
+
+\`\`\`
+{paste the first 5-10 meaningful stack frames here, skipping framework internals}
+\`\`\`
+
+### Test Run Output
+
+\`\`\`
+{paste the relevant portion of the test output — the failure message and surrounding context}
+\`\`\`
+```

package/kits/shared/skills/web-auto-generate-best-practices/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: web-auto-generate-best-practices
+description: "Format web automation best practices provided by the user into a structured Do's / Don'ts table with Code Examples and save to `.documents-design/web-auto-best-practices.md`. Input can be in any form — prose, bullet points, numbered rules, code examples, or mixed. Use when asked to add best practices, document coding rules, record anti-patterns, update web-auto-best-practices, format automation standards, or anytime the user mentions best practices, coding standards, do's and don'ts, or anti-patterns in a web automation context. Triggers on requests like 'add these best practices', 'update web-auto-best-practices', 'document these rules', 'format best practices', 'add this anti-pattern', 'what we learned should become a best practice'."
+---
+
+# Web Auto Generate Best Practices
+
+This skill maintains the project's central best practices file — the shared reference that every coding agent and human contributor consults when writing web automation tests. Good best practices are specific, actionable, and grounded in real project experience. Vague advice ("write clean code") has no place here; concrete guidance ("wrap assertions in `subExpect()` for Allure reporting") does.
+
+The file has three sections that serve different purposes:
+- **Do's** table — recommended patterns with reasons
+- **Don'ts** table — anti-patterns with explanations of the harm they cause
+- **Code Examples** — wrong/correct code pairs for practices that are hard to express in a single table row
+
+## Output
+
+```
+.documents-design/web-auto-best-practices.md
+```
+
+If the file already exists, **merge** new items into the existing sections — never overwrite what's already documented.
+
+## Relationship to Other Documentation Files
+
+These three files work together but serve distinct roles. Understanding the boundaries prevents duplication:
+
+| File | Role | What belongs here |
+|------|------|-------------------|
+| `web-auto-project-blueprint.md` | *What* the project is | Architecture, tech stack, directory structure, naming conventions |
+| `web-auto-best-practices.md` (this output) | *How* to write good code | Rules, standards, anti-patterns — things that apply across many tickets |
+| `web-auto-instructions.md` | *Concrete patterns* | Copy-paste-ready code templates extracted from the codebase |
+
+A common duplication trap: a best practice says "use `waitForSpinnerLoading()` after actions that trigger loading" (rule), while instructions.md has the actual code template showing how to call it (pattern). Both are needed — the rule explains *why*, the template shows *how*. If a new item fits better as a code template in `web-auto-instructions.md`, suggest that to the user instead of adding it here.
+
+## Output Format
+
+```markdown
+# Best Practices
+
+## Do's
+
+| Practice | Reason |
+|----------|--------|
+| [what to do] | [why it matters] |
+
+## Don'ts
+
+| Anti-Pattern | Why to Avoid |
+|--------------|--------------|
+| [what NOT to do] | [why it causes problems] |
+
+## Code Examples
+
+### [Descriptive Title] — Correct Pattern
+
+\```typescript
+// Wrong — [brief explanation of the problem]
+[wrong code]
+
+// Correct — [brief explanation of the fix]
+[correct code]
+\```
+```
+
+## Workflow
+
+### Step 1: Parse the Input
+
+Accept best practices from the user in any format — prose, bullet points, numbered rules, code examples, or a mix.
+
+### Step 2: Classify Each Item
+
+For each extracted item, determine its type:
+
+| Input signals | Classify as |
+|---------------|-------------|
+| "always", "prefer", "use", "make sure", "should" | Do |
+| "never", "avoid", "don't", "do not", "forbidden" | Don't |
+| A rule stated positively | Do |
+| A rule stated negatively | Don't |
+| A wrong → correct code pair | Don't (anti-pattern row) + Do (correct approach row) + Code Example |
+| A nuanced pattern that needs code to explain | Do or Don't row + Code Example |
+
+When an item contains both a wrong and a correct approach, create entries in all three sections: a Don't row for the anti-pattern, a Do row for the correct approach, and a Code Example with the side-by-side comparison. The table rows give the quick reference; the code example shows exactly what the code looks like. This triple-entry pattern is what makes the file genuinely useful — the tables are scannable, and the examples are copy-pasteable.
+
+### Step 3: Read Existing File and Deduplicate
+
+Read the existing best practices file (if it exists). For each new item, check whether it's already covered:
+
+| Check | Action |
+|-------|--------|
+| **Exact match** — same practice already exists in a table row | Skip it |
+| **Semantic match** — different wording but same underlying guidance (e.g., "avoid hardcoded waits" vs "don't use `browser.pause()` with fixed delays") | Skip it |
+| **Partial overlap** — related guidance exists but the new item adds a meaningful distinction (e.g., existing says "use explicit waits" but new item specifies "use `waitForSpinnerLoading` specifically for async dropdown content") | Keep the new item — it's a valuable specialization |
+| **Contradicts existing** — new item conflicts with something already documented | Flag it to the user with both versions and ask which is correct |
+
+Also read `web-auto-instructions.md` if it exists. If the new item is essentially a code template (not a rule), suggest adding it to instructions instead.
+
+### Step 4: Write the Output
+
+Apply new items to the appropriate sections of the file:
+
+**For Do's and Don'ts table rows:**
+- **Practice / Anti-Pattern column**: one concise sentence — what to do or not do. Inline code with backticks is encouraged for specificity (e.g., "Use `waitForDisplayed(toast)` before asserting toast text")
+- **Reason / Why to Avoid column**: one sentence — why it matters, grounded in the real consequence (e.g., "Toasts appear asynchronously — asserting without waiting causes flaky failures")
+
+**For Code Examples:**
+- Use a descriptive heading that names the pattern (e.g., "### Toast Assertion — Correct Pattern")
+- Show the wrong approach first with a `// Wrong —` comment explaining the problem
+- Show the correct approach with a `// Correct —` comment explaining the fix
+- Keep examples minimal — just enough code to illustrate the point, not a full page object
+
+**Placement**: add new rows near related existing entries rather than appending to the bottom. Group similar practices together — a new selector-related Don't should sit near other selector Don'ts.
+
+### Step 5: Confirm
+
+Show the user what was added:
+- List each new Do row
+- List each new Don't row
+- List each new Code Example title
+- Note any items that were skipped (already documented) or flagged (contradictions)
+
+Confirm the file path where changes were saved.

package/kits/shared/skills/web-auto-generate-instructions/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: web-auto-generate-instructions
+description: "Analyze a web automation test codebase and generate a comprehensive AI coding guide saved to `.documents-design/web-auto-instructions.md`. Works with any language (TypeScript, JavaScript, Python, Java, etc.) and any framework (Playwright, Cypress, WebdriverIO, Selenium, Robot Framework, etc.). Use this skill whenever someone asks to create a web automation coding guide, generate test instructions, analyze automation patterns, produce AI-ready test documentation, update/regenerate existing test instructions, extract coding patterns from an automation codebase, or document how tests are written in a project. Also use it when someone wants to onboard an AI agent to an existing test suite, prepare a project for AI-assisted test writing, or says things like 'how do tests work in this project' and wants a written guide. Triggers on requests like 'create web automation instructions', 'generate automation coding guide', 'analyze test codebase and write instructions', 'document our test patterns', 'extract test conventions', 'web-auto-generate-instructions'."
+---
+
+# Web Auto Generate Instructions
+
+Analyze the existing web automation test codebase and generate a comprehensive coding guide that enables an AI agent to write tests that strictly follow the project's established conventions and patterns.
+
+The output file is the practical coding companion — real code pulled from the codebase, not rules or architecture. An AI agent reading this file should be able to write a new test that fits seamlessly into the existing suite without ever looking at the original test files.
+
+## Output
+
+Save the generated guide to:
+
+```
+.documents-design/web-auto-instructions.md
+```
+
+If the file already exists, update it — preserving any sections that are still accurate and replacing sections that need updating.
+
+## Workflow
+
+### Step 1: Read Existing Project Documentation
+
+Read all available project documentation before touching the codebase. This step exists because the three `.documents-design/web-auto-*.md` files form a coordinated documentation system — each file has a distinct role, and the instructions file must not duplicate content from its siblings.
+
+**Web automation specific docs (highest priority — read these first):**
+
+| File | What it Contains |
+|------|-----------------|
+| `.documents-design/web-auto-project-blueprint.md` | Project overview, architecture, tech stack, directory structure, and high-level conventions for the automation project |
+| `.documents-design/web-auto-best-practices.md` | Established best practices, coding standards, and rules for the automation project |
+
+**General project standards (read if present):**
+
+| Location | Purpose |
+|----------|---------|
+| `.github/copilot-instructions.md` | Copilot instructions |
+| `project-blueprint.md`, `.github/project-blueprint.md`, `.cursor/rules/project-blueprint.mdc` | General project blueprint |
+| `.cursor/rules/*.md`, `.cursor/rules/*.mdc`, `.cursorrules` | Cursor rules |
+| `CONTRIBUTING.md`, `AGENTS.md`, `.editorconfig` | Other conventions |
+
+**After reading, build a "covered topics" list** — a concrete list of every topic already documented (e.g., "selector strategy", "file naming convention", "directory structure"). Check each topic you write in the output against this list. If it is already covered, replace the content with a cross-reference.
+
+**If no documentation files exist yet** (first-time run on a new project), there is nothing to deduplicate — proceed to Step 2 and produce the fullest possible guide. Note in Step 5 that the blueprint and best practices files are missing and recommend generating them.
+
+**The three `.documents-design/web-auto-*.md` files serve distinct roles:**
+
+| File | Role |
+|------|------|
+| `web-auto-project-blueprint.md` | *What* the project is — architecture, structure, tech choices |
+| `web-auto-best-practices.md` | *How* to write good code — rules, standards, anti-patterns |
+| `web-auto-instructions.md` (output) | *Concrete patterns from the actual codebase* — copy-paste-ready code examples, selectors, templates, and checklists extracted from existing tests |
+
+### Step 2: Detect Framework & Analyze Structure
+
+**2.1 — Detect the test framework** using the signals in [references/analysis-guide.md](references/analysis-guide.md).
+
+Read the framework configuration file to extract:
+- Base URL, timeouts, retries, browser settings
+- Test directory paths and spec patterns
+- Reporter configuration
+- Environment-specific settings
+
+**2.2 — Map the test directory structure.** Document the actual layout found in the project:
+```
+Typical structures to look for:
+├── e2e/ or tests/ or test/ or src/
+│   ├── pages/ or pageObjects/ or page-objects/     → Page Object classes
+│   ├── fixtures/ or data/ or testdata/              → Test data
+│   ├── helpers/ or utils/ or support/               → Shared utilities
+│   ├── specs/ or features/ or __tests__/            → Test specs
+│   └── setup/ or support/ or conftest               → Setup/teardown
+```
+
+Not every project follows this shape. If the structure is non-standard (flat layout, monorepo with multiple test roots, or a custom convention), document what actually exists rather than forcing it into a conventional shape. The goal is accuracy, not conformance to a template.
+
+**2.3 — Identify shared utilities:**
+- Base class / page base fixture
+- Custom commands or helper methods
+- API helpers for test data setup/teardown
+- Authentication utilities
+- Environment configuration helpers
+
+For detailed framework-specific analysis guidance, see [references/analysis-guide.md](references/analysis-guide.md).
+
+### Step 3: Analyze Test Patterns
+
+Read **5–8 test files** and **3–5 Page Object files** across different features. Extract the patterns listed below. For detailed checklists, see [references/analysis-guide.md](references/analysis-guide.md).
+
+**Sampling strategy:** diversity matters more than volume. Pick files from different feature areas and different authors (check git blame if available) to capture the project's conventions rather than one developer's style. Prioritize files that look well-maintained (recent commits, consistent formatting) as pattern sources — they are more likely to reflect the team's current standards.
+
+**If the codebase has fewer files than the targets above** (e.g., a young project with only 2–3 tests), read everything available. The output will naturally be shorter, and that is fine — document what exists and note the limited sample in Step 5.
+
+**If no Page Objects exist** (some projects use plain helper functions, or no abstraction at all), skip Section 1 in the output and document whatever abstraction layer is used instead (e.g., helper modules, custom commands, or direct selectors in test files).
+
+**3.1 — Page Object patterns:**
+- Class structure, naming, and export conventions
+- How selectors are defined (getters, constants, factory methods)
+- Async rules (e.g., which getters must/must-not be async)
+- Action and verification method patterns
+- Step wrapper usage (allure.step, custom step/expect wrappers)
+
+**3.2 — Test file patterns:**
+- Import structure and ordering
+- `describe` / test block organization and naming
+- Setup and teardown hooks — what belongs where
+- Assertion library and style
+- Step organization ownership rules (which page object owns which steps)
+- Tag/annotation conventions
+
+**3.3 — Test data patterns:**
+- Data file structure and location
+- Dynamic/unique value generation utilities used in the project
+- Type definitions or data model shapes used for test data
+- Pre-test cleanup convention (before hook vs inline)
+
+**3.4 — API/backend helper patterns:**
+- Auth pattern (how credentials or tokens are obtained for programmatic API calls)
+- Data seeding and teardown patterns (REST, GraphQL, DB, or other)
+- Any project-specific rules or gotchas for API helpers
+
+**3.5 — Cross-cutting patterns:**
+- Login and navigation flows
+- Common UI interactions (spinners, toasts, modals, search)
+
+> If pitfalls or anti-patterns are found during analysis, add them to `.documents-design/web-auto-best-practices.md` — not to the instructions file. The instructions file documents *what the codebase does*; the best practices file documents *what it should do*.
+
+### Step 4: Generate the Coding Guide
+
+Create `.documents-design/web-auto-instructions.md` using the structure from [templates/web-auto-instructions.template.md](templates/web-auto-instructions.template.md).
+
+**Critical rules:**
+1. **No duplication** — If a topic is already covered in `web-auto-project-blueprint.md`, `web-auto-best-practices.md`, or any other standards file read in Step 1, do NOT repeat it. Add a cross-reference instead (e.g., _"See `web-auto-best-practices.md` for selector rules."_). **Exception: Section 6 must always be self-contained** — fill in actual path patterns and commands directly in the checklist items, even if the same information appears in the blueprint. The reason is that Section 6 is meant for quick reference when starting a new test — the reader should not need to open another file.
+2. **Evidence-based** — Include only patterns and conventions actually observed in the codebase. If you saw it in the code, include it. If you didn't, leave it out — inventing conventions that nobody follows is worse than having a gap.
+3. **Real examples only** — Extract actual code from existing tests; no placeholder pseudocode. Change variable names to be generic (e.g., `featureName` instead of `specificProduct`) so examples are reusable, but keep the structure and style identical to the source.
+4. **Immediately usable** — Every code block must be copy-paste ready. A developer should be able to drop a template into a new file and start editing it without fixing syntax or imports.
+5. **Complete coverage** — Sample across multiple feature areas, not just one.
+6. **Flag discrepancies** — If observed codebase patterns conflict with documented standards, add the discrepancy to `web-auto-best-practices.md` with a note like _"Observed in codebase but conflicts with documented standard — needs team alignment."_
+7. **Flag gaps** — If the codebase lacks patterns for something important (e.g., no cleanup, no test data separation), note it as a recommendation rather than inventing a convention.
+
+**Which sections to include:**
+
+| Section | Include When | Decision Signal |
+|---------|-------------|-----------------|
+| 1. Page Object Patterns | Always (even if brief) | Project has page objects or equivalent abstraction |
+| 2. Test Structure & Patterns | Always (even if brief) | Tests exist |
+| 3. Test Data Management | Dedicated data files or fixture modules exist | Look for `fixtures/`, `data/`, factory files, or shared constants files |
+| 4. API & Backend Helpers | Programmatic API helpers exist for test data setup | Look for REST/GraphQL client wrappers, seed scripts, or helper modules that call backend APIs |
+| 5. Common Workflow Patterns | Recurring multi-step patterns appear across 3+ test files | Login flows, search-select patterns, modal confirmations, form submissions |
+| 6. Implementation Checklist | Always | Required for every project |
+
+> Framework, directory structure, file naming, selector strategy, anti-patterns, and coding rules belong in `.documents-design/web-auto-project-blueprint.md` or `.documents-design/web-auto-best-practices.md`. Do not create sections for them here. If pitfalls or anti-patterns are discovered during codebase analysis, add them to `web-auto-best-practices.md` instead.
+
+**Section 6 (Implementation Checklist) is the most important section.** Fill in the actual file path patterns and commands so the checklist is immediately usable as a quick reference when starting a new test case — without needing to read the full document.
+
+### Step 5: Verify and Present
+
+1. Confirm the file was saved to `.documents-design/web-auto-instructions.md`
+2. Present a structured summary:
+
+```
+## Summary
+
+- **Output**: `.documents-design/web-auto-instructions.md`
+- **Framework**: [detected framework] ([language])
+- **Files analyzed**: [N] test files, [N] page objects, [N] helpers
+- **Sections generated**: [list of sections included]
+- **Sections omitted**: [list with reason, e.g., "Section 4 — no API helpers found"]
+- **Discrepancies flagged**: [count, with brief descriptions]
+- **Gaps noted**: [count, with brief descriptions]
+- **Missing companion docs**: [list any .documents-design files that don't exist yet]
+```
+
+3. Ask: "Does this guide accurately capture the project's testing patterns and conventions?" If the user identifies inaccuracies, update the affected sections and re-confirm.
+
+## Edge Cases & Error Recovery
+
+| Situation | What to Do |
+|-----------|-----------|
+| **Very few test files** (< 3) | Read all available tests. Produce a shorter guide. Note limited sample in summary and recommend revisiting after more tests are written. |
+| **No page objects / no abstraction layer** | Skip Section 1. Document how selectors and actions are organized in the test files directly (Section 2). |
+| **Mixed patterns** (e.g., some tests use POM, others don't) | Document the dominant pattern as the primary convention. Note the alternative in a "Variations" subsection with a cross-reference. |
+| **Non-standard directory structure** | Document the actual structure as-is. Do not force it into conventional categories. |
+| **Existing instructions file is outdated** | Compare existing sections against current codebase. Update sections where patterns have changed, preserve sections that are still accurate. Note what changed in the summary. |
+| **No companion docs exist** (blueprint, best-practices) | Produce the fullest guide possible (no deduplication needed). Recommend generating the missing files in the summary. |
+| **Codebase contradicts documented standards** | Flag the discrepancy in `web-auto-best-practices.md`. In the instructions file, document the actual codebase pattern (because other tests should match what exists, not what was planned). |
+
+## Important Rules
+
+- **Respect existing patterns** — Even if a pattern isn't globally considered best practice, if the project uses it consistently, document it as the convention to follow. Consistency within a codebase matters more than theoretical correctness — an AI agent writing a test that follows a "better" pattern but doesn't match the rest of the suite creates more problems than it solves.
+- **Be comprehensive** — Sample across multiple feature areas so the guide enables AI to write tests for any feature, not just the ones analyzed.
+- **Accuracy over completeness** — A shorter guide with accurate, verified patterns is better than a longer guide that includes speculation. Every code block should be traceable to a real file in the codebase.
+- **Keep the file maintainable** — Write in a way that makes future updates easy. Use clear section boundaries so individual sections can be updated without re-reading the entire document.
+
+## Additional Resources
+
+- Detailed codebase analysis guidance: [references/analysis-guide.md](references/analysis-guide.md)
+- Output template structure: [templates/web-auto-instructions.template.md](templates/web-auto-instructions.template.md)

package/kits/shared/skills/web-auto-generate-instructions/evals/evals.json

@@ -0,0 +1,23 @@
+{
+  "skill_name": "web-auto-generate-instructions",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I just joined a team that has a Playwright TypeScript automation project with about 20 test files, page objects, and API helpers. I need to generate a coding guide so our AI agent can write tests that match our existing patterns. The project has .documents-design/web-auto-project-blueprint.md and web-auto-best-practices.md already. Can you analyze the codebase and create the instructions file?",
+      "expected_output": "A .documents-design/web-auto-instructions.md file that: (1) does NOT duplicate content from the existing blueprint/best-practices files but cross-references them, (2) contains real code extracted from the codebase in all sections, (3) has a self-contained Section 6 Implementation Checklist with actual paths and commands, (4) includes sections 1-5 based on what exists in the codebase, (5) presents a structured summary at the end",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "We have a small Cypress project — only 3 test files and no page objects, just helper functions. No .documents-design files exist yet. Can you create the web automation instructions for it?",
+      "expected_output": "A .documents-design/web-auto-instructions.md file that: (1) handles the edge case of no page objects gracefully (skips or adapts Section 1), (2) reads all 3 available test files since there are fewer than the 5-8 target, (3) produces a complete guide without duplication concerns since no companion docs exist, (4) notes the limited sample and missing companion docs in the summary, (5) recommends generating blueprint and best-practices files",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Our web-auto-instructions.md file is outdated — we refactored our page objects last month and added a new API helper layer. Can you regenerate it? The blueprint and best practices files are up to date.",
+      "expected_output": "An updated .documents-design/web-auto-instructions.md that: (1) compares existing sections against the current codebase, (2) updates sections where patterns have changed (page objects, API helpers), (3) preserves sections that are still accurate, (4) notes what changed in the summary, (5) flags any discrepancies between the codebase and documented standards to the best-practices file",
+      "files": []
+    }
+  ]
+}