evizi-kit 1.0.0

package/kits/shared/skills/web-auto-ticket-playbook/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: web-auto-ticket-playbook
+description: Create a comprehensive implementation playbook from a ticket design document. Reads ticket-design.md, reads project/feature coding instructions, searches the codebase for reusable Page Objects and utilities, and generates a step-by-step implementation plan with tasks, dependencies, and reference patterns. Use this skill whenever someone asks to create a ticket playbook, generate an implementation plan, prepare coding tasks, plan implementation work, break down a ticket into tasks, or create a coding guide for a ticket — even casual requests like "plan the work for this ticket" or "what tasks do I need for TKT-001". Triggers on requests like "create playbook for ticket TKT-001", "generate implementation plan for ABC-123", "prepare coding tasks for ticket fe-2026", "break down ticket work", "plan the implementation".
+---
+
+# Web Automation Ticket Playbook
+
+Read a `ticket-design.md` file for a given ticket ID, search the codebase for reusable components, and generate a comprehensive implementation playbook saved as `ticket-playbook.md`.
+
+The playbook is the bridge between design and code. The upstream ticket-design skill maps *what* needs to happen (test steps, selectors, expected results); this skill maps *how* to implement it (which files to create, what patterns to follow, which existing code to build on). The downstream coding skill then executes the playbook task by task. A well-crafted playbook gives the coding agent everything it needs — clear file paths, concrete reference patterns, explicit dependencies — so it can implement without guessing or re-searching.
+
+## 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 the Ticket Design
+
+Search for the ticket design file:
+
+```
+.tickets/{TICKET_ID}/ticket-design.md
+```
+
+**If not found:** Inform the user and stop:
+
+```
+Error: ticket-design.md not found for ticket {TICKET_ID}.
+Run the web-auto-ticket-design skill first to create it.
+```
+
+**If found:** Extract and understand:
+- **Feature / Child Feature** from the Ticket Information section
+- **Related Feature** (if any) — often shares components worth reusing
+- **Test Case IDs** from the section headers
+- **Test Steps** including actions, elements, selectors, and expected results
+- **Existing code references** — steps using Format 1 or Format 2 already point to specific Page Objects and methods. Catalog these — they tell you which files the coding agent will need to import
+- **New implementations needed** — steps marked with "Note: New element/action - needs to be implemented" (Format 3) or "Note: New API action - needs to be implemented" (Format 4). These are the items that need new tasks in the playbook
+- **Selectors** — both resolved selectors and any remaining `<-- Update selector for this element -->` placeholders
+
+### Step 2: Read Project and Feature Instructions
+
+Read the coding instructions that define mandatory conventions. These files shape *how* the playbook structures its tasks — file paths, class names, method signatures, and coding patterns all come from here.
+
+1. `.documents-design/web-auto-project-blueprint.md` — project structure, framework, tech stack, directory layout, file naming conventions
+2. `.documents-design/web-auto-instructions.md` — concrete coding patterns with copy-paste templates from the actual codebase
+3. `.documents-design/web-auto-best-practices.md` — coding standards, anti-patterns to avoid, best practices
+
+From these files, extract and note:
+- **Directory structure** — where Page Objects, test scripts, fixtures, and utilities live
+- **File naming conventions** — how files should be named (e.g., `feature.page.ts`, `feature.spec.ts`)
+- **Page Object patterns** — base class to extend, how to define elements, how to write action methods
+- **Test script patterns** — test structure, hooks, setup/teardown, assertion style
+- **Test data patterns** — how test data is organized (fixtures, factories, inline, environment variables)
+- **Import conventions** — barrel exports, relative vs. absolute paths
+- **Anti-patterns** — things the coding agent must avoid
+
+**If no instruction files are found:** Proceed without them, but note in the playbook output that no project instructions were available. The coding agent should then infer conventions from existing codebase patterns.
+
+### Step 3: Search and Catalog Existing Components
+
+The ticket design already identified which Page Objects, methods, and elements exist for individual test steps. This step goes further — search for the *infrastructure* the coding agent will need: utilities, fixtures, test data helpers, configuration, and patterns for creating new components.
+
+Complete all analysis internally — do not output search results to the user.
+
+**3.1 — Verify and Expand Page Object Knowledge**
+
+The ticket design referenced specific Page Objects. Read those files to understand their full structure:
+
+| Search Target | Why |
+|---------------|-----|
+| Feature Page Objects referenced in the design | Understand imports, base class, existing methods — the coding agent will extend these |
+| Related Feature Page Objects | May share patterns or elements worth reusing |
+| Base / Shared Page Objects | Understand the base class API — methods the coding agent can call or override |
+
+For Page Objects that need new methods (from Format 3/4 steps), identify the exact insertion point — which file, after which existing method.
+
+**3.2 — Utilities and Helpers**
+
+Search for reusable utilities the ticket design wouldn't have covered:
+
+| Search Target | Patterns |
+|---------------|----------|
+| Assertion helpers | `expect`, `verify`, `assert`, `waitFor`, custom matchers |
+| Navigation utilities | `goto`, `navigate`, `waitForNavigation`, `waitForURL` |
+| Data generation | `faker`, `generate`, `random`, `factory`, `build` |
+| File handling | `upload`, `download`, `readFile`, `writeFile` |
+| API clients | `ApiClient`, `request`, `fetch` — for Format 4 (new API) tasks |
+| Environment / Config | `env`, `config`, `baseURL`, `credentials` |
+
+**3.3 — Test Data and Fixtures**
+
+Search for existing test data patterns — how the project handles test data determines how the playbook structures data-related tasks:
+
+| Search Target | Patterns |
+|---------------|----------|
+| Fixture files | `fixture`, `.fixture.ts`, `.data.ts`, `testData` |
+| Factories | `factory`, `create`, `build`, `generate` |
+| Seed data | `seed`, `mock`, `stub` |
+| Environment data | `.env`, `config`, credentials handling |
+
+**3.4 — Reference Pattern Candidates**
+
+For each type of new component the ticket needs (new Page Object method, new test script, new API helper), find the best existing example to serve as a reference pattern. A good reference pattern:
+- Is in the same feature area (or a closely related one)
+- Uses the same base classes and conventions
+- Is similar in complexity to what needs to be built
+- Is a complete, working implementation (not a stub)
+
+**3.5 — Build Internal Catalog**
+
+Organize findings into numbered tables (the numbers become dependency references in tasks):
+
+```
+Existing Components:
+| # | Component | Type | Path | Key Methods/Elements |
+
+New Components Needed:
+| # | Component | Type | Planned Path | Purpose | Best Reference |
+
+Utilities Available:
+| # | Utility | Path | Relevant Methods |
+```
+
+### Step 4: Plan Implementation Tasks
+
+This is where the playbook's value is created. Plan all tasks before generating the output. The goal: produce a task list that the coding agent can execute sequentially without needing to make architectural decisions.
+
+#### 4.1 — Categorize Work
+
+Group everything that needs to happen into categories. This ordering also defines the dependency flow:
+
+| Order | Category | Examples |
+|-------|----------|----------|
+| 1 | Test Data & Fixtures | New fixture files, test data constants, environment setup |
+| 2 | API Helpers | New API client methods for CRUD operations (from Format 4 steps) |
+| 3 | Page Object Updates | New methods or elements added to *existing* Page Objects |
+| 4 | New Page Objects | Brand new Page Object classes |
+| 5 | Test Scripts | The actual test spec files |
+
+#### 4.2 — Determine Task Granularity
+
+Each task should represent a single coherent unit of work in one file. Use this guide:
+
+- **One task per file** as the default — if a task touches multiple files, split it
+- **Group related small changes** — adding 2-3 related methods to the same Page Object is one task, not three
+- **Separate Page Object creation from test script creation** — even if they're for the same test case, they're different tasks with a dependency
+- **One test script task per test case** — unless test cases share significant setup code, in which case shared setup can be its own task
+
+#### 4.3 — Write Task Details
+
+For each task, prepare:
+
+- **Dependencies** — which task numbers must complete first. Think about: Does this task import from a file another task creates? Does it use test data another task defines?
+- **Guidance** — the most important field. This tells the coding agent *what* to do and *how*, referencing conventions from the instruction files. Good guidance is specific and actionable (see examples in the template). Avoid vague guidance like "implement the page object" — instead say "Add a `clickSubmitButton()` method to `LoginPage` that clicks the submit button element and waits for navigation, following the action method pattern in the Reference Pattern."
+- **File(s) to Modify** — exact file paths (for existing files) or planned paths following naming conventions (for new files)
+- **Key Selector(s)** — selectors from the ticket design that this task uses. Include both resolved selectors and any remaining placeholders
+- **Reference Pattern** — a specific existing file + class/method that the coding agent should use as a model. Not just "look at LoginPage" but "see `LoginPage.fillUsername()` in `pages/login.page.ts` for the method pattern"
+
+#### 4.4 — Validate the Dependency Graph
+
+Before generating output:
+1. Verify all dependencies reference valid task numbers
+2. Confirm no circular dependencies exist
+3. Check that dependency order follows the category order (data → API → Page Objects → tests)
+4. Ensure every task that imports from a new file depends on the task that creates that file
+
+### Step 5: Generate and Save the Playbook
+
+Generate the playbook following the template at [templates/ticket-playbook.template.md](templates/ticket-playbook.template.md).
+
+Save to the same directory as the ticket design:
+
+```
+.tickets/{TICKET_ID}/ticket-playbook.md
+```
+
+### Step 6: Summary
+
+Display the result:
+
+```
+Ticket playbook created for ticket {TICKET_ID}.
+
+Created:
+- .tickets/{TICKET_ID}/ticket-playbook.md
+
+Summary:
+- Instructions used: [file path(s)]
+- Total implementation tasks: {count}
+- Existing components reused: {count}
+- New components to create: {count}
+```
+
+## Guiding Principles
+
+These explain the reasoning behind how the skill works — understanding them helps handle edge cases not explicitly covered above.
+
+- **The playbook serves the coding agent** — every decision should make the coding agent's job easier. The coding agent reads the playbook and executes tasks sequentially. It shouldn't need to search the codebase itself, make architectural decisions, or guess file paths. If the coding agent needs to figure something out on its own, the playbook failed to communicate it.
+
+- **Leverage the ticket design's work** — the ticket design already searched for Page Objects, elements, and actions. Don't redo that search from scratch. Instead, build on it: read the referenced files to understand their full API, then search for the additional things the design didn't cover (utilities, fixtures, data patterns, reference patterns for new components).
+
+- **Explain the "what" and "how" in Guidance** — vague guidance like "implement the test" creates ambiguity. Specific guidance like "Create a test that navigates to the login page, fills credentials using `LoginPage.fillCredentials()`, submits the form, and verifies the dashboard loads using `DashboardPage.isLoaded()`" gives the coding agent a clear implementation path. Reference the instruction file conventions when relevant.
+
+- **Reference patterns are concrete pointers** — "see `pages/login.page.ts`" is not a reference pattern. "`LoginPage.fillUsername()` in `pages/login.page.ts:42` — follow this pattern for the method signature, element access, and wait strategy" is a reference pattern. The coding agent should be able to open the file, find the exact code, and replicate the pattern.
+
+- **Prioritize reuse because it saves time and ensures consistency** — every existing method the playbook references is one fewer method the coding agent has to write, test, and debug. It also means the new code follows established patterns automatically. When in doubt, search one more time before concluding something needs to be built from scratch.
+
+- **Keep analysis internal** — the user sees only the final playbook and summary. Search results, catalogs, and planning tables are working artifacts that would clutter the output without adding value.
+
+- **Handle missing instructions gracefully** — if instruction files don't exist, the playbook can still be generated. The coding agent should then infer conventions from the reference patterns provided in each task. Note the gap so the user knows.
+
+- **File creation failure** — report the error and ask how to proceed.

package/kits/shared/skills/web-auto-ticket-playbook/evals/evals.json

@@ -0,0 +1,23 @@
+{
+  "skill_name": "web-auto-ticket-playbook",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Create a playbook for ticket fe-3000",
+      "expected_output": "A ticket-playbook.md with Pre-Implementation Analysis, Component Mapping, and Implementation Checklist with properly ordered tasks, dependencies, guidance, selectors, and reference patterns",
+      "files": [".tickets/fe-3000/ticket-design.md"]
+    },
+    {
+      "id": 2,
+      "prompt": "I've got the design ready for fe-3001, now plan out the implementation tasks",
+      "expected_output": "Skill triggers on casual phrasing and produces a well-structured playbook with tasks categorized by type (data, API, Page Objects, tests) and valid dependency graph",
+      "files": [".tickets/fe-3001/ticket-design.md"]
+    },
+    {
+      "id": 3,
+      "prompt": "Generate implementation plan for ticket XYZ-999",
+      "expected_output": "Error message indicating ticket-design.md not found, suggesting to run web-auto-ticket-design skill first",
+      "files": []
+    }
+  ]
+}

package/kits/shared/skills/web-auto-ticket-playbook/templates/ticket-playbook.template.md

@@ -0,0 +1,148 @@
+# Ticket Playbook Template
+
+Use this template as the output structure for `ticket-playbook.md`.
+
+## Output Structure
+
+```markdown
+# Ticket Playbook
+
+## Ticket Information
+- Ticket ID: [ticket-id]
+- Feature: [main-feature - child-feature]
+
+## Pre-Implementation Analysis
+
+### Instructions Used
+- Project Blueprint: [path or "Not available"]
+- Coding Instructions: [path or "Not available"]
+- Best Practices: [path or "Not available"]
+
+### Component Mapping
+
+#### Existing Components (Reusable)
+| # | Component | Type | Path | Key Methods/Elements |
+|---|-----------|------|------|----------------------|
+| 1 | [Name] | Page Object / Utility / Fixture / API Helper | [path] | [methods and elements the coding agent will use] |
+
+#### New Components (To Create)
+| # | Component | Type | Planned Path | Purpose | Reference |
+|---|-----------|------|--------------|---------|-----------|
+| 1 | [Name] | Page Object / Utility / Fixture / API Helper | [path following naming conventions] | [what it provides] | [existing file to use as model] |
+
+---
+
+## Implementation Checklist
+
+### [Category Name]
+
+#### Task [N]: [Descriptive Task Title]
+- **Dependencies**: [Task numbers or "None"]
+- **Guidance**: [Specific, actionable instructions — what to do and how, referencing conventions]
+- **File(s) to Modify**: [exact file path(s) — existing or planned]
+- **Key Selector(s)**: [selectors from ticket-design, or "N/A" for non-UI tasks]
+- **Reference Pattern**: [file:line — specific method/class to replicate]
+
+#### Task [N+1]: [Descriptive Task Title]
+...
+```
+
+## Category Ordering
+
+Tasks are organized into categories. This ordering also defines the dependency flow — earlier categories complete before later ones:
+
+| Order | Category | What Goes Here |
+|-------|----------|----------------|
+| 1 | Test Data & Fixtures | New fixture files, test data constants, environment setup |
+| 2 | API Helpers | New API client methods for CRUD operations |
+| 3 | Page Object Updates | New methods or elements added to existing Page Objects |
+| 4 | New Page Objects | Brand new Page Object classes |
+| 5 | Test Scripts | The actual test specification files |
+
+Not all categories will be present in every playbook — include only the categories that have tasks.
+
+## Field Descriptions
+
+| Field | Good Example | Bad Example | Why |
+|-------|-------------|-------------|-----|
+| **Dependencies** | `Task 1, Task 3` or `None` | `Page Object task` | Must reference specific task numbers so the coding agent knows the exact order |
+| **Guidance** | `Add a clickSubmitButton() method to LoginPage that clicks the submit button and waits for navigation. Follow the async action method pattern — see Reference Pattern. Use the selector from Key Selector(s).` | `Implement the page object` | The coding agent shouldn't have to figure out what "implement" means. Be specific about the method name, behavior, and pattern to follow |
+| **File(s) to Modify** | `tests/pages/login.page.ts` | `the login page object` | Must be an exact file path the coding agent can open |
+| **Key Selector(s)** | `[data-testid="submit-btn"]` or `N/A` | `the submit button` | Must be the actual selector string from ticket-design, or N/A for non-UI tasks (API helpers, fixtures) |
+| **Reference Pattern** | `LoginPage.fillUsername() in tests/pages/login.page.ts — follow the method signature, element access via this.page.getByTestId(), and await pattern` | `see LoginPage` | Must point to a specific method/class with enough detail that the coding agent knows exactly what to replicate |
+
+## Dependency Rules
+
+1. Test Data & Fixture tasks have no dependencies (they come first)
+2. API Helper tasks may depend on fixture tasks (if they use test data)
+3. Page Object tasks may depend on fixture or API tasks (if methods need imported types)
+4. Test Script tasks depend on the Page Object and fixture tasks they import from
+5. All dependencies must reference valid task numbers — no circular references
+6. Every task that imports from a file created by another task must list that task as a dependency
+
+## Example
+
+A complete playbook for a login feature ticket:
+
+```markdown
+# Ticket Playbook
+
+## Ticket Information
+- Ticket ID: fe-2026
+- Feature: Authentication - Login
+
+## Pre-Implementation Analysis
+
+### Instructions Used
+- Project Blueprint: .documents-design/web-auto-project-blueprint.md
+- Coding Instructions: .documents-design/web-auto-instructions.md
+- Best Practices: .documents-design/web-auto-best-practices.md
+
+### Component Mapping
+
+#### Existing Components (Reusable)
+| # | Component | Type | Path | Key Methods/Elements |
+|---|-----------|------|------|----------------------|
+| 1 | LoginPage | Page Object | tests/pages/login.page.ts | goto(), fillUsername(), fillPassword(), usernameInput, passwordInput |
+| 2 | DashboardPage | Page Object | tests/pages/dashboard.page.ts | isLoaded(), welcomeMessage |
+| 3 | UserApi | API Helper | tests/api/user.api.ts | create(), delete() |
+| 4 | test-helpers | Utility | tests/utils/test-helpers.ts | generateEmail(), waitForNavigation() |
+
+#### New Components (To Create)
+| # | Component | Type | Planned Path | Purpose | Reference |
+|---|-----------|------|--------------|---------|-----------|
+| 1 | LoginPage.clickSubmitButton() | Page Object Method | tests/pages/login.page.ts | Click submit and wait for navigation | LoginPage.fillUsername() |
+| 2 | LoginPage.errorMessage | Page Object Element | tests/pages/login.page.ts | Error message element for validation tests | LoginPage.usernameInput |
+| 3 | login.spec.ts | Test Script | tests/specs/auth/login.spec.ts | Test cases TC042, TC043 | tests/specs/auth/register.spec.ts |
+
+---
+
+## Implementation Checklist
+
+### Page Object Updates
+
+#### Task 1: Add submit button and error message to LoginPage
+- **Dependencies**: None
+- **Guidance**: Add two new members to LoginPage: (1) a `clickSubmitButton()` async method that clicks `[data-testid="login-submit"]` and waits for navigation using `this.page.waitForURL('**/dashboard')`, and (2) an `errorMessage` getter that returns `this.page.getByTestId('login-error')`. Follow the existing element getter pattern in LoginPage for the getter, and the async action pattern from `fillUsername()` for the method.
+- **File(s) to Modify**: tests/pages/login.page.ts
+- **Key Selector(s)**: `[data-testid="login-submit"]`, `[data-testid="login-error"]`
+- **Reference Pattern**: `LoginPage.fillUsername()` in tests/pages/login.page.ts — follow the method signature (`async fillUsername(value: string)`), element access via `this.page.getByTestId()`, and await pattern
+
+### Test Scripts
+
+#### Task 2: Create login test spec
+- **Dependencies**: Task 1
+- **Guidance**: Create the login test spec with two test cases. TC042: Navigate to login (LoginPage.goto()), fill credentials (fillUsername + fillPassword), click submit (clickSubmitButton), verify dashboard loads (DashboardPage.isLoaded()). TC043: Navigate to login, fill invalid credentials, click submit, verify error message is visible (LoginPage.errorMessage). Use `test.describe` for the suite, `test.beforeEach` for shared navigation, and the UserApi for test data setup in `test.beforeAll`. Follow the test structure pattern from the Reference Pattern.
+- **File(s) to Modify**: tests/specs/auth/login.spec.ts (new file)
+- **Key Selector(s)**: N/A (selectors are encapsulated in Page Objects)
+- **Reference Pattern**: `tests/specs/auth/register.spec.ts` — follow the test structure (describe block, beforeAll/beforeEach hooks, test cases, assertion patterns)
+```
+
+**What this example shows:**
+- Ticket Information and Instructions Used provide context
+- Component Mapping shows what exists and what's new, with references for new items
+- Tasks are ordered by category (Page Object Updates before Test Scripts)
+- Task 2 depends on Task 1 (test script imports from updated Page Object)
+- Guidance is specific and actionable — names exact methods, explains behavior, references patterns
+- Reference Pattern points to a specific method/file with what to replicate
+- Key Selectors come from ticket-design; test scripts use N/A since selectors are in Page Objects

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

@@ -0,0 +1,156 @@
+---
+name: web-auto-update-source-instructions
+description: Update project source instruction files based on lessons learned from a completed ticket. Reads lessons-learned.md for a given ticket, extracts recommendations grouped by target document (Project Blueprint, Coding Instructions, Best Practices), deduplicates against existing content, resolves conflicts, then applies updates only to the source instructions that have new, non-redundant recommendations. ALWAYS use this skill when asked to update source instructions from lessons learned, apply lessons to project standards, improve source instruction files after a ticket, feed lessons back into project docs, close the feedback loop for a ticket, or propagate ticket learnings. Triggers on requests like "update source instructions for TKT-001", "apply lessons learned from ABC-123", "update best practices from ticket fe-2026", "feed back lessons from ticket X", "close the loop on ticket Y".
+---
+
+# Web Automation Update Source Instructions
+
+Every completed ticket produces lessons — gaps in the documentation that caused confusion, missing patterns that led to errors, anti-patterns that weren't explicitly warned against. This skill closes the feedback loop by taking those lessons and writing them back into the project's source instruction files, so the next ticket benefits from what was learned.
+
+Without this step, the same mistakes recur: a wrong selector strategy gets re-used because the best practices file never captured the fix, an ambiguous instruction stays ambiguous because nobody updated it, a missing code example stays missing because the lesson was extracted but never applied.
+
+## Input
+
+| 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 before proceeding.
+
+## Workflow
+
+### Step 1: Read the Lessons Learned Document
+
+Read the lessons file at:
+
+```
+.tickets/{TICKET_ID}/lessons-learned.md
+```
+
+If not found, inform the user and stop — without the lessons file there is nothing to apply:
+
+```
+lessons-learned.md not found for ticket {TICKET_ID}.
+Run the web-auto-extract-lessons-learned skill first to create it.
+```
+
+Extract all recommendations from **Section 4 (Recommendations)**. The document uses three priority tables:
+
+- **High Priority** — columns: `#`, `Target Document`, `Instruction Gap / Issue`, `Problem`, `Impact`, `Recommended Action`
+- **Medium Priority** — columns: `#`, `Target Document`, `Recommendation`
+- **Examples Needed** — columns: `#`, `Target Document`, `Topic`, `What Example Would Help`
+
+Each row's `Target Document` value will be one of: `Project Blueprint`, `Coding Instructions`, or `Best Practices`.
+
+### Step 2: Group and Filter Recommendations
+
+Organize recommendations into three groups by their target document:
+
+| Group | Target Document Value | Source Instruction File |
+|-------|-----------------------|------------------------|
+| Project Blueprint | `Project Blueprint` | `.documents-design/web-auto-project-blueprint.md` |
+| Coding Instructions | `Coding Instructions` | `.documents-design/web-auto-instructions.md` |
+| Best Practices | `Best Practices` | `.documents-design/web-auto-best-practices.md` |
+
+Skip empty groups — only proceed with groups that have at least one recommendation.
+
+If no recommendations exist in any group:
+
+```
+No actionable recommendations found in lessons-learned.md for ticket {TICKET_ID}.
+No source instruction files need updating.
+```
+
+### Step 3: Read Target Files and Deduplicate
+
+For each non-empty group, locate and read the corresponding source instruction file.
+
+If a target file is not found:
+- Report it: `Warning: {Document} not found at {path}. Skipping updates for this document.`
+- Skip that group and continue with the others.
+
+**Deduplication is the most important quality gate in this step.** Source instruction files grow with every ticket. If recommendations are applied without checking for existing coverage, these files become bloated with repetitive or contradictory entries — which actually makes future implementations worse.
+
+For each recommendation, check the current file content:
+
+| Check | Action |
+|-------|--------|
+| **Already covered** — the same guidance exists, even in different wording | Drop the recommendation. It adds no value. |
+| **Partially covered** — related guidance exists but misses the specific detail | Reframe as a **clarification** to the existing entry rather than a new addition. |
+| **Contradicts existing content** — the recommendation conflicts with something already documented | Flag it for the user instead of applying it silently. Present both the existing content and the recommendation, and ask which is correct. |
+| **Genuinely new** — nothing in the file addresses this topic | Keep it for application. |
+
+After deduplication, if a group has no remaining recommendations, skip it.
+
+### Step 4: Apply Updates
+
+For each target file with surviving recommendations, apply updates following the document-specific rules below. The general principles apply to all three:
+
+- **Add, don't replace** — append new content to the relevant section. Never delete or rewrite existing entries.
+- **Match the file's voice** — follow the existing formatting, heading levels, table structures, and tone. If the file uses terse one-liners, don't add paragraphs.
+- **Place content near related entries** — new items should sit next to existing items on the same topic, not appended to the bottom of the file.
+- **Keep it concise** — each addition should be the minimum needed to close the gap. One precise sentence or table row beats a paragraph of explanation.
+
+#### 4a — Updating `web-auto-project-blueprint.md`
+
+This file documents the project's architecture — tech stack, directory structure, naming conventions, selector strategy, and test execution commands. It is organized into sections with tables and bullet lists.
+
+| Recommendation Type | How to Apply |
+|--------------------|--------------| 
+| **High Priority** | Add missing patterns, naming conventions, or structural details to the relevant section. If no section fits, add a brief new subsection under the closest parent heading. |
+| **Medium Priority** | Add a clarification or note to the relevant section — typically a new bullet point or table row. |
+| **Examples Needed** | Add a short code snippet or file path example inline within the relevant section, using a fenced code block. |
+
+#### 4b — Updating `web-auto-instructions.md`
+
+This file contains copy-paste-ready code patterns organized into sections: Page Object Patterns, Test Structure & Patterns, Test Data Management, API & Backend Helpers, Common Workflow Patterns, and Implementation Checklist.
+
+| Recommendation Type | How to Apply |
+|--------------------|--------------| 
+| **High Priority** | Add a new pattern block to the relevant section — include both the code example and a one-line description of when to use it. Follow the existing pattern block format in the file. |
+| **Medium Priority** | Add a note, caveat, or variation to an existing pattern block, or add a new checklist item to the Implementation Checklist section. |
+| **Examples Needed** | Add a new named code example to the relevant section, using the same heading level and fenced code block style as neighboring examples. |
+
+#### 4c — Updating `web-auto-best-practices.md`
+
+This file has three sections: a **Do's** table (`| Practice | Reason |`), a **Don'ts** table (`| Anti-Pattern | Why to Avoid |`), and a **Code Examples** section with named subsections and code blocks.
+
+| Recommendation Type | How to Apply |
+|--------------------|--------------| 
+| **High Priority / Medium Priority** | Classify the recommendation as a Do or Don't, then add a new row to the appropriate table. Use one concise sentence per cell. Inline code snippets in cells are fine using backticks. |
+| **Examples Needed** | Add a new named subsection under `## Code Examples` with a descriptive heading and a fenced code block. |
+
+#### 4d — Verify Each File
+
+After editing each file:
+- Confirm no existing content was accidentally removed or altered
+- Check that markdown formatting is intact (table alignment, heading levels, code fences)
+- Verify new entries read naturally alongside existing content
+
+### Step 5: Summary
+
+```
+Source instructions updated from lessons learned for ticket {TICKET_ID}.
+
+Source:
+- .tickets/{TICKET_ID}/lessons-learned.md
+
+Updated Files:
+- {path} — {count} updates applied ({X} high, {Y} medium, {Z} examples)
+- {path} — {count} updates applied ({X} high, {Y} medium, {Z} examples)
+
+Skipped:
+- {Document Name} — {reason: no recommendations / file not found / all deduplicated}
+
+Duplicates Filtered: {count}
+Conflicts Flagged: {count}
+```
+
+## Key Principles
+
+- **Deduplication is mandatory** — check before adding. The single most common failure mode is bloating source files with redundant entries.
+- **Conflicts require human input** — never silently override existing content with a contradictory recommendation. Surface both versions and ask.
+- **Smallest effective change** — two precise additions beat ten vague ones. If a recommendation is too general to act on ("improve selector strategy"), drop it — it won't help the next implementer.
+- **Preserve existing content** — never delete, rewrite, or reorganize existing source instruction content.
+- **Skip missing files** — report the gap but continue with other files.
+- **Lessons file missing** — inform the user to run extract-lessons-learned first, then stop.

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

@@ -0,0 +1,22 @@
+{
+  "skill_name": "web-auto-update-source-instructions",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I just finished the lessons learned extraction for ticket fe-3050. The lessons-learned.md has 2 high-priority recommendations for Best Practices (one about using data-testid selectors instead of CSS classes, and one about adding explicit waits before assertions), 1 medium-priority for Coding Instructions (add a pattern for handling modal dialogs), and 1 example needed for Project Blueprint (directory structure for shared fixtures). The best practices file already has a row about preferring data-testid selectors. Update the source instructions.",
+      "expected_output": "Should deduplicate the data-testid recommendation (already exists in best practices), apply the remaining 3 recommendations to the correct files, add <!-- From ticket fe-3050 --> attribution comments, and report 1 duplicate filtered in the summary.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Update source instructions for ticket ABC-789. The lessons learned recommend adding 'Never use page.waitForTimeout() for synchronization' as a best practice, but the existing best practices file already says 'Avoid hardcoded timeouts — use waitForSelector or waitForLoadState instead' in the Don'ts table. Also there's a high-priority recommendation for Coding Instructions that says 'Always use baseURL from config' but the instructions file currently says 'Construct full URLs in each test file'. Handle these conflicts and updates.",
+      "expected_output": "Should detect the waitForTimeout recommendation as partially covered (clarification to existing entry), flag the baseURL conflict (contradicts existing content about constructing full URLs) and ask the user which is correct instead of silently applying it.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Apply lessons learned from ticket fe-2099 to the source instructions. The lessons-learned.md has recommendations targeting all three documents — project blueprint needs a new section on API mock configuration, coding instructions needs two new pattern blocks for intercepting network requests and for handling file uploads, and best practices needs both a new Do (verify API response status before asserting UI changes) and a new Don't (don't assert on auto-generated IDs). None of these exist in the current files.",
+      "expected_output": "Should apply all recommendations across all three files with proper formatting per document type, add attribution comments, and produce a summary showing updates to all three files with zero duplicates filtered."
+    }
+  ]
+}