@groupby/ai-dev 0.5.21 → 0.5.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groupby/ai-dev",
-  "version": "0.5.21",
+  "version": "0.5.22",
   "description": "Interactive installer for Rezolve Ai development content",
   "type": "module",
   "bin": {

package/teams/snpd/qa-skills/README.md

@@ -0,0 +1,256 @@
+# SNPD Team — QA Skills
+
+A set of keyword-triggered skills that walk a Jira ticket through the full QA lifecycle — from ticket intake to a filed bug or a Qase-ready test suite — with a durable artifact at every stage.
+
+Each skill does one job, hands off a file, and stops. The human stays in control of every transition: no skill silently continues into the next, every open question surfaces in chat before any deliverable is written, and every artifact is saved next to the ticket so it can be audited later.
+
+## The pipeline
+
+```
+Jira ticket / Epic
+      │
+      ▼
+┌────────────────┐   writes  Tasks/{KEY}/{KEY}_Test_Plan.xlsx
+│ qa-test-plan   │ ────────▶ + {KEY}_Qase_Export.json
+└────────────────┘           (test cases with PR-diff findings + Qase-ready JSON)
+      │
+      ├─────────────► ┌────────────────┐   writes  Tasks/{KEY}/QA_Checklist.md
+      │               │ qa-checklist   │           (exploratory / regression pass)
+      │               └────────────────┘
+      │
+      ▼
+┌────────────────┐   writes  Tasks/{KEY}/{KEY}_<name>.postman_collection.json
+│ postman-qa     │ ────────▶ (SETUP + POSITIVE + REGRESSION + NEGATIVE
+└────────────────┘            + EDGE + KNOWN-BUGS + TEARDOWN)
+      │
+      ├─ fallback ─► ┌───────────────────────┐   writes  test_*.py + conftest.py + tests.yml
+      │              │ be-github-actions-qa  │           (pytest suite + CI job)
+      │              └───────────────────────┘
+      │
+      ├─ ui only ──► ┌───────────────────────┐   writes  *.spec.ts
+      │              │ fe-github-actions-qa  │           (Playwright E2E)
+      │              └───────────────────────┘
+      ▼
+   Test run
+      │
+      ├─ green ────► Qase import via {KEY}_Qase_Export.json
+      │
+      └─ red ─────► ┌────────────────────┐   verdict: test bug / product bug / env
+                    │ failed-test-triage │ ──┐
+                    └────────────────────┘   │
+                                             │ if product bug
+                                             ▼
+                                    ┌────────────────┐   writes  BUG_<slug>.md
+                                    │ bug-report     │ + BUG_REPRO_<slug>.postman_collection.json
+                                    └────────────────┘
+```
+
+`qa-test-plan` is the entry point and auto-invokes sub-skills via the Skill tool — never composes Postman / pytest / Playwright output from memory.
+
+## Skills
+
+### 1. `qa-test-plan` — plan the ticket
+
+- **Trigger** — any Jira key with testing intent (`S4R-11120`, `SNPD-4567`), or a Jira URL
+- **Reads** — the ticket via Atlassian MCP; every linked PR via the dev-status API + Chrome MCP `/files` tab; existing collections in `Tasks/`; the env file at `Tasks/gbiqa-lo.postman_environment.json`
+- **Produces** — `Tasks/{KEY}/{KEY}_Test_Plan.xlsx` and `Tasks/{KEY}/{KEY}_Qase_Export.json`
+- **Stops before** — writing any Postman / pytest / Playwright output (offers those in the next message)
+
+The orchestrator. Asks a scope question upfront (**Epic mode** — parent Epic + every related ticket, comments and statuses / **single-ticket mode** — this ticket + its comments + directly linked "relates to" issues), then does a mandatory PR review for every ticket in scope. Multiple PRs per ticket (follow-ups, optimisations) are all read. Every open question is posted in chat as one numbered list before the Excel is generated.
+
+Excel includes a Summary sheet with the code-review findings, a Setup sheet naming which entities SETUP must create, and one row per TC. Qase JSON export is Qase-import-ready and produced at the end of the automation cycle for suite creation.
+
+**Key rules:**
+- Reviews the PR of the ticket via dev-status API + Chrome MCP — Jira MCP never exposes PR URLs directly
+- If the repo requires SSO, stops and asks the user to log in — never guesses
+- **Rule #2a — reused-method regression trap:** a shared method invoked from a new caller sees a broader input surface. Every new input dimension gets its own TC
+- Asks upfront whether a Qase suite already exists — if it does, references those case IDs in the Excel's `Automation` column and skips duplicating
+- Never generates Postman without a working curl for every endpoint (or a verbatim body from an existing collection in `Tasks/`)
+- After the Excel, the very next message offers Postman — never pytest as default
+- After Postman, a Manual Check Guide is posted inline: env to select, run order, per-TC verification steps, GCP filter, cleanup confirmation
+
+### 2. `qa-checklist` — scoped manual pass
+
+- **Trigger** — "checklist for [ticket]", "exploratory test", "regression checklist"
+- **Reads** — the Jira ticket via Atlassian MCP
+- **Produces** — a sectioned markdown checklist (pre-conditions / functional / negative / engine coverage / regression / logging / automation coverage / sign-off)
+- **Stops before** — any automation work
+
+Fast, scoped checklist for exploratory or regression sessions. Not a replacement for `qa-test-plan` — used when a full test plan would be overkill (config change, small bug fix, quick regression pass). Adapts sections to ticket type (feature vs. bug fix vs. config).
+
+**Key rules:**
+- Cross-references existing Qase cases in the automation section
+- Adjusts engine coverage (VERTEXAI / RZLV) only if the ticket touches search/filter behaviour
+
+### 3. `postman-qa` — write the tests
+
+- **Trigger** — auto-invoked by `qa-test-plan` (Step 7a); also on "write pm.test", "fix Postman request", "generate collection"
+- **Reads** — the env file (`gbiqa-lo.postman_environment.json` or `gbiqa.postman_environment.json`); existing collections in `Tasks/`; the working curls the user provided
+- **Produces** — `Tasks/{KEY}/{KEY}_<name>.postman_collection.json`
+- **Stops before** — running the collection (that's manual via Runner or Newman)
+
+Every collection self-seeds: SETUP creates rules / attributes / filter sets and stores IDs in env vars; POSITIVE / REGRESSION / NEGATIVE / EDGE / KNOWN-BUGS folders reference those vars; TEARDOWN deletes everything (idempotent). Every SETUP body uses a shared `run_ts` (`Date.now()` in `pm.environment`) so re-runs never collide.
+
+**Key rules:**
+- **#0** Check `Tasks/{KEY}/` for an existing collection before creating a new one
+- **#1** Read the env file first. Variable names are exact: `{{bearer_token}}` (not `bearerToken`), `{{ccapi_customer_id}}` for numeric CCAPI path IDs (`{{areaId}}` does not exist)
+- **#2** `pm.environment.get/set`, never `pm.collectionVariables`
+- **#3** URL as a plain string in collection JSON, not object form
+- **#4** Integer variables must not be quoted in JSON body
+- **#5** Dynamic bodies via `pm.request.body.raw`
+- **#6** CCAPI PATCH takes the full attribute object from GET and modifies minimally — never a delta
+- Every test script includes the GCP log helper (prints correlation IDs for Logs Explorer lookup)
+
+### 4. `be-github-actions-qa` — pytest + CI fallback
+
+- **Trigger** — "write pytest for X", "add suite to CI", "why did CI fail"; also auto-invoked by `qa-test-plan` when Postman can't cover the case cleanly
+- **Reads** — the target file in `bs-qa-automation`, existing `conftest.py`, `.github/workflows/tests.yml`
+- **Produces** — `test_*.py`, updates to `conftest.py` (new marker), updates to `tests.yml` (new job / matrix entry)
+- **Stops before** — pushing / opening a PR
+
+Used only when Postman can't cover the case cleanly — multi-step data seeding beyond Postman scripting, GCP log verification, DB query-count checks, cross-service orchestration, or scheduled CI runs.
+
+Code patterns it produces: minimal test skeleton with fixtures, teardown, engine parametrization (`VERTEXAI` + `RZLV` in one test via `@pytest.mark.parametrize`), polling with timeout, full lifecycle (create → poll-verify → delete), and `@pytest.mark.known_bug` for product defects tracked in code.
+
+**Key rules:**
+- 5-step workflow: clarify → write test → register marker in `conftest.py` → add suite to `tests.yml` → give the exact local run command
+- Never invents markers or fixture names — asks if unclear
+
+### 5. `fe-github-actions-qa` — Playwright E2E
+
+- **Trigger** — "write Playwright test for X", "add UI test", "automate this UI flow"
+- **Reads** — existing specs in `brainstudiolower`, navigation helpers, `data-testid` map (or a screenshot the user provides)
+- **Produces** — `*.spec.ts` matching the repo's structure
+- **Stops before** — pushing / opening a PR
+
+Commerce Console UI tests: Rules, Facets, Areas, Zones, Redirects, Filter Sets, Site Management, Tag Management.
+
+**Key rules:**
+- Uses the repo's mandatory import pattern — no ad-hoc `@playwright/test` imports
+- Never navigates by raw URL — uses the navigation helper
+- Locator preference: `data-testid` > role > text > CSS. Never nth-child, never generated class names
+- Test name matches the Qase case ID when applicable
+- Asks for a screenshot or `data-testid` if a selector is unknown — never invents
+
+### 6. `bug-report` — file the defect
+
+- **Trigger** — "write a bug", "file a bug", "is this a bug?"; also auto-invoked by `failed-test-triage` when the verdict is product bug
+- **Reads** — the raw observation (response, log, screenshot, description), plus the ticket if one is linked
+- **Produces** — `BUG_<short_title>.md` (in `Tasks/{KEY}/` if linked, workspace root if exploratory) and, when applicable, `BUG_REPRO_<short_title>.postman_collection.json` (2–4 requests, minimum needed to reproduce)
+- **Stops before** — filing to Jira (that's manual — the file is the paste-ready payload)
+
+**Format (strict):**
+- Title with engine/scope prefix only if it applies — e.g. `[Google Search]`, `[Mongo Browse]`, `[Google Browse]`, `[Mongo+Google]`. No prefix if the bug applies everywhere or scope is unclear
+- Title line in body wrapped in `_italic_`
+- Section labels bold: `**Severity:**`, `**Reproduction rate:**`, `**Summary:**`, `**Notes:**`, `**Steps:**`, `**Expected result:**`, `**Actual result:**`, `**Found in:**`
+- Steps numbered, one action per line, precise enough for a dev who has never seen the flow
+- Actual result quotes the response / log **verbatim** — never paraphrased
+- Reproduction rate: `100%` / `intermittent (~X/10)` / `once`
+- Severity S1–S4 per guide
+- Environment paragraph names env, GCP env impact, cache header state, tenant
+
+**Key rules:**
+- Never invents error messages or field names — copies verbatim from the actual response
+- Repro collection is minimal — 2–4 requests, not the whole test flow
+
+### 7. `failed-test-triage` — diagnose the failure
+
+- **Trigger** — pasted failure output, "why is this failing", "tests are red in CI", "fix this test"
+- **Reads** — the assertion / traceback / Newman output; correlation IDs; the env state if unclear
+- **Produces** — a verdict in chat (test bug / product bug / env issue) + either a fix (test bug) or a `bug-report` handoff (product bug)
+- **Stops before** — filing a bug (that's `bug-report`'s job)
+
+Wrong diagnosis wastes days, so the skill forces an explicit hypothesis before touching anything. Flow: read the failure carefully → state hypothesis out loud → ask clarifying questions if evidence is missing → reach a verdict.
+
+**Key rules:**
+- Never says "flaky, rerun" without evidence
+- MongoDB vs Search results mismatch has its own playbook — check the MongoDB pipeline first, then compare with search response
+- Env checklist: auth token freshness, area/collection existence, LaunchDarkly flag state, tenant
+
+## How the skills connect
+
+### Artifact flow
+
+```
+Jira ticket / Epic
+      │
+      │  qa-test-plan
+      ▼
+Tasks/{KEY}/{KEY}_Test_Plan.xlsx      ◄── test cases + PR-diff findings
+Tasks/{KEY}/{KEY}_Qase_Export.json    ◄── ready for Qase import
+      │
+      │  postman-qa
+      ▼
+Tasks/{KEY}/{KEY}_<name>.postman_collection.json  ◄── SETUP + tests + TEARDOWN
+      │
+      │  test run (Runner or Newman)
+      ▼
+   red? ─── failed-test-triage ─── product bug? ─── bug-report ─── BUG_<slug>.md
+                                                                   BUG_REPRO_<slug>.postman_collection.json
+   green? ─ Qase import via {KEY}_Qase_Export.json
+```
+
+All artifacts live in `Tasks/{TICKET-KEY}/` in the workspace — never scattered.
+
+### Separation of concerns
+
+| Boundary | Meaning |
+|---|---|
+| Ticket ≠ Plan | The ticket says what changed; the plan decides what to cover |
+| Plan ≠ Tests | The Excel names the TCs; the collection scripts them |
+| Tests ≠ Verdict | A red run is not automatically a bug — `failed-test-triage` categorises it |
+| Verdict ≠ Bug | Product-bug verdict is the input to `bug-report`, not a filed bug |
+| File ≠ Import | Qase JSON export is created locally; Qase import is manual, at the end of the cycle |
+
+Each boundary is a human checkpoint. No skill silently rolls into the next.
+
+## Typical end-to-end run
+
+```
+"generate test plan for S4R-11120"     → qa-test-plan  →  Excel + Qase JSON
+"yes, generate the Postman collection" → postman-qa    →  SETUP + tests + TEARDOWN
+                                                          + Manual Check Guide in chat
+[run the collection in Postman Runner]
+"3 tests are red — see this output"    → failed-test-triage → verdict
+"file the bug"                         → bug-report    →  BUG_<slug>.md + repro
+[end of cycle]
+"import Qase JSON"                     → Qase suite created from {KEY}_Qase_Export.json
+```
+
+## Shared conventions
+
+- **Keyword-triggered.** Every skill fires on natural-language triggers — no `/slash-command` needed. Say "write a Postman collection for S4R-11120" and the right skill loads.
+- **Never guess.** Ask one clear question instead of inventing field names, locators, paths, or IDs.
+- **One message per batch of questions.** Every open question surfaces at once, not drip-fed across messages.
+- **Match existing structure.** Follow patterns already in the repo / collection — don't introduce new formats.
+- **English only** for all code, comments, and test names.
+- **Show only the relevant snippet** (fixed `pm.test` block, failing job step) — not full rewrites.
+- **Artifacts live next to the ticket.** All specs, plans, collections, and bug reports go under `Tasks/{TICKET-KEY}/`, never scattered in the workspace root.
+
+## Install
+
+Drop the skill folders into `.claude/skills/` in the target repo, or zip each as `<name>.skill` for the shared repo.
+
+```
+.claude/skills/
+├── qa-test-plan/          # includes references/
+├── qa-checklist/
+├── postman-qa/
+├── be-github-actions-qa/
+├── fe-github-actions-qa/
+├── bug-report/
+└── failed-test-triage/
+```
+
+Each folder contains `SKILL.md` with the full instructions and any supporting templates.
+
+## Requirements
+
+- **Atlassian MCP** — Jira fetch (`qa-test-plan`, `qa-checklist`)
+- **Claude in Chrome** MCP — PR review (dev-status API + PR `/files` tab)
+- **GitHub SSO login** in the browser — for private `groupby` repos
+- Access to `bs-qa-automation` (backend) and `brainstudiolower` (frontend) repos
+- Postman + Newman
+- `gbiqa` / `gbiqa-lower` credentials for Search API / CCAPI
+- Qase workspace access — for importing `{KEY}_Qase_Export.json`
+- GCP Logs Explorer access — for `[LOGGING]` TC verification

package/teams/snpd/qa-skills/be-github-actions-qa/SKILL.md

@@ -0,0 +1,354 @@
+---
+name: "be-github-actions-qa"
+description: "Use this skill whenever the user wants to write, fix, or update GitHub Actions CI workflows or pytest tests for the bs-qa-automation repo (GroupBy / Rezolve SNPD team). Triggers on: \"write a test for X\", \"add this suite to CI\", \"write a workflow for X\", \"why did CI fail\", \"fix this failing job\", \"add a new step to the workflow\", \"write pytest for X\", \"update tests.yml\", or any mention of .github/workflows, pytest markers, conftest.py, or GitHub Actions in a QA context. Use this skill even for casual asks like \"write a test for the redirect endpoint\" or \"my CI job is failing, what's wrong\" — if it involves pytest or the Actions workflow, trigger this skill. This skill writes both the test file AND updates conftest.py and tests.yml as needed. Also use when the user pastes a failing CI log and asks what to do."
+---
+
+# GitHub Actions QA Skill — Rezolve AI / SNPD Team
+
+You are a senior QA automation engineer working on the `bs-qa-automation` repo (GroupBy / Rezolve).
+Your job is to write pytest tests, keep `conftest.py` up to date, and maintain the GitHub Actions workflow.
+All code and comments must be in English.
+
+---
+
+## ⚠️ GOLDEN RULE — NEVER GUESS. ASK INSTEAD.
+
+If something is unclear — a file path, a variable name, an endpoint format, whether a test or suite already exists, or any missing context — **STOP and ask the user. One clear question is faster than a wrong answer.**
+
+Do NOT invent, assume, or guess. A single clarifying question saves everyone time.
+
+---
+
+## Repo Structure
+
+```
+/Users/lika/bs-qa-automation/
+├── tests/
+│   └── <suite>/
+│       └── test_<feature>.py
+├── utils/
+│   ├── api_client.py     # HTTP client, shared headers, base URLs
+│   └── config.py         # area + collection scenarios
+├── conftest.py           # pytest marker registration
+├── requirements.txt
+└── .github/
+    └── workflows/
+        └── tests.yml     # manual dispatch CI, suite dropdown
+```
+
+---
+
+## Environment & Auth
+
+```python
+from dotenv import load_dotenv
+load_dotenv()
+load_dotenv(".env.local", override=True)
+
+BASE_URL           = os.getenv("BASE_URL", "https://search.gbiqa.groupbycloud.com")
+CLIENT_KEY         = os.getenv("CLIENT_KEY")
+CCAPI_BEARER_TOKEN = os.getenv("CCAPI_BEARER_TOKEN", "")
+REDIRECT_BASE_URL  = os.getenv("REDIRECT_BASE_URL", "https://ccapi.gbiqa.groupbycloud.com")
+```
+
+GitHub Actions secrets: `CLIENT_KEY`, `CCAPI_BEARER_TOKEN`.
+
+---
+
+## API Headers
+
+```python
+HEADERS = {
+    "accept": "*/*",
+    "content-type": "application/json",
+    "authorization": f"client-key {CLIENT_KEY}",
+    "x-groupby-customer-id": "gbiqa",
+    "origin": "https://cc.gbiqa.groupbycloud.com",
+    "referer": "https://cc.gbiqa.groupbycloud.com/",
+}
+
+CCAPI_HEADERS = {
+    "accept": "application/json",
+    "content-type": "application/json",
+    "authorization": f"Bearer {CCAPI_BEARER_TOKEN}",
+    "x-groupby-customer-id": "gbiqa",
+}
+```
+
+---
+
+## Test Data (areas & collections)
+
+| Area name           | areaId | Collection         | Engine         | Use for                    |
+|---------------------|--------|--------------------|----------------|----------------------------|
+| `LikaNew`           | 697    | `productsClothing` | GOOGLE (Vertex)| Manual / exploratory tests |
+| `marcinautomation`  | —      | `productsClothing` | GOOGLE (Vertex)| Automated tests (preferred)|
+| `likaareatwo`       | —      | `productsClothing` | GOOGLE_BROWSE  | Browse tests               |
+| Tenaquip account    | —      | —                  | —              | Inventory / variantRollup  |
+
+**Rule:** Use `marcinautomation` area for all automated tests. `LikaNew` is for manual/exploratory only.
+
+Environments:
+- `gbiqa` (upper): `https://search.gbiqa.groupbycloud.com`
+- `gbiqa-lo` (lower): `https://search.gbiqa-lo.groupbycloud.com`
+
+Primary search endpoint: `POST /api/search`
+CCAPI (config): `GET/POST /ccapi/admin/area/{areaId}/...`
+
+---
+
+## Registered pytest Markers
+
+Defined in `conftest.py`. Always use existing markers when they fit — only create a new one if none applies.
+
+| Marker              | Scope                                       |
+|---------------------|---------------------------------------------|
+| `rules`             | Merchandising Rules                         |
+| `facets`            | Facets / Navigations                        |
+| `redirect`          | Redirects                                   |
+| `conversational`    | Conversational Search                       |
+| `area_management`   | Admin Area Management                       |
+| `variant_rollup`    | variantRollupKeys parameter                 |
+| `search`            | Contract tests for /api/search              |
+| `filter_sets`       | Product Recommendations Filter Sets         |
+| `templates`         | Merchandising Templates                     |
+| `compound_filter`   | S4R-10753 Mongo compound.filter dedup       |
+| `known_bug`         | Tests that FAIL due to a real product bug   |
+
+To add a new marker, append to `conftest.py`:
+```python
+config.addinivalue_line("markers", "new_marker: short description")
+```
+
+---
+
+## Code Patterns
+
+### Minimal test
+```python
+import pytest
+import requests
+from utils.api_client import HEADERS, BASE_URL
+
+@pytest.mark.search
+def test_basic_search_returns_records():
+    payload = {"area": "LikaNew", "collection": "productsClothing", "query": "shirt"}
+    resp = requests.post(f"{BASE_URL}/api/search", headers=HEADERS, json=payload)
+    assert resp.status_code == 200
+    data = resp.json()
+    assert "records" in data and len(data["records"]) > 0
+```
+
+### Teardown — create/delete entities
+```python
+@pytest.fixture(autouse=True)
+def cleanup():
+    created = []
+    yield created
+    for item_id in created:
+        requests.delete(f"{REDIRECT_BASE_URL}/ccapi/admin/area/697/{item_id}", headers=CCAPI_HEADERS)
+```
+
+### Engine parametrization — cover both VERTEXAI and RZLV
+```python
+ENGINES = {
+    "VERTEXAI": {"query": "dress", "expected_source": "VERTEXAI"},  # non-empty query
+    "RZLV":     {"query": "",      "expected_source": "RZLV"},      # empty query / browse
+}
+
+@pytest.mark.parametrize("engine", list(ENGINES.keys()))
+def test_feature_works_across_engines(engine):
+    cfg = ENGINES[engine]
+    payload = {"area": "marcinautomation", "collection": "productsClothing",
+               "query": cfg["query"], ...}
+    resp = requests.post(f"{BASE_URL}/api/search", headers=HEADERS, json=payload)
+    assert resp.status_code == 200
+    assert resp.json()["engineSource"] == cfg["expected_source"]
+```
+
+### Polling — wait for async data
+```python
+import time
+
+def poll_until(fn, timeout=60, interval=3):
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        result = fn()
+        if result:
+            return result
+        time.sleep(interval)
+    raise TimeoutError("Condition not met within timeout")
+```
+
+### Create → verify (poll) → delete lifecycle
+```python
+@pytest.fixture
+def created_resource():
+    resource_id = ccapi_create(...)
+    poll_until(lambda: resource_visible_in_search(resource_id), timeout=60, interval=3)
+    yield resource_id
+    ccapi_delete(resource_id)
+
+def test_resource_visible_in_search(created_resource):
+    resp = requests.post(f"{BASE_URL}/api/search", headers=HEADERS,
+                         json={"area": "marcinautomation", "collection": "productsClothing", ...})
+    assert created_resource in [r["id"] for r in resp.json()["records"]]
+```
+
+### Known bug — real product defect
+```python
+@pytest.mark.known_bug
+def test_filter_dedup_not_working():
+    """S4R-10753: Mongo compound.filter returns duplicate products."""
+    ...
+    assert len(data["records"]) == len(set(r["id"] for r in data["records"]))  # FAIL until fixed
+```
+
+Known bug tests are excluded from normal runs via `-m 'not known_bug'` in CI.
+
+---
+
+## Writing New Tests — Step by Step
+
+When the user asks for a new test, follow this sequence:
+
+**Step 1 — Clarify (if not obvious):**
+- Which feature or endpoint?
+- Does an existing marker fit, or is a new one needed?
+- Any teardown required (entities to create/delete)?
+
+**Step 2 — Write the test file:**
+- Path: `tests/<suite>/test_<feature>.py`
+- If creating a new suite folder, also create `tests/<suite>/__init__.py` (empty file)
+- Import from `utils.api_client` — do not hardcode headers or URLs
+- Use `marcinautomation` area (not `LikaNew`) for all automated tests
+- No mocking — these are real integration tests against the live QA environment
+- Descriptive test function names (`test_<what_it_verifies>`)
+- Name test functions with TC ID: `test_tc01_<short_description>`
+- Parametrize across engines (`VERTEXAI` / `RZLV`) when the ticket involves search API
+- Docstrings only when the logic is non-obvious
+- snake_case variables
+
+**Step 3 — Update `conftest.py` if a new marker is needed:**
+Show only the line to add — do not rewrite the whole file.
+
+**Step 4 — Update `.github/workflows/tests.yml` if a new suite is needed:**
+Show only the two changes (options list + case mapping):
+```yaml
+# 1. Add to options list under suite input:
+- new_suite
+
+# 2. Add to case block in run step:
+new_suite) MARK="new_marker" ;;
+```
+
+**Step 5 — Provide the local run command:**
+```bash
+pytest -v -s -m "marker_name" tests/<suite>/
+```
+
+---
+
+## Fixing Failing CI Jobs
+
+When the user pastes a failing CI log or .yml snippet:
+
+1. **Identify the failing step** — look for `Error:`, `FAILED`, non-zero exit codes
+2. **Classify the cause:**
+   - **Workflow YAML error** — wrong syntax, missing secret ref, wrong step name → fix the YAML step
+   - **pytest failure** — a test assertion failed → hand off to the `failed-test-triage` skill
+   - **Environment/setup error** — missing dependency, wrong Python version, secret not passed → fix the setup step
+3. **Show only the fixed step(s)** — never rewrite the whole workflow unless asked
+
+### Common CI failure patterns
+
+| Symptom | Likely cause | Fix |
+|---------|-------------|-----|
+| `ModuleNotFoundError` | Missing pip install step or wrong requirements.txt path | Add/fix `pip install -r requirements.txt` |
+| `secret not found` / empty `CLIENT_KEY` | Secret not passed to env block | Add `CLIENT_KEY: ${{ secrets.CLIENT_KEY }}` under `env:` |
+| `pytest: error: unrecognized arguments` | Marker not registered | Add marker to `conftest.py` |
+| `No tests ran` | Wrong `-m` expression or suite name typo | Check case mapping in `tests.yml` |
+| `TimeoutError` | Async operation too slow | Increase `timeout` in `poll_until()` |
+| `AssertionError` on status | Real product or env issue | Use `failed-test-triage` skill |
+
+---
+
+## Adding a New Suite to CI
+
+When creating a new test suite, always make all three changes together:
+
+**1. `tests/<suite>/test_<feature>.py`** — the test file
+
+**2. `conftest.py`** — register the new marker (show only the added line)
+
+**3. `.github/workflows/tests.yml`** — add suite to dropdown and case block:
+
+```yaml
+# Under inputs > suite > options:
+- new_suite_name
+
+# Under steps > run (the pytest dispatch block):
+new_suite_name) MARK="new_marker" ;;
+```
+
+Always present all three files/snippets together so the user can apply them in one go.
+
+---
+
+## CI Workflow Reference
+
+The workflow is triggered manually (`workflow_dispatch`) with a suite dropdown. Relevant structure:
+
+```yaml
+on:
+  workflow_dispatch:
+    inputs:
+      suite:
+        description: 'Test suite to run'
+        required: true
+        type: choice
+        options:
+          - rules
+          - facets
+          - redirect
+          # ... existing suites
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    env:
+      CLIENT_KEY: ${{ secrets.CLIENT_KEY }}
+      CCAPI_BEARER_TOKEN: ${{ secrets.CCAPI_BEARER_TOKEN }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - run: pip install -r requirements.txt
+      - name: Run tests
+        run: |
+          case "${{ inputs.suite }}" in
+            rules)           MARK="rules" ;;
+            facets)          MARK="facets" ;;
+            redirect)        MARK="redirect" ;;
+            # ...
+          esac
+          pytest -v -s -m "$MARK" --html=report.html --self-contained-html
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: test-report
+          path: report.html
+```
+
+---
+
+## Style Rules
+
+- All code and comments in English
+- snake_case for variables and function names
+- No HTTP mocking — always real integration tests
+- Known bugs: always tag with `@pytest.mark.known_bug` + Jira key in docstring
+- Keep tests independent — each test must be able to run in isolation
+- Show only the affected snippet, not the full file, unless the user asks for the whole thing
+