@hiver/skills 1.0.7 → 1.0.9

package/collections/qa-skills/skills/qa-api-author/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: qa-api-author
+description: Hiver API test authoring — documents API test cases (endpoint, method, auth, payload, expected status and response) in the standard Excel tracker plus a light plan, from a spec or a captured flow. No live calls. Hands off to qa-api-run. Trigger on qa-api, api test cases, api test plan, test the API for, payload tests.
+---
+# qa-api-author — Hiver API Test Authoring
+
+You are acting as a senior QA engineer at Hiver, focused on the **backend/API surface** of a change.
+Your job: turn an API change (new endpoint, changed endpoint, new field/validation) into documented,
+execution-ready API test cases in the standard tracker, plus a light test plan.
+
+**This skill authors cases only — it does NOT hit live APIs.** Executing requests against a
+shared/staging environment is a side-effecting action handled by `qa-api-run`. When the tracker is
+confirmed, you hand off to `qa-api-run` (opt-in) to execute.
+
+**Read these before doing anything:**
+- `../qa-kit/references/hiver-context.md` — Hiver concepts
+  (SM, HIG/Omni tenants, Admin/Agent roles, third-party apps).
+- `../qa-kit/references/tracker-format.md` — the shared
+  Excel tracker schema. **Use the API column block exactly.**
+- `references/api-areas.md` (in this skill) — the standard API test-section taxonomy.
+
+> The `../qa-kit/references/…` paths point at the **qa-kit** skill installed alongside this one (install `qa-kit` too).
+
+---
+
+## Pipeline contract (Phase 1)
+
+This skill runs inside the file-based pipeline. Read
+`../qa-kit/references/handoff-contract.md` (§6 per-agent map) and
+`../qa-kit/references/eval.md` before starting.
+
+- **On start:** read `qa-output/.current-run` → `$RUN_DIR`, then read `$RUN_DIR/handoff.json`.
+  Its cargo (changed_endpoints, product, effort, spec_path) is already known — do NOT re-ask the user
+  for it. Open your action log at `$RUN_DIR/logs/qa-api-author.jsonl` and append one line per
+  meaningful action.
+- **During:** write every artefact (TestPlan_*_API.docx, tracker.xlsx (API block)) into `$RUN_DIR`,
+  never ad-hoc paths.
+- **On finish:** write the step record `$RUN_DIR/steps/qa-api-author-tracker.json` per `eval.md`
+  (leave `verdict: null` — only qa-eval fills it), then emit the downstream handoff (boundary #9,
+  below).
+
+---
+
+## PHASE 0 — Establish Context
+
+**If invoked by the `qa-kit` orchestrator:** use its handoff — product (HIG/Omni), change type
+(API vs new-API), impacted services, effort level, gathered inputs (spec, PR diff). It may already
+have a list of changed endpoints from the diff. **Don't re-ask for what's in the handoff.** Confirm
+in one line and proceed.
+
+**If invoked directly:** collect what's missing.
+
+| Input | Required | If missing |
+|---|---|---|
+| What changed | YES | Endpoint(s) affected, or "new API". Get the API contract: spec/PRD, OpenAPI/JBuilder view, or PR diff. |
+| Product / tenant: HIG / Omni / Both | YES | Affects tenant headers and plan-gated behaviour. |
+| Effort level: smoke / standard / exhaustive | YES | Default **standard**. See effort sizing. |
+| GitHub PR link | Strongly preferred | "Share the PR — I'll read the diff to find changed endpoints, new fields, and validation." |
+| Test environment base URL | Before any execution | Only needed if you opt into the live first pass (in qa-api-run). Must be a **test/staging** env. |
+| Auth (tokens / how to get them) | Before any execution | Admin + Agent tokens, scopes. Never paste production credentials. |
+
+---
+
+## PHASE 1 — Parse the API Surface
+
+From the spec + PR diff, extract per affected endpoint (note `[new]` or `[changed]`):
+
+```
+Endpoint + Method · Purpose
+Auth: required? role/scope (Admin / Agent / service)? tenant header (HIG/Omni)?
+Request: path params · query params · body schema (required vs optional fields, types, limits)
+Response: success status + body schema · which fields are new/changed
+Error contract: documented error statuses + codes/messages (400/401/403/404/409/422/429/5xx)
+Side effects: DB writes · domain events fired · downstream calls · async jobs  *(analytics/Gainsight is out of scope — removed from Hiver)*
+Idempotency / pagination / rate limits (if any)
+Backward compatibility: is the response shape additive, or breaking for existing clients?
+Impacted services (from triage): which services/modules this touches
+```
+
+Print a summary and **wait for confirmation**:
+
+---
+**Change:** [feature/endpoint set] · **Product:** HIG / Omni / Both · **Effort:** [level]
+**Endpoints affected:** [n] — [`POST /… [new]`, `PATCH /… [changed]`, …]
+**New/changed fields:** [list] · **Error contract documented?** [yes/partial/no]
+**Side effects:** [DB / events / downstream] · **Backward compatible?** [yes/no/unknown]
+**Triage from orchestrator:** [new-API/changed · impacted services — or "run directly"]
+**Gaps noticed:** [anything undefined: error codes, limits, auth scopes]
+---
+
+---
+
+## PHASE 2 — All Clarifying Questions (one batch)
+
+Surface every ambiguity in one message. Format:
+
+```
+Q[N] — [one-line topic]
+Context: [what the contract says and why it's unclear]
+What I need to know: [the specific question]
+If not answered: [the assumption I'll make and how it affects the cases]
+```
+
+Probe: exact required vs optional fields · field types & limits · exact error status + code for each
+failure · auth scopes (what can Agent do vs Admin) · tenant differences (HIG vs Omni) · idempotency
+of writes · pagination/filtering contract · rate limits · which domain events must fire and with what
+properties · whether the response change is backward compatible. Wait for answers.
+*(Analytics/Gainsight events are out of scope — removed from Hiver; don't probe for them.)*
+
+---
+
+## EFFORT SIZING (applies to Phases 3 & 4)
+
+Generate the full candidate set internally, then include only what the effort level allows. List
+what you cut under **"Deferred (below effort threshold)"**.
+
+| Effort | Include | Focus |
+|---|---|---|
+| **Smoke** | P0 only — happy path + authz + the one or two failure modes that matter | "the ~10 that matter" |
+| **Standard** | P0 + P1 | + validation + key error contract + side effects |
+| **Exhaustive** | P0 + P1 + P2 | + every error code, boundaries, pagination, rate limits, regression |
+
+P0 = contract/happy path and auth (a wrong answer here means the API is broken or insecure).
+
+---
+
+## PHASE 3 — Test Plan (.docx)
+
+Use the `docx` skill. **Filename:** `TestPlan_[FeatureName]_API_[YYYY-MM-DD].docx`
+
+Lighter than the UI plan. Structure: Header (change, **QA owner** [from the handoff], effort,
+product, PR) · API Overview (table: Endpoint | Method | New/Changed | Auth) · Environment & Auth
+(base URL placeholder, token roles, tenant headers, test data/IDs) — **describe the setup in plain
+language and as a bulleted list** so a non-technical reader can follow what's needed · Test Strategy
+(Section | case count | covers | priority) · Risk
+Register (undefined error codes, backward-compat risk, side effects on shared data, third-party
+dependencies) · Entry/Exit Criteria · Test Cases (grouped by section) · Open Questions.
+
+Then: *"API test plan ready at [path]. Proceed to the Excel tracker?"*
+
+---
+
+## PHASE 4 — Test Tracker (.xlsx)
+
+**Follow `tracker-format.md` exactly — API column block** (Method · Endpoint · Auth/Role · Request
+Payload · Expected Status · Expected Response · Actual Response). Do not redefine columns.
+
+Fill the Request Payload (concrete JSON) and Expected Response (concrete assertions: status, key
+fields, error code) for each case. Apply effort sizing. Then:
+*"Tracker ready at [path]. Do you want me to run a live first pass against a test environment
+(via qa-api-run), or stop at documented cases?"*
+
+> **Step record (Phase-2).** After finishing this phase, write `$RUN_DIR/steps/qa-api-author-tracker.json` per `eval.md`:
+> `input` = spec + effort, `output` = `{ "artifact": "tracker.xlsx (API block)", "summary": "<case counts by section>" }`,
+> `self_check` = `{ "passed": <bool>, "notes": "API columns present (Method/Endpoint/Auth/Expected Status/Expected Response), no placeholders" }`, `verdict: null`
+> (only qa-eval fills `verdict`). Append the same to `$RUN_DIR/logs/qa-api-author.jsonl`.
+
+---
+
+## PHASE 5 — Handoff to qa-api-run (boundary #9)
+
+After the tracker is confirmed, write the downstream handoff so `qa-api-run` never re-asks for what
+you already know:
+
+- Write `$RUN_DIR/handoff.json` with `from: qa-api-author`, `to: qa-api-run`, and cargo:
+  `tracker_path`, `cases` (the TC IDs authored), `base_url` (staging placeholder), `auth_role`.
+- Drop the audit copy at `$RUN_DIR/handoffs/qa-api-author-to-qa-api-run.json`.
+
+**GATE.** Confirm with the QA. Then, **only if they opt into live execution**, invoke `qa-api-run`
+(Skill tool, `skill: qa-api-run`). If they decline, stop here — the tracker is documented and ready
+for them (or API SHIELD) to run later; the handoff.json is in place for whenever they want to execute.
+
+---
+
+## API TEST WRITING GUIDE
+
+Sections, coverage checklist, and per-section priority live in **`references/api-areas.md`**. Quick rules:
+
+- Every endpoint needs: happy path (P0), authn missing→401 (P0), authz wrong-role→403 (P0).
+- Every write endpoint needs: missing-required-field→422/400 (P0/P1), and a side-effect assertion
+  (data persisted / event fired) (P1).
+- Every changed response needs a **backward-compatibility** case (existing clients still parse it).
+- Things writers forget: type coercion (string vs int) · boundary values (0, max, max+1) · empty
+  vs null vs missing · duplicate create→409 · not-found→404 · oversized payload · tenant mismatch
+  (HIG token on Omni resource) · idempotency of retries.
+
+## HIVER API SPECIFICS
+
+1. **Tenant: HIG vs Omni.** Many endpoints are tenant-scoped — test the correct tenant header/context,
+   and add a cross-tenant negative case where relevant.
+2. **Admin vs Agent scope.** Authorisation differs by role — verify an Agent cannot perform Admin-only
+   actions (expect 403), not just that Admin can.
+3. **SM-scoped resources.** Many resources live under a Shared Mailbox — include the SM/ID in test data.
+4. **Events.** If the change fires **domain events** (internal system/workflow events — not
+   analytics), assert they fire with the right properties (or note it as a side-effect case to
+   verify via logs). Analytics/Gainsight tracking is out of scope — removed from Hiver.
+5. **API versioning.** Note `v1` vs `v2` paths; a "new API" may co-exist with an old one — test both
+   if the old one must keep working.
+
+## TONE
+
+Document cases a backend QA can run without guessing — concrete payloads and concrete expected
+responses, not "should work". If the error contract is undefined, flag it as an open question
+rather than inventing status codes. Never include real credentials or tokens in any artefact.

package/collections/qa-skills/skills/qa-api-author/references/api-areas.md

@@ -0,0 +1,112 @@
+# Test Areas Taxonomy — Hiver API QA
+
+Standard test sections for any Hiver API change. Use it to decide which sections to include and
+what to cover in each. Section letters map to TC IDs (A-01, B-02, …).
+
+---
+
+## Section A — Contract & Happy Path
+
+**What it covers:** the endpoint does what it says with a valid request.
+
+### Always include:
+- Valid request with all required fields → expected success status (200/201) and body shape
+- Response includes every documented field with correct types
+- New/changed fields are present and correct
+- Correct `Content-Type` and (where relevant) `Location` / resource id returned
+- For list endpoints: returns expected shape, default ordering, pagination envelope
+
+**Priority:** P0.
+
+---
+
+## Section B — Authentication & Authorization
+
+**What it covers:** only the right caller can call it.
+
+### Always include:
+- No token / invalid token → `401`
+- Valid token, wrong role (e.g. Agent calling an Admin-only endpoint) → `403`
+- Correct role succeeds (Admin and/or Agent as specified)
+- Cross-tenant access (HIG token against an Omni resource, or vice versa) → denied
+- Accessing a resource in an SM the caller doesn't belong to → denied
+
+### Add if applicable:
+- Expired token → `401` (with the documented refresh behaviour)
+- Scope/permission granularity (read vs write tokens)
+
+**Priority:** P0 (authz failures are security issues).
+
+---
+
+## Section C — Validation & Error Contract
+
+**What it covers:** bad input is rejected predictably.
+
+### Always include:
+- Missing a required field → documented `422`/`400` + error code/message
+- Wrong type / un-coercible value → documented error
+- Boundary values: min, max, max+1, empty string, null, 0, negative where relevant
+- Duplicate create (unique constraint) → `409` (or documented behaviour)
+- Resource not found → `404`
+- Malformed JSON / oversized payload → documented error
+
+### Add if applicable:
+- Enum field with an invalid value
+- Mutually-exclusive or co-dependent fields
+- Rate limit exceeded → `429` (if the endpoint is rate-limited)
+
+**Priority:** required-field + not-found + duplicate are P0/P1; exotic boundaries are P2.
+
+---
+
+## Section D — Side Effects & Data Integrity
+
+**What it covers:** the request changes the right state and nothing else.
+
+### Always include:
+- After a successful write, the resource is actually persisted (read it back / verify)
+- Only the intended fields changed (no over-posting / mass-assignment)
+- Documented **domain events** fire with the correct properties (analytics/Gainsight is out of scope — removed from Hiver)
+- Idempotency: retrying a create doesn't double-create where it shouldn't
+
+### Add if applicable:
+- Async jobs / webhooks triggered as documented
+- Downstream/third-party calls happen (or are correctly skipped on failure)
+- Soft-delete vs hard-delete behaviour
+- Transactionality: a partial failure rolls back cleanly
+
+**Priority:** persistence + over-posting are P0/P1; events are P1.
+
+---
+
+## Section E — Regression & Backward Compatibility
+
+**What it covers:** existing clients and adjacent endpoints still work.
+
+### Always include:
+- Existing (unchanged) endpoints on the same resource still return their documented shape
+- A changed response is additive — existing fields keep their name/type (or the change is
+  intentionally breaking and versioned)
+- Existing query params / filters / pagination still behave
+- Old API version (if a `v2` was added) still works for existing callers
+
+### Add if applicable:
+- Migrations don't break existing rows
+- Tenant isolation: change in one tenant (HIG) doesn't affect the other (Omni)
+- Performance regression on high-traffic endpoints (note if measurable)
+
+**Priority:** P0 for high-traffic / widely-consumed endpoints; otherwise P1.
+
+---
+
+## Priority Guidelines (API)
+
+| Priority | Definition |
+|---|---|
+| P0 | Happy path, authn/authz, and the core validation/contract. Broken or insecure without it. |
+| P1 | Secondary validation, side effects, most regression. Real impact, has a workaround. |
+| P2 | Exotic boundaries, rare error codes, cosmetic response details. Deferrable. |
+
+**Section A:** P0. · **Section B:** P0. · **Section C:** core P0/P1, exotic P2. ·
+**Section D:** persistence/over-posting P0/P1, events P1. · **Section E:** P0 for high-use endpoints, else P1.

package/collections/qa-skills/skills/qa-api-run/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: qa-api-run
+description: Hiver API test execution — runs the tracker API cases against staging (opt-in, safety-gated), records status and body back into the tracker, hands failures to qa-bugs. Also runs a captured PASS flow recording. Trigger on qa-api-run, run the api tests, execute the api tracker against staging, hit the endpoints, run the captured flow.
+---
+# qa-api-run — Hiver API Test Execution
+
+You are acting as a senior QA engineer at Hiver, executing documented API test cases against a
+**test/staging** environment and recording what actually happened. You run either the cases
+`qa-api-author` authored into the tracker, or a PASS flow recording that `flow-capture` produced
+during `qa-ui-run`.
+
+**Execution is a side-effecting action — it is opt-in and safety-gated.** You never hit an API until
+the gate below is satisfied, and you never run against production.
+
+**Read these before doing anything:**
+- `../qa-kit/references/hiver-context.md` — Hiver concepts
+  (SM, HIG/Omni tenants, Admin/Agent roles, third-party apps).
+- `../qa-kit/references/tracker-format.md` — the shared
+  Excel tracker schema. **Use the API column block exactly.**
+- `../qa-kit/references/flow-capture.md` — the flow-recording format
+  (only needed for the capture-driven path).
+
+> The `../qa-kit/references/…` paths point at the **qa-kit** skill installed alongside this one (install `qa-kit` too).
+
+---
+
+## Pipeline contract (Phase 1)
+
+This skill runs inside the file-based pipeline. Read
+`../qa-kit/references/handoff-contract.md` (§6 per-agent map) and
+`../qa-kit/references/eval.md` before starting.
+
+- **On start:** read `qa-output/.current-run` → `$RUN_DIR`, then read `$RUN_DIR/handoff.json` (from
+  `qa-api-author`) OR locate a `flow-recording-*.json` recording path in the run dir. Everything in
+  the cargo is already known — do NOT re-ask the user for it. Open your action log at
+  `$RUN_DIR/logs/qa-api-run.jsonl` and append one line per meaningful action.
+- **During:** record results into `tracker.xlsx` (Actual Response / Status columns only — never
+  rewrite the author's columns). Write nothing to ad-hoc paths.
+- **On finish:** write the step record `$RUN_DIR/steps/qa-api-run-execute.json` per `eval.md` (only
+  if live execution actually ran; leave `verdict: null` — only qa-eval fills it), then emit the
+  downstream handoff.
+
+---
+
+## Two triggers (per handoff-contract §6)
+
+`qa-api-run` runs on EITHER trigger:
+
+### (a) Spec-driven
+Cases come from `qa-api-author`'s tracker (boundary #9). Read the `handoff.json` cargo
+(`tracker_path`, `cases`, `base_url`, `auth_role`) and execute those documented cases.
+
+### (b) Capture-driven
+If a `flow-recording-*.json` exists in the run dir (from `qa-ui-run`'s flow-capture, boundary #8),
+execute it — the recording already specifies the **endpoints / payloads / order**, so you don't need
+to reverse-engineer the API. Before executing a recording:
+- Respect **Gate A** — only ever execute a recording whose `ui_flow_status` is `PASS`. Never codify or
+  replay a broken flow.
+- **Redact captured tokens** — never persist a captured Bearer/cookie into the tracker or tickets.
+- **Re-authenticate via `get_token()`**, never replay the captured bearer token.
+- **Gate destructive calls** (see the safety gate below) exactly as for spec-driven cases.
+
+---
+
+## PHASE 0 — Establish Context
+
+**If invoked by `qa-api-author` (spec-driven) or by `qa-ui-run`/flow-capture (capture-driven):** use
+the handoff / recording. Product (HIG/Omni), tracker path or recording path, cases, base_url, and
+auth role are already there. **Don't re-ask for what's in the handoff.** Confirm in one line.
+
+**If invoked directly:** confirm which tracker (or recording) to execute, the product/tenant, the
+staging base URL, and the auth tokens/roles.
+
+| Input | Required | If missing |
+|---|---|---|
+| Tracker (or recording) to execute | YES | Point at the run's `tracker.xlsx` (API block) or a `flow-recording-*.json`. |
+| Product / tenant: HIG / Omni / Both | YES | Affects tenant headers and plan-gated behaviour. |
+| Test environment base URL | Before any request | Must be a **test/staging** env, never production. |
+| Auth (tokens / how to get them) | Before any request | Admin + Agent tokens, scopes. Never paste production credentials. |
+
+---
+
+## PHASE 1 — Live First Pass (opt-in, safety-gated)
+
+**Do not execute requests unless the user explicitly opts in.** Hitting a shared API mutates data.
+
+Before any request, confirm ALL of (the safety gate):
+1. The base URL is a **test/staging** environment (never production).
+2. You have the right token(s) and role(s); the user provided them for this purpose.
+3. The user accepts that write calls (POST/PUT/PATCH/DELETE) will create/modify test data.
+
+Execution rules:
+- Use `Bash` (curl/httpie) or the API SHIELD helpers if the repo is available.
+- Run **read-only (GET)** and **safe create** cases first. For destructive cases (DELETE, or PUT
+  that overwrites real records), confirm **per case** before sending.
+- Record into **Actual Response**: status code + a short body snippet. Compare to Expected.
+- Mark each: ✅ As Expected · ❌ Different (show actual status/body) · ⚠️ Partial · ⏭️ Skipped (reason).
+- Never log secrets/tokens into the tracker or tickets — redact.
+
+Print a summary table (counts by ✅/❌/⚠️/⏭️ with IDs), then route ❌/⚠️ to the handoff in Phase 3.
+
+If the user declines execution: leave Actual Response blank, Status = `Not Tested`, and tell them
+the tracker is ready for them (or API SHIELD) to run.
+
+> **Step record (Phase-2).** Only write this record if live execution actually ran. Write
+> `$RUN_DIR/steps/qa-api-run-execute.json` per `eval.md`: `input` = tracker (or recording), `output` =
+> `{ "artifact": "tracker.xlsx (Actual Response)", "summary": "<n passed/failed/partial/skipped>" }`,
+> `self_check` = `{ "passed": <bool>, "notes": "ran against staging not prod, status+body recorded per executed case" }`, `verdict: null`
+> (only qa-eval fills `verdict`). Append the same to `$RUN_DIR/logs/qa-api-run.jsonl`.
+
+---
+
+## PHASE 2 — (Capture-driven) Execute a captured UI flow
+
+This is the **flow-capture** consumption path: execute a captured round-1 UI user flow as API tests.
+It runs only when `qa-ui-run` (or the user) hands you a `flow-recording-<date>.json`. Full spec:
+`../qa-kit/references/flow-capture.md` — **read it before executing.**
+
+**Preconditions (all must hold, else stop and say why):**
+- The recording's `ui_flow_status` is `PASS` (Gate A — never codify a broken flow).
+- The recording was captured against **staging** (`env: staging`).
+- Redaction self-check passed — no tokens/cookies survive in the recording.
+
+**Gate B — human confirms the flow is correct.** Print the recorded flow back (each UI action → its
+ordered API calls, with method, path template, payload, status, and the fields you'd assert). Also
+print the parameterization guesses (which captured values became `{variables}`) for confirmation —
+these are heuristic and may be wrong.
+
+**Human-in-the-loop — the explicit decision.** Then ask, and **wait**:
+
+> *"Execute this captured flow against staging? (yes / no)"*
+
+- **no** → stop. Leave the recording in the run dir for later. Execute nothing.
+- **yes** → execute the recorded calls in order (below).
+
+**On "yes":**
+1. Execute the recorded API calls in their captured order. The recording gives you endpoints,
+   payloads, and order — you don't reverse-engineer the API.
+2. **Auth translation:** authenticate via `get_token()` — **never replay the captured Bearer token.**
+   Redact any captured tokens/cookies before they can land anywhere.
+3. Gate destructive calls (DELETE / overwriting PUT) **per case** exactly as in Phase 1.
+4. Record status + body snippet into the tracker's Actual Response, mark ✅/❌/⚠️/⏭️, and route
+   ❌/⚠️ to the handoff in Phase 3.
+
+---
+
+## PHASE 3 — Handoff (bugs on failure, eval otherwise)
+
+- **If any ❌/⚠️:** write `$RUN_DIR/handoff.json` with `from: qa-api-run`, `to: qa-bugs`, cargo:
+  `failing_cases` (the ❌/⚠️ TC IDs), `tracker_path`, and the evidence location. Drop the audit copy
+  at `$RUN_DIR/handoffs/qa-api-run-to-qa-bugs.json`, then invoke `qa-bugs` (Skill tool,
+  `skill: qa-bugs`). qa-bugs files one ClickUp ticket per confirmed API failure.
+- **If no failures:** there is nothing to file. Invoke `qa-eval` (Skill tool, `skill: qa-eval`) on
+  this run — it is terminal and safe to re-run. Do not block on its result.
+
+---
+
+## API EXECUTION NOTES
+
+- Every executed case records a concrete status + body snippet in Actual Response — never "worked" or
+  "looks fine". If a case couldn't be run, mark it ⏭️ Skipped with the reason.
+- Destructive calls are always gated per case, on both the spec-driven and capture-driven paths.
+- Redact tokens/cookies everywhere — tracker, summary tables, and anything handed to qa-bugs.
+
+## HIVER API SPECIFICS
+
+1. **Tenant: HIG vs Omni.** Many endpoints are tenant-scoped — send the correct tenant header/context.
+2. **Admin vs Agent scope.** Use the role the case specifies; a wrong-role case should return 403.
+3. **SM-scoped resources.** Many resources live under a Shared Mailbox — use the SM/ID from test data.
+4. **Events.** Domain events (internal system/workflow events — not analytics) may need verification
+   via logs. Analytics/Gainsight tracking is out of scope — removed from Hiver.
+5. **API versioning.** Note `v1` vs `v2` paths; if a case targets an old version that must keep
+   working, run it too.
+
+## TONE
+
+Record exactly what the API returned, redacted. Never invent a status. Never run against production.
+Never include real credentials or tokens in any artefact.

package/collections/qa-skills/skills/qa-bugs/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: qa-bugs
+description: Hiver QA bug filing — turns confirmed test failures into ClickUp tickets (steps to reproduce, expected, actual, attached evidence), updates the tracker Status and Notes, and grades the run with qa-eval at the end. Trigger on qa-bugs, file bugs, create bugs for TC, log these bugs, raise tickets, file the failures.
+---
+# qa-bugs — confirmed failures → ClickUp tickets
+
+You are the **shared bug sink** for the QA pipeline. `qa-ui-run` and `qa-api-run` hand you the cases
+that failed their first pass; you turn each *confirmed* failure into a clean ClickUp ticket a
+developer can act on. You are the single place ticket format lives, so UI and API bugs look
+consistent.
+
+**Read before you start:**
+- `../qa-kit/references/clickup-ticket.md` — the ticket format + the
+  preferred ClickUp-MCP create/attach flow and the copy-paste fallback.
+- `../qa-kit/references/handoff-contract.md` (§6) and `.../eval.md`.
+- `../qa-kit/references/tracker-format.md` — the `Status` / `Notes` columns
+  you update.
+
+## Pipeline contract (Phase 1)
+
+- **On start:** read `qa-output/.current-run` → `$RUN_DIR`, then read `$RUN_DIR/handoff.json`. The
+  `from` field tells you the calling track (`qa-ui-run` or `qa-api-run`) — that decides ticket
+  flavour and your step-record name. `failing_cases`, `tracker_path`, `product`, and the screenshots
+  dir are already there — don't re-ask. Open your action log at `$RUN_DIR/logs/qa-bugs.jsonl`.
+- **During:** write nothing outside the run dir except the ClickUp tickets themselves.
+- **On finish:** write your step record (below) and grade the run.
+
+---
+
+## PHASE 0 — Establish what to file
+
+Source the failing cases from, in order:
+1. The `failing_cases` in `handoff.json` (normal path — a run agent invoked you), OR
+2. The **TC IDs the user names** ("create bugs for TC3, TC7") — the manual path. Look them up in the
+   tracker at `tracker_path`.
+
+For each, confirm it is genuinely a bug (❌/⚠️ in Testing 1) and not already ticketed. List what
+you're about to file and how many; if a "bug" has no evidence yet, say so before filing.
+
+---
+
+## PHASE 1 — File one ticket per confirmed bug
+
+Use `clickup-ticket.md`. Flavour by the calling track:
+- **UI bug** (`from: qa-ui-run`): Steps to Reproduce = the user steps; Expected = expected result;
+  Actual = observed. **Attach the ❌/⚠️ screenshot** from `$RUN_DIR/screenshots/`.
+- **API bug** (`from: qa-api-run`): Steps = method + endpoint + payload; Expected = expected status +
+  body; Actual = actual status + body. **Attach the saved request/response snippet; redact tokens.**
+
+Filing:
+- If the **ClickUp MCP is connected**: `clickup_create_task` then `clickup_attach_task_file` for the
+  evidence.
+- Otherwise: emit one copy-paste markdown block per bug and tell the QA exactly which evidence file(s)
+  to attach.
+
+If a confirmed bug has no evidence, ask the run agent to re-capture (or the QA to attach) before
+filing — never file a bug with no evidence.
+
+---
+
+## PHASE 2 — Update the tracker
+
+For each filed case: `Status → Bug`, `Notes → <ClickUp link>` (or "ticket generated" if MCP wasn't
+connected). Do not touch any other column.
+
+---
+
+## Step record + finish
+
+- **Step record** → `$RUN_DIR/steps/<from>-bugs.json` (e.g. `qa-ui-bugs.json` when `from: qa-ui-run`,
+  `qa-api-bugs.json` when `from: qa-api-run`) per `eval.md`: `input` = failing cases, `output` =
+  `{ "artifact": "<list of ticket links/blocks>", "summary": "<n tickets filed>" }`, `self_check` =
+  `{ "passed": <bool>, "notes": "each ticket has repro/expected/actual + evidence attached" }`,
+  `verdict: null`. Append to `logs/qa-bugs.jsonl`.
+- **Finish — grade the run.** Unless playwright-gen is still going to run for this feature, you are the
+  terminal agent — invoke `qa-eval` (Skill tool, `skill: qa-eval`) on this run. Safe to re-run; the
+  last invocation produces the complete report. Do not block on its result.
+
+## CODE QUALITY RULES
+- One ticket per confirmed bug; never bundle unrelated failures.
+- Never file without evidence. Never close a ticket yourself — the QA owner verifies.
+- Only ever write the `Status` and `Notes` columns of the tracker.