@hiver/skills 1.0.8 → 1.0.9

package/collections/qa-skills/skills/qa-kit/references/handoff-contract.md

@@ -0,0 +1,159 @@
+# Handoff Contract — file-based state for the QA pipeline
+
+**Phase 1 foundation.** Every agent in the suite reads its input from disk and writes its output to
+disk. Handoffs are **files**, never chat blocks. This is the rule that keeps the decomposed skills
+from drifting (chat-only handoffs are what broke v2).
+
+Read this before emitting or consuming a handoff.
+
+---
+
+## 1. The run directory
+
+The first agent to run in a pipeline (usually `qa-kit`, or `hiver-explore` when there is no spec)
+**mints a run** and creates its directory. Everything for that run lives under it.
+
+```
+qa-output/
+  .current-run                      # pointer file: absolute path to the active run dir
+  <feature-slug>/
+    <run-id>/
+      handoff.json                  # the latest/active handoff (see §3)
+      handoffs/<from>-to-<to>.json  # one file per boundary crossed (audit trail)
+      tracker.xlsx                  # the shared state / memory (see §4)
+      steps/<skill>-<phase>.json    # eval step records — what each agent PRODUCED (see eval.md)
+      logs/<skill>.jsonl            # action log — the forensic trace of what each agent DID
+      trace/report.md               # qa-eval output, written at pipeline end
+      screenshots/                  # evidence captured by *-run agents
+      flow-recording-<date>.json    # optional, from flow-capture
+      spec.md                       # optional, copied from hiver-explore
+```
+
+### run-id
+Format: `<feature-slug>-<YYYYMMDD-HHMM>`, e.g. `hiver-notes-20260709-1530`.
+Mint it with a shell call so it is real, not guessed:
+```bash
+echo "$(echo "<feature>" | tr 'A-Z ' 'a-z-')-$(date +%Y%m%d-%H%M)"
+```
+
+### The pointer file
+`qa-output/.current-run` contains the absolute path to the active run dir. Any agent (or a hook, or
+`qa-eval`) resolves "which run am I in?" by reading this file. The minting agent writes it; later
+agents read it. If it is missing, the agent asks the user which run to attach to (or mints a new one).
+
+---
+
+## 2. Who mints, who reads
+
+| Agent | Mints a run? | Reads from | Writes to |
+|---|---|---|---|
+| hiver-explore | yes (if it starts the chain) | help docs + live UI | `spec.md`, `handoff.json` |
+| qa-kit | yes (usual entry point) | spec, diff, interview | `handoff.json` (triage summary) |
+| qa-ui-author / qa-api-author | no | `handoff.json` | `tracker.xlsx`, updated `handoff.json` |
+| qa-ui-run / qa-api-run | no | `tracker.xlsx`, `handoff.json` | `tracker.xlsx` (results), `screenshots/` |
+| qa-bugs | no | `tracker.xlsx` (failing rows) | ClickUp + tracker `Notes`/`Status` |
+| playwright-gen | no | `tracker.xlsx` (passing rows), `handoff.json` | specs in POC + tracker results + PR |
+| qa-eval | no | `steps/*.json`, artifacts | `trace/report.md` |
+
+---
+
+## 3. `handoff.json` — the boundary contract
+
+Written by the upstream agent, read by the downstream agent so it never re-asks for what is already
+known. One canonical `handoff.json` (the active one) plus an append-only copy per boundary in
+`handoffs/` for audit.
+
+```json
+{
+  "run_id": "hiver-notes-20260709-1530",
+  "from": "qa-kit",
+  "to": "qa-ui-author",
+  "feature": "Hiver Notes",
+  "slug": "hiver-notes",
+  "product": "HIG",                       // HIG | Omni | Both
+  "effort": "standard",                   // smoke | standard | exhaustive
+  "classification": "UI",                 // UI | API | new-API | mixed  (qa-kit only)
+  "impacted_services": ["web"],
+  "risks": ["right-panel injection timing"],
+  "spec_path": "qa-output/hiver-notes/.../spec.md",
+  "tracker_path": "qa-output/hiver-notes/.../tracker.xlsx",
+  "pr": "GrexIt/web#1234",
+  "figma": "https://figma.com/...",
+  "cases": [],                            // TC IDs relevant to this handoff (author→run→bugs)
+  "qa_owner": "Niranjan",
+  "notes": "free text",
+  "open_questions": ["are pinned notes in scope?"]
+}
+```
+
+Rules:
+- Downstream agents **must** read `handoff.json` before asking the user anything.
+- Each agent updates the fields it owns (e.g. author fills `tracker_path`; run fills nothing here but
+  writes results into the tracker), rewrites `handoff.json` with `from`/`to` advanced, and drops a
+  copy in `handoffs/<from>-to-<to>.json`.
+- Missing optional fields are fine; record gaps in `notes`/`open_questions` rather than blocking.
+
+---
+
+## 4. `tracker.xlsx` — the shared memory
+
+The tracker is the single source of truth for cases and their state. Schema and formatting are defined
+in `tracker-format.md` (unchanged). For the pipeline, the important contract is **column ownership** —
+each stage writes only its own columns:
+
+| Column | Owner (writes) | Everyone else |
+|---|---|---|
+| TC ID, Section, Test Case, Priority, Pre-conditions, Test Data, Steps, Expected | author | read-only |
+| Initial Behaviour – Testing 1 (✅/❌/⚠️/⏭️) | run | read-only |
+| Behaviour – Testing 2 | human QA | — |
+| Status (Pass/Fail/Bug/Not Tested) | run → then qa-bugs | read-only |
+| Notes / Bug Link | qa-bugs | read-only |
+
+A stage never rewrites another stage's columns. This makes each stage independently re-runnable and
+makes the tracker a reliable diff target for `qa-eval`.
+
+---
+
+## 5. Phase-1 wiring checklist (how existing skills adopt this — no behaviour change)
+1. Entry agent mints run dir + `.current-run` + `handoff.json`.
+2. Each skill, at start, reads `.current-run` → run dir → `handoff.json`.
+3. Each skill, at end, updates `handoff.json` + drops the `handoffs/` copy.
+4. Artefacts (tracker, screenshots, spec) are written **into the run dir**, not ad-hoc paths.
+No skill changes *what it does* yet — only *where it reads/writes*. Splitting comes in a later phase.
+
+---
+
+## 6. Per-agent handoff map — the pipeline, boundary by boundary
+
+**The contract, in one paragraph.** Every agent: (1) resolves the run via `qa-output/.current-run`;
+(2) reads its input `handoff.json` and never re-asks for cargo already there; (3) does its work,
+writing every artefact into the run dir and appending each meaningful action to `logs/<skill>.jsonl`;
+(4) on finish writes/updates `handoff.json` for the next agent (+ an audit copy in `handoffs/`) and a
+step record in `steps/`. `qa-eval` reads all step records + artefacts at the end. **That read → work
+→ write loop IS the end-to-end contract.**
+
+Boundaries (the split skills now exist — each emits its own records):
+
+| # | from → to | Trigger | Cargo the upstream writes into `handoff.json` | Artefacts into run dir |
+|---|---|---|---|---|
+| 1 | hiver-explore → qa-kit | no spec; explore done | spec_path, feature, slug, product?, open_questions | spec ref · steps/hiver-explore-spec.json |
+| 2 | qa-kit → qa-ui-author | class = UI or mixed | qa_owner, feature, product, effort, spec_path, risks, figma, cases:[] | steps/qa-kit-triage.json |
+| 3 | qa-kit → qa-api-author | class = API/new-API/mixed | + changed_endpoints | steps/qa-kit-triage.json |
+| 5 | qa-ui-author → qa-ui-run | tracker authored | tracker_path, cases, product (→ picks HIG/Omni adapter) | tracker.xlsx |
+| 6 | qa-ui-run → qa-bugs | any ❌/⚠️ in Testing-1 | failing_cases[], screenshots dir | tracker results · screenshots/ · steps/qa-ui-run-execute.json |
+| 7 | qa-ui-run → flow-capture | opt-in; PASS flows only | pass_flow_ids | flow-recording-&lt;date&gt;.json |
+| 8 | flow-capture → qa-api-run | a PASS recording exists (Gate A) | recording_path, endpoints[], payloads, order | steps/flow-capture.json |
+| 9 | qa-api-author → qa-api-run | spec-driven cases authored | tracker_path, cases, base_url (staging), auth_role | tracker.xlsx (API block) |
+| 10 | qa-api-run → qa-bugs | any ❌/⚠️ | failing_cases[] | tracker results · steps/qa-api-run-execute.json |
+| 11 | qa-ui-run → playwright-gen | passing automatable cases + opt-in | automatable_cases[], repo_root, pom_hints, live_observations | steps/qa-ui-run-execute.json |
+| 12 | (all) → qa-eval | pipeline end (auto) | — reads every steps/*.json + the artefacts | trace/report.md |
+
+### When does `qa-api-run` run? (two triggers)
+`qa-api-run` is the API executor. It runs on EITHER trigger:
+- **(a) Spec-driven** — qa-kit routed an API/new-API/mixed change → `qa-api-author` drafted cases → execute them.
+- **(b) Capture-driven** — `flow-capture` produced a PASS recording during `qa-ui-run`. **This is the
+  low-prerequisite path: the recording already says exactly what to send (endpoints, payloads, order)
+  and what NOT to send** — Gate A means PASS flows only; captured tokens are redacted; the executor
+  re-authenticates via `get_token()` instead of replaying the captured bearer; destructive calls are
+  gated. When a recording lands, `qa-api-run` should OFFER to execute it against staging — you no
+  longer need to reverse-engineer the API or arrange prerequisites beyond a staging token.

package/collections/qa-skills/skills/qa-kit/references/hiver-context.md

@@ -0,0 +1,99 @@
+# Hiver Context — QA Reference
+
+> **Domain knowledge base:** for the full feature map see
+> `../knowledge-base/hiver/INDEX.md`. It splits into **two product trees** —
+> `hig/` (Hiver in Gmail) and `omni/` (multi-channel: chat/Slack/voice/WhatsApp/tickets, Outlook,
+> SSO/SCIM) — each mirroring that product's real help-center segments, with a cross-feature
+> connection map for regression blast radius. Triage sets the product (HIG/Omni/Both); read the
+> matching tree. This file below is the quick QA primer; the KB is the comprehensive reference. For
+> deep, current, screen-accurate behaviour of any one feature, run `hiver-explore`.
+
+## What is Hiver
+
+Hiver is a **Chrome extension** that layers on top of Gmail to turn shared inboxes into a
+collaborative helpdesk. It is NOT a standalone web app — it runs as a Chrome extension injected
+into the Gmail UI. All testing happens with a specific extension version installed.
+
+## Key Concepts
+
+### SM — Shared Mailbox
+The core unit in Hiver. A shared inbox (e.g. support@company.com) that multiple agents can access.
+Every feature is configured at the SM level. When writing test cases, always specify which SM is
+being used in Pre-conditions.
+
+### Plans: HIG vs Omni
+- **HIG** (Hiver in Gmail) — the Gmail-native plan. Extension runs inside Gmail.
+- **Omni** — the multi-channel plan that supports email + other channels.
+- Some features are plan-gated. If the spec says "Both HIG and Omni", test on both.
+- If a feature behaves differently on each plan, write separate test cases.
+
+### Admin vs Agent Roles
+- **Admin** — configures settings, integrations, automations. Access to Settings panel.
+- **Agent** — day-to-day user. Handles conversations. Does NOT have access to Settings.
+- These are always separate test sections (Section A for Admin, Section B for Agent).
+- A single account can have both roles in test environments.
+
+### Right Panel
+The Hiver sidebar that appears on the right side of a Gmail conversation. Shows conversation
+details, custom fields, app integrations, notes, etc. Many features surface here for agents.
+
+### Conversations
+Hiver calls email threads "conversations". When the spec says "conversation", it means an email
+thread visible in the SM inbox.
+
+## Test Personas (from Playwright POC)
+
+The POC uses named personas. Reference these in test pre-conditions:
+
+| Persona | Role | Notes |
+|---|---|---|
+| Tony | Admin + Primary | Primary test account. Has admin access. |
+| Steve | Agent | Secondary agent account for multi-user tests |
+| Thor | Agent | Third agent account for multi-user tests |
+
+> **Analytics *events* (Gainsight) are out of scope — analytics *features* are NOT.** Gainsight has
+> been removed from Hiver, so do **not** write internal event-tracking cases and do not treat
+> "events fire" as a testable QA area; if a spec still lists Gainsight events, ignore them and note
+> them out of scope. This does **not** exclude a customer-facing analytics *feature* — an Analytics
+> dashboard, reports, metrics, or charts the user sees. Those are normal UI surfaces: test them
+> (rendering, filters, and that the numbers reconcile / compute per spec).
+
+## Extension Environment
+
+- Extension is loaded as a `.zip` or `.crx` file, not from the Chrome Web Store
+- Test environments use specific extension versions provided by devs (e.g. v7.5.6)
+- Pre-conditions for every TC should include: `Extension: v[version]`
+- If the user provides a `.zip` path, it must be extracted and loaded via chrome://extensions/
+  with Developer Mode enabled
+
+## Third-Party App Integrations
+
+Hiver integrates with: Salesforce, HubSpot, Jira, Asana, ClickUp, Salesforce, GoHighLevel,
+AppFolio, Slack, and more.
+
+When a feature integrates with multiple apps:
+- Each app may behave slightly differently (different OAuth flows, different field names)
+- Write one TC per app for the auth flow
+- Write one shared TC for common behaviour (e.g. "field mapping") with a note listing which apps it applies to
+- Always test auth failure + token expiry separately from the happy path
+
+## Common Test Setup Requirements
+
+Before testing most features, you need:
+- Admin account (Tony persona) logged into Gmail with Hiver extension loaded
+- SM created and accessible
+- If testing agent flows: agent account (Steve or Thor) in a separate Chrome profile
+- If testing app integrations: the third-party app authenticated at the SM level
+
+## Known Hiver Extension Quirks (from Playwright POC knowledgebase)
+
+Refer to `~/Documents/poc-playwright/knowledgebase-claude/HIVER-QUIRKS.md`
+for the full list. Key quirks to be aware of:
+
+1. **Bulk action toolbar is async** — appears after an async update cycle, not immediately
+2. **React re-render race conditions** — dropdowns can disappear after a re-render
+3. **Floating panels intercept clicks** — some panels block clicks on elements behind them
+4. **Dynamic vs static sidebar tabs** — some tabs only appear conditionally; navigation
+   can reset sidebar state
+
+These are relevant when writing browser test steps — account for wait states.

package/collections/qa-skills/skills/qa-kit/references/tracker-format.md

@@ -0,0 +1,123 @@
+# Shared Test Tracker Format
+
+This is the single source of truth for the Excel test tracker. **Both `qa-ui-author` and `qa-api-author`
+MUST produce their tracker using this schema** so that every QA engineer on the team ships an
+identical-looking file. Do not invent columns or reorder them.
+
+Use the `xlsx` skill to generate the file. Read the xlsx skill's SKILL.md before writing code.
+
+**Filename:** `TestTracker_[FeatureName]_[YYYY-MM-DD].xlsx`
+
+---
+
+## Sheet 1 — Test Cases
+
+Columns are grouped into **core** (always present, same order), a **track-specific** block, and
+a **shared tail** (always present, same order). The only difference between a UI tracker and an
+API tracker is the middle block.
+
+### Core columns (both tracks — always in this order)
+
+| # | Column | Notes |
+|---|---|---|
+| 1 | TC ID | Section letter + number, e.g. `A-01`, `B-03` |
+| 2 | Section | The test-area group name |
+| 3 | Test Case | One clear sentence: what is being validated |
+| 4 | Priority | `P0` / `P1` / `P2` |
+| 5 | Pre-conditions | What must be true before this test can run, **written as a bulleted list — one condition per line** (use line breaks within the cell, each line starting with `• `). **Plain, non-technical language** so someone without a technical background can follow it. Still include the specifics (e.g. `• Hiver extension version 7.5.6 is installed`, `• You are logged in as an Admin`, `• Shared Mailbox "Support" exists`; for API: `• Testing on the staging environment`, `• You have an Admin login token`). |
+| 6 | Test Data | The exact values to use, in **plain language a non-technical person understands** — spell out what each value is for, don't just dump raw IDs. E.g. `Admin email: tony@acme.com`, `Column name to add: "Priority"`, `Customer record ID: 10432 (the test customer "Acme Corp")`. |
+
+### Track-specific block
+
+**UI track (`qa-ui-author`) — insert after Test Data:**
+
+| # | Column | Notes |
+|---|---|---|
+| 7 | Test Steps | Numbered list in one cell (line breaks within the cell) |
+| 8 | Expected Result | Numbered list in one cell — one outcome per line |
+| 9 | Initial Behaviour – Testing 1 | **Yellow** `#FFF9C4`. Filled by the browser agent (automated first pass). |
+| 10 | Behaviour – Testing 2 | **Light blue** `#E3F2FD`. Filled by the QA engineer during manual verification. |
+| 11 | Screenshots | File paths / "Attach in ticket" |
+
+**API track (`qa-api-author`) — insert after Test Data:**
+
+| # | Column | Notes |
+|---|---|---|
+| 7 | Method | `GET` / `POST` / `PUT` / `PATCH` / `DELETE` |
+| 8 | Endpoint | Path with placeholders, e.g. `/api/v2/channels/{id}` |
+| 9 | Auth / Role | Token type + role used (e.g. `Admin bearer`, `Agent bearer`, `none`) |
+| 10 | Request Payload | JSON body / query params in one cell |
+| 11 | Expected Status | e.g. `201`, `200`, `403`, `422` |
+| 12 | Expected Response | Key assertions on the body (fields, values, error code) — one per line |
+| 13 | Actual Response | **Yellow** `#FFF9C4`. Filled when the case is executed (status + body snippet). |
+
+### Shared tail (both tracks — always last, in this order)
+
+| # | Column | Notes |
+|---|---|---|
+| … | Status | **Grey.** Values: `Pass` / `Fail` / `Bug` / `Blocked` / `Not Tested` |
+| … | Notes / Bug Link | ClickUp ticket link or notes |
+
+---
+
+## Formatting (identical for both tracks)
+
+- Frozen top header row.
+- Section header rows: merged across all columns, **dark navy `#1F3864`**, white bold text.
+- Priority tint on the **TC ID + Priority** cells only:
+  - P0 → light red `#FDECEA`
+  - P1 → light amber `#FFF9C4`
+  - P2 → light green `#E8F5E9`
+- Wrap text ON in all cells.
+- Suggested widths (px): TC ID 60 · Section 120 · Test Case 220 · Pre-conditions 180 ·
+  Test Data 160 · Test Steps 300 · Expected Result 300 · Payload 260 · Expected Response 260 ·
+  Testing/Actual columns 200 · Status 100 · Notes 200.
+
+---
+
+## Sheet 2 — Legend & Guide
+
+Include, verbatim:
+
+**QA owner:** `[name]` — *(the person running this QA pass; carried from the qa-kit handoff)*
+
+**Generated at effort level:** `[Smoke / Standard / Exhaustive]` — *(state which; see effort
+definitions below)*
+
+| Status | Meaning |
+|---|---|
+| Pass | Behaviour/response matches Expected exactly |
+| Fail | Behaviour/response does not match Expected |
+| Bug | Defect confirmed — add ClickUp ticket link in Notes |
+| Blocked | Cannot run — environment or dependency issue |
+| Not Tested | Not yet executed |
+
+| Priority | Definition |
+|---|---|
+| P0 | Must pass before release. Feature is broken/unusable without it. |
+| P1 | Should pass. Real-user impact but has a workaround or is low-frequency. |
+| P2 | Nice-to-have. Edge case or cosmetic. Can be deferred. |
+
+**Effort levels** (set at intake; controls which cases are in this file):
+
+| Level | Includes | Use when |
+|---|---|---|
+| Smoke | P0 only — the critical path / "the ~10 that matter" | Hotfix, tiny change, time-boxed pass |
+| Standard | P0 + P1 | Default for most features |
+| Exhaustive | P0 + P1 + P2 + all edge cases | High-risk feature, release-gating |
+
+UI-only notes:
+- "Testing 1" is the browser agent's automated first pass; "Testing 2" is the QA engineer's
+  manual verification.
+- Run P0 cases first, then P1, then P2.
+
+---
+
+## Sheet 3 — Summary (optional but recommended)
+
+A small table the QA engineer can read at a glance:
+
+| Section | P0 | P1 | P2 | Total | Pass | Fail | Bug | Blocked | Not Tested |
+|---|---|---|---|---|---|---|---|---|---|
+
+One row per section, plus a totals row.

package/collections/qa-skills/skills/qa-kit/references/triage-guide.md

@@ -0,0 +1,105 @@
+# Triage Guide — Classify the Change & Find the Blast Radius
+
+The orchestrator uses this to turn "here's a feature/PR" into a **classification** (UI / API /
+new-API / mixed), a list of **impacted services**, and a **product** (HIG / Omni / Both). Combine
+the diff, the QA interview, the spec, and Figma — no single source is enough.
+
+> The path maps below are a **starting heuristic** based on the Hiver repo layout. Always verify
+> against the actual diff and repo — directory names move. If a path isn't in the map, open it and
+> judge by content (does it render UI, or serve an endpoint?).
+
+---
+
+## Step 1 — Read the change (read-only)
+
+**From a PR:**
+```bash
+gh pr view <url-or-number> --json title,body,files   # title, description, changed files
+gh pr diff <url-or-number>                            # the actual diff
+```
+**From a local branch:**
+```bash
+git diff <base>...<branch>      # base is usually master or main
+git diff --name-only <base>...<branch>   # just the file list, fast
+```
+
+If neither is available, triage from the spec + interview and record "no diff" as a gap (the
+classification is then a best guess to confirm with the QA).
+
+---
+
+## Step 2 — Classify by what the changed files are
+
+### Signals → UI change → route `qa-ui-author`
+- Files under the **frontend** app (`web/…`): `.jsx`, `.tsx`, `.js` components, Redux
+  actions/reducers, `.scss`/`.css`, templates.
+- Changes to user-visible copy, layout, right-panel widgets, modals, settings screens.
+- Figma is attached and the diff is mostly presentational.
+
+### Signals → API change → route `qa-api-author`
+- Files under the **Rails backend** (`hot-api-mono/app/…`): controllers, models, `*.jbuilder`
+  views, serializers, `routes.rb`, policies, services/producers/consumers.
+- Backend services: `sync-engine`, `automations-api`, `custom-integrations`.
+- Changes to request/response shape, validation, auth/policy, DB schema/migrations.
+
+### Signals → **new-API** (a sub-type of API) → route `qa-api-author`, flag `[new]`
+- A **new route** added to `routes.rb` / a new controller action.
+- A new `*.jbuilder` view or serializer for a new resource.
+- A new endpoint version (e.g. a `v2` path alongside an existing `v1`).
+- Treat new-API as higher-risk: full Section A/B/C coverage even at lower effort.
+
+### Signals → **mixed** → route BOTH
+- The diff touches frontend **and** backend (very common for a full feature: new endpoint +
+  the UI that calls it).
+- A new backend endpoint plus a new right-panel/settings surface that consumes it.
+
+When in doubt between API and mixed, ask the QA: "Does this change have a screen a user interacts
+with, a backend endpoint, or both?"
+
+---
+
+## Step 3 — Map changed paths → impacted services (for the handoff)
+
+Name the services so the sub-skills and the QA know the blast radius. Starting map (verify):
+
+| Path / area (in the diff) | Impacted service to record | Track |
+|---|---|---|
+| `web/…` (React/Redux) | `web` (frontend) + the feature area (e.g. right-panel, settings) | qa-ui-author |
+| `hot-api-mono/app/controllers/…` | `hot-api-mono` + the controller/resource (e.g. channels) | qa-api-author |
+| `hot-api-mono/app/models/…` / migrations | `hot-api-mono` data layer — flag regression + data integrity | qa-api-author |
+| `hot-api-mono/**/*.jbuilder` / serializers | response contract — flag backward-compat | qa-api-author |
+| `sync-engine/…` | `sync-engine` — flag downstream sync side effects | qa-api-author |
+| `automations-api/…` | `automations-api` — automations/triggers (watch `OMNI`/`HIG` constants) | qa-api-author |
+| `custom-integrations/…` | `custom-integrations` + the third-party app | qa-api-author |
+
+Cross-reference for where tests live:
+- **API SHIELD** (`api-s.h.i.e.l.d`) organizes tests by domain: `tests/channels`, `tests/admirals`,
+  `tests/platforms`, `tests/incredibles`, `tests/sync`, `tests/team_name`. Map the impacted resource
+  to the closest domain folder — `qa-api-author` Phase 7 uses this when scaffolding pytest.
+- **poc-playwright** page objects are `pages/hiver-*.page.ts` — useful context for `qa-ui-author`.
+
+---
+
+## Step 4 — Detect the product (HIG / Omni / Both)
+
+In priority order, then **confirm with the QA**:
+1. **Diff signals** — `OMNI` / `HIG` constants, tenant flags, or paths that are clearly one product
+   (e.g. an Outlook-specific module → Omni).
+2. **Spec "Plans" field** — if the spec says HIG / Omni / Both, use it.
+3. **QA interview** — just ask if 1–2 are silent.
+
+If the feature is flagged for **Both** and behaviour may differ, tell the relevant track to write
+per-product cases (the sub-skills handle this) and consider a cross-tenant negative case.
+
+---
+
+## Step 5 — Surface the key risks
+
+From the diff + interview, note the highest-blast-radius items for the Triage Summary:
+- Schema/migration changes → regression + data-integrity risk.
+- Changed response shape → backward-compat risk for existing clients.
+- Auth/policy changes → authorization risk (Agent doing Admin things).
+- Shared/often-used endpoints or components → broad regression risk.
+- Third-party integration touched → external dependency risk.
+
+These become the "Key risks" line in the handoff and seed the sub-skill's Risk Register.