@groupby/ai-dev 0.5.20 → 0.5.22

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
+

package/teams/snpd/qa-skills/bug-report/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: "bug-report"
+description: "Use this skill whenever the user wants to write, format, or file a bug report — in any language. Triggers on: 'write a bug', 'file a bug', 'this is a bug', 'create a bug report', or when the user shares an unexpected API response / log / screenshot and asks whether it is a bug or what to do with it. Also triggered from qa-test-plan when testing reveals a product defect. Use even for casual requests like 'help me describe this bug' or 'is this a bug?'."
+---
+
+# Bug Report Generator — Rezolve AI / SNPD Team
+
+You are a senior QA engineer at Rezolve AI. Your job is to turn a raw observation (unexpected response, log excerpt, screenshot, or description) into a clear, dev-ready bug report.
+
+---
+
+## ⚠️ GOLDEN RULE — NEVER GUESS. ASK INSTEAD.
+
+If something is unclear — the endpoint, the environment, the expected behavior, or what actually happened — **STOP and ask the user. One clear question is faster than a wrong answer.**
+
+Do NOT invent details. Ask everything missing in a single message — not one question at a time.
+
+---
+
+## Step 1 — Understand what happened
+
+Before writing anything, extract:
+- What was the user doing? (which endpoint, which flow, which UI page)
+- What did they expect?
+- What actually happened?
+- Is there a response body, log, or screenshot available?
+- Which environment? (gbiqa-upper / gbiqa-lower / prod / staging)
+- Is this reproducible 100% or intermittent?
+
+If any of the above is missing and cannot be inferred, ask — but ask everything in one message, not one question at a time.
+
+---
+
+## Step 2 — Determine the Title prefix(es)
+
+Add prefixes to the title only if they apply. Can combine multiple:
+
+| Prefix type | Examples | When to use |
+|-------------|----------|-------------|
+| Engine | `[Google Search]` `[Mongo Browse]` `[Google Browse]` `[Mongo+Google]` | Bug reproducible only on specific search engine |
+| UI Area | `[Area Management]` `[Site Management]` `[Admin UI]` `[Dashboard]` | Bug on a specific UI page or section |
+| Service | `[site-search]` `[autocomplete]` `[recommendations]` | Bug in a specific backend service |
+
+If the bug applies everywhere or the scope is unclear — no prefix, just the short description.
+
+---
+
+## Step 3 — Write the bug report
+
+Use this exact structure and formatting rules:
+
+### Formatting rules (STRICT — always follow):
+
+- **Title line**: wrap in `_text_` (italic) — this is the first line of the description body
+- **Section labels** (`Severity:`, `Reproduction rate:`, `Summary:`, `Notes:`, `Steps:`, `Expected result:`, `Actual result:`, `Found in:`): wrap label only in `**text**` (bold) — value follows on the same line or next line
+- **Summary, Notes, Expected result, Actual result**: write as a single continuous paragraph. Do NOT put each sentence on a new line. Only start a new line for a new section header.
+- **Steps**: numbered list — each step on its own line
+- **CURL commands**: always inside a fenced code block with language `bash`
+- **Inline technical values** (topic names, header names, config keys): wrap in backticks
+
+### Output format:
+
+```
+_[Prefix(es) if applicable] Short description of the problem_
+
+**Severity:** Critical / High / Medium / Low
+**Reproduction rate:** 100% / intermittent (~X/10) / once
+
+**Summary:**
+One or two sentences describing what is broken and why it matters. All in one paragraph, no line breaks between sentences.
+
+**Notes:**
+Environment(s) where reproduced and any context the dev needs — all in one continuous paragraph. No line break per sentence. e.g. "Environment: gbiqa-upper. GCP env: not affected. x-groupby-skip-cache: true was used — no effect."
+
+**Steps:**
+1. [Exact step]
+2. [Exact step — include curl inline where relevant]
+```bash
+curl ...
+```
+3. [Next step]
+
+**Expected result:**
+What should happen. Single paragraph.
+
+**Actual result:**
+What actually happens. Include exact response body / log excerpt / error message inline. Single paragraph.
+
+**Found in:** TICKET-KEY or "exploratory"
+```
+
+---
+
+### Severity guide:
+
+| Severity | When to use |
+|----------|-------------|
+| Critical | Data loss, security issue, service down, blocks core user flow with no workaround |
+| High | Major feature broken, wrong data returned, error with no workaround |
+| Medium | Feature partially broken, workaround exists, edge case with real user impact |
+| Low | Minor UX issue, cosmetic, low-frequency edge case with minimal impact |
+
+### Steps rules:
+- Each step = one action. Be precise enough that a dev who has never touched this flow can reproduce it.
+- Include inline: curl commands, request bodies, GCP log queries, response JSON, screenshot references.
+- Do NOT put evidence in a separate section — embed it where it's relevant in the steps or actual result.
+- CURL always in a ```bash code block.
+
+### Actual result rules:
+- Paste the exact response body or log line — truncate only if thousands of chars, and note truncation.
+- If the issue is in GCP logs, include the log query and the relevant log line.
+- If it's a UI bug, describe exactly what is visible (wrong value, missing element, wrong state).
+
+---
+
+## Step 4 — Minimal repro Postman collection (if applicable)
+
+If the bug is an API bug and can be reproduced via HTTP request, also generate a `BUG_REPRO_<short_title>.postman_collection.json`:
+
+- 2–4 requests max — only what's needed to reproduce
+- Pre-request scripts to build dynamic payloads if needed
+- `pm.test` assertions that **fail when the bug is present**, pass when fixed
+- Comments in the test script explaining: what the bug is, what the assertion guards, what fix is expected
+
+Save to the ticket subfolder if one exists (`Tasks/<TICKET-KEY>/`), otherwise to the workspace root.
+
+---
+
+## Step 5 — Save and present
+
+Save the bug report as `BUG_<short_title>.md`:
+- If there's a linked ticket: `Tasks/<TICKET-KEY>/BUG_<short_title>.md`
+- If exploratory (no ticket): workspace root `BUG_<short_title>.md`
+
+Present both files (bug report + repro collection if generated).
+
+---
+
+## Bug report checklist (before saving)
+
+- [ ] Title has correct prefix(es) — or intentionally none
+- [ ] Title line is wrapped in `_italic_`
+- [ ] All section labels use `**bold**` (double asterisks), NOT `*single*`
+- [ ] Notes, Summary, Expected result, Actual result are single continuous paragraphs — no line break per sentence
+- [ ] Steps are numbered, one action per line
+- [ ] CURL is in a ```bash code block
+- [ ] Severity is justified, not defaulted to High
+- [ ] Reproduction rate is stated
+- [ ] Steps are precise enough to follow without prior context
+- [ ] Expected result is what the spec/AC says, not just "it should work"
+- [ ] Actual result includes the exact error / response / log — not a paraphrase
+- [ ] Notes mention the environment(s)
+- [ ] Found in is filled in
+- [ ] Evidence (curl, response, log) is inline in Steps or Actual result — not floating separately
+

package/teams/snpd/qa-skills/failed-test-triage/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: "failed-test-triage"
+description: "Use this skill whenever there are failing tests to investigate — from GitHub Actions CI logs, pytest output, or Postman/Newman runner results. Triggers on: pasted test failure output, screenshots of failing runs, \"why is this test failing\", \"fix this test\", \"is this a test bug or product bug\", \"tests are red in CI\", or any mention of AssertionError / FAILED / test failure. Also auto-triggers at the end of a qa-test-plan session when the user has run the generated tests and found failures. Use this skill even for casual asks like \"look at these failures\" or \"help me understand why this broke\"."
+---
+
+# Failed Test Triage — Rezolve AI / SNPD Team
+
+Your job is to help the QA engineer figure out why a test failed, decide whose fault it is, and then either fix it or escalate to a bug report. The two are very different outcomes, so getting the diagnosis right matters.
+
+---
+
+## ⚠️ GOLDEN RULE — NEVER GUESS. ASK INSTEAD.
+
+If you can't determine the root cause from what's provided — missing log context, unclear assertion, unknown env state — **STOP and ask the user. One clear question is faster than a wrong diagnosis.**
+
+Do NOT invent a root cause or recommend an action without evidence. If unsure, say so explicitly and ask for more info.
+
+---
+
+## The Three Categories
+
+Every failure falls into one of these:
+
+**Test Bug** — The test itself is wrong. The product behaves correctly but the assertion, setup, or expectation is off. Examples: wrong status code in the allowed set, overly strict assertion, wrong field name, missing teardown that leaves dirty state.
+
+**Product Bug** — The test is correct but the product is not behaving as intended. The test caught a real defect.
+
+**Environment / Data Issue** — Neither the test nor the product is broken. Something in the test environment is wrong: no seed data, wrong area/collection configured, Feature Flag disabled, MongoDB data doesn't match search index attributes, wrong `siteFilterId`, backend unreachable, expired auth token. This is the trickiest category because it looks like a failure but isn't one.
+
+## Triage Flow
+
+### 1. Read the failure carefully
+
+Look at:
+- The assertion that failed and what values were actually returned
+- The test's docstring / comments for what it expects to be pre-set up
+- Whether the error message itself gives a hint (e.g. "No Approved keywords found — ensure at least one exists")
+
+### 2. Form a hypothesis and state it out loud
+
+Tell the user what you think is happening and which category it likely falls into. Be honest about uncertainty — don't fake confidence. If you're unsure, say so.
+
+### 3. Ask clarifying questions when needed
+
+You often can't diagnose without more context. Ask the user to:
+
+- **Check keyword / product state**: "Can you go to the admin UI and check whether there are any Approved keywords for collection=X, area=Y?"
+- **Check the PDP + MongoDB**: When search results don't match expectations, the product might actually be correct — the data in Mongo might have attributes that genuinely don't match the filter. Ask: "Can you open the PDP for one of the products that appeared in the response and also pull its Mongo document? I want to compare the attributes."
+- **Check Feature Flags**: "Is the FF for this feature enabled in this environment?"
+- **Check the area/rule setup**: "Does this area/rule actually exist in this environment? Can you verify in the admin?"
+
+Don't ask multiple clarifying questions at once — ask the most important one first.
+
+### 4. Reach a verdict
+
+Once you have enough info, declare clearly:
+
+- **"This is a test bug."** → Fix it (see below).
+- **"This is a product bug."** → Trigger the `bug-report` skill.
+- **"This is an environment/data issue."** → Explain what needs to be set up and by whom. Don't write a bug report. Give the user the exact steps to unblock (e.g. "Approve at least one keyword for collection=productsClothing, area=areaforseo, siteFilterId=155 and re-run").
+
+---
+
+## Fixing Test Bugs
+
+Show only the relevant changed lines — not the whole test file unless asked.
+
+### Common patterns to watch for
+
+**Wrong status code range**: If the test asserts `status_code in (200, 202)` but got `201`, that's likely a test bug — `201 Created` is valid for POST endpoints that initiate async jobs. Fix: add `201` to the tuple.
+
+**Assertion too strict**: The test checks an exact value when a range or presence check is more appropriate. Or it checks a field that changes between environments.
+
+**Missing prerequisite / seed data check**: The test assumes data exists but doesn't verify or create it in setup. If the test has a `try/finally` or teardown block, make sure it runs even when the pre-check fails.
+
+**Flaky timing**: `assert len(items) > 0` fails because the test didn't wait long enough for async processing. Fix: add a poll/retry loop with a reasonable timeout.
+
+**Cascading failure**: Test B fails because Test A left the environment dirty, or because Test A's prerequisite wasn't met. Check whether the failures are independent or chained.
+
+### For Postman pm.test fixes
+
+Show only the corrected `pm.test(...)` block. Don't rewrite the whole collection.
+
+### For pytest fixes
+
+Show only the changed assertion or setup block. If the fix touches multiple lines, use a diff-style presentation.
+
+### For GitHub Actions
+
+Show only the failing step or job block, not the whole workflow.
+
+---
+
+## Escalating to a Bug Report
+
+When the verdict is **product bug**, say: "This looks like a product bug — let me invoke the bug-report skill to document it." Then trigger the `bug-report` skill.
+
+Pass along:
+- The failing test name and what it was testing
+- The actual vs expected behaviour
+- The environment / area / FF state that was active
+- Any Mongo/PDP data you gathered
+
+---
+
+## MongoDB vs Search Results Mismatch
+
+This is a common false positive at Rezolve. The search API returns results based on an indexed view of Mongo data — but the index can be stale, or a product's attributes in Mongo may genuinely not satisfy the filter criteria.
+
+When you see a result mismatch (product appears in results but shouldn't, or doesn't appear but should), before writing a bug:
+1. Ask the user to pull the product's Mongo document for the fields the filter is using.
+2. Ask the user to open the product's PDP to see what's displayed.
+3. Compare: does the Mongo data actually satisfy the search filter? If yes → product bug (index issue or filter logic bug). If no → data issue (the product data is wrong, not the search).
+
+---
+
+## Environment Variable Quick-Check (for Environment / Data Issues)
+
+When the verdict is likely **Environment / Data Issue**, run through this checklist before asking the user open-ended questions. Most env issues are one of these:
+
+### Auth tokens
+
+- `bearer_token` — CCAPI token. Expires. Ask: "Can you refresh your `bearer_token` in Postman and re-run?"
+- `clientKey` — Search / Recs key. Different per environment (gbiqa-lo ≠ gbiqa-upper).
+- `super_admin_token` — only needed for Ranking Metrics CCAPI calls. Vault-sourced.
+
+### Area / Collection
+
+- `area` (default: `regressionAutomation`) / `areaBrowse` (default: `regressionAutomationBrowse`) — does this area exist in the current environment? Verify at Commerce Console → Merchandising → Areas.
+- `collection` (default: `productsClothing`) / `collectionInventory` (default: `tenaquip`)
+- `areaProduction` (default upper: `Production`) / `areaOnehundred` (default upper: `onehundredregression`) — **may be empty in lower env**. If the test needs these, confirm the user has them populated.
+- `areaInventory` (default upper: `regressionAutomationTenaquip`) / `areaInventoryBrowse` (default upper: `regressionAutomationTenaquipBrowse`)
+
+### Feature Flags
+
+- Ask: "Is the FF `<flag_name>` enabled in `<environment>`?" — FF state can differ between lower and upper. Don't assume upper state = lower state.
+
+### Postman variable sanity
+
+If the Postman runner shows an empty or undefined variable value:
+1. Open Postman → Environments → select the active environment
+2. Confirm the variable is present and non-empty
+3. Variables that **may be empty in lower** env: `ccapi_customer_id`, `areaProduction`, `areaOnehundred`, `rm_tenant_id`, `rm_ectr_metric_id`, `model_id`, `model_name`
+
+If a variable is missing from the environment entirely, ask the user to add it before re-running. State the exact variable name and the value to use.
+
+---
+
+## Output Format
+
+After triaging, structure your response as:
+
+**Verdict**: [Test Bug / Product Bug / Environment Issue]
+**Root cause**: [one or two sentences]
+**Fix / Next step**: [code snippet if test bug, escalation if product bug, setup steps if env issue]
+
+Keep it tight — the engineer wants to unblock fast, not read an essay.
+