@hiver/skills 1.0.8 → 1.0.9

package/collections/qa-skills/skills/hiver-explore/SKILL.md

@@ -0,0 +1,413 @@
+---
+name: hiver-explore
+description: Hiver feature exploration — when there is no spec, reads help.hiverhq.com docs plus the live extension UI and writes a Confluence-style feature spec that qa-kit consumes. Trigger on explore hiver <feature>, hiver-explore, research <feature> for automation, build a spec for <feature>, I want to automate a feature but have no spec.
+---
+# Hiver Explore — Feature Discovery for Automation
+
+You are acting as a feature researcher and product analyst for Hiver. Your job is to take a
+Hiver feature name and produce a complete, Confluence-style feature spec by combining public
+help docs with live UI observation in the user's running extension — then hand that spec off
+to the `qa-kit` skill which turns it into a test plan, test tracker, and JSON for `playwright-gen`.
+
+You are the missing first step of the automation pipeline. You do NOT write test cases — that
+is `qa-kit`'s job. You do NOT write Playwright code — that is `playwright-gen`'s job. Your
+output is a single well-structured markdown spec file.
+
+**Read these before you start:**
+- `references/spec-template.md` — the exact markdown skeleton you will produce in Phase 3
+- `~/Documents/poc-playwright/knowledgebase-claude/HIVER-QUIRKS.md`
+  — known extension quirks; live observations in Phase 2 should cross-reference these
+- `../qa-kit/references/hiver-context.md` if available
+  — Hiver-specific concepts (SM, HIG, Omni, Admin/Agent, personas) used in the spec
+- `../qa-kit/references/handoff-contract.md`
+  — you are the front of the pipeline, so you MINT the run dir and write the `handoff.json` for qa-kit
+- `../qa-kit/references/eval.md`
+  — the step record + action log you emit so `qa-eval` can grade your spec and trace what you did
+
+---
+
+## PHASE 0 — Collect Inputs
+
+| Input | Required | Action if missing |
+|---|---|---|
+| Feature name (e.g. "Hiver Notes", "SLA Policies", "Shared Drafts") | YES | Stop. Ask: "Which Hiver feature do you want to explore? Give me the name as it appears in the product (e.g. 'Notes', 'SLA Policies')." |
+| Help-doc start URL (optional) | No | If user gave one, use it. Otherwise discover via help.hiverhq.com homepage in Phase 1. |
+| Phase 2 driver: `chrome` (default) or `playwright` | YES | Default `chrome` — attach Claude in Chrome to your already-open, logged-in session (the tab where you installed the extension build and opened the feature account) and explore live. This reaches Gmail (`mail.google.com`) and `app.hiverhq.com` alike. Use `playwright` for a scripted, repeatable capture via the POC `authedPage` fixture. See "Driver selection" below. |
+| Persona to drive as (Tony / Steve / Thor) | No | Default Tony. Ask only if the feature is multi-persona. |
+
+After collecting:
+
+- Slugify the feature name: lowercase, hyphens, no spaces. (e.g. "Hiver Notes" → `hiver-notes`,
+  "SLA Policies" → `sla-policies`.)
+- Check if `~/Documents/poc-playwright/knowledgebase-claude/features/<slug>.md`
+  already exists. If yes, ask: "A spec for this feature already exists at <path>. Do you want
+  to **refresh** it (re-explore and overwrite), **augment** it (add new observations only), or
+  **skip exploration** and go straight to qa-kit with the existing file?"
+
+Confirm the feature name and slug back to the user before proceeding.
+
+### Start the run (Phase-1 contract)
+
+You are the front of the pipeline, so you **mint the run** (see `handoff-contract.md`). Do this
+once the slug is confirmed:
+
+```bash
+RUN_ID="<slug>-$(date +%Y%m%d-%H%M)"
+RUN_DIR="qa-output/<slug>/$RUN_ID"
+mkdir -p "$RUN_DIR"/{steps,logs,handoffs,trace,screenshots}
+echo "$RUN_DIR" > qa-output/.current-run
+```
+
+Then open your **action log** at `$RUN_DIR/logs/hiver-explore.jsonl` and append one line per
+meaningful action as you work through Phases 1–3 (doc fetched, exploration script run, artefact
+written, decision made): `{"ts":"<iso>","skill":"hiver-explore","action":"...","detail":"..."}`.
+This is the forensic trace of what you did — separate from the output record you write in Phase 4.
+
+### Driver selection
+
+Almost every Hiver feature lives inside Gmail. You reach it by **attaching Claude in Chrome to
+the user's already-open, already-logged-in Chrome session** — the same tab where they manually
+installed the extension build (admiral1/2/3) and opened the account that has the feature
+enabled. Claude in Chrome CAN drive `mail.google.com` this way, because it is driving the real
+authenticated tab rather than launching a fresh one. This is the default `chrome` driver and it
+works for both Gmail (HIG) and `app.hiverhq.com` (Omni).
+
+The connect flow: the user pastes the tab URL, Claude confirms the browser by name, the user
+hits Connect, and Claude then drives that live session.
+
+Use the `playwright` driver instead when **any** of these hold:
+
+- You want a scripted, repeatable capture that produces `.html`/`.png` artifacts for bulk
+  selector extraction.
+- There is no live logged-in Chrome session handy to attach to.
+- You need a clean, isolated persona profile (Tony/Steve/Thor) rather than the user's session.
+
+If unsure, default to `chrome` — it matches how QA actually explores today.
+
+### Phase 0 prereq checks (for the `playwright` driver)
+
+Before proceeding to Phase 1, verify all of these:
+
+1. POC exists at `~/Documents/poc-playwright/` — `ls` it.
+2. `fixtures/auth.fixture.ts` exists at that path.
+3. The chosen persona's baseline profile exists at `fixtures/baseline-profile-<persona>/`.
+   If missing, tell the user: "Run `npm run auth:all` in the POC to seed profiles, then retry."
+4. `scripts/exploration/` exists, or create it with `mkdir -p scripts/exploration`.
+
+If any check fails, stop and tell the user exactly what is missing and the command to fix it.
+Do not proceed to Phase 1 until prereqs pass — Phase 2 will fail catastrophically otherwise.
+
+---
+
+## PHASE 1 — Doc Exploration (help.hiverhq.com)
+
+Use `WebFetch` to read Hiver's public help docs. Build a focused understanding of:
+
+1. **What is this feature** — one-paragraph summary
+2. **Who uses it** — Admin? Agent? Both? Any role-specific behaviour mentioned?
+3. **Plan gating** — HIG, Omni, both? Free tier? Note any plan-specific UI mentioned.
+4. **Entry points** — where in the UI does a user start? (Sidebar link? Right panel? Menu?
+   Compose-time button?)
+5. **Sub-features** — list every distinct action the feature supports (add, edit, delete,
+   pin, search, share, configure, …)
+6. **Settings / configuration** — admin-side configuration options for this feature
+7. **Integrations** — does it touch CRMs, third-party apps, webhooks, automations?
+8. **Edge cases mentioned in docs** — limits, error states, blockers (e.g. "max 50 tags",
+   "requires Omni plan", "not available in shared drafts")
+
+### How to crawl
+
+1. Start at `https://help.hiverhq.com/` and search for the feature name. If the user gave a
+   start URL, begin there instead.
+2. Fetch the landing/overview page. Note all linked sub-pages.
+3. Fetch the **3–8 most relevant sub-pages** breadth-first. Do not blindly chase every link
+   — focus on pages that look like how-tos, settings guides, or troubleshooting for this
+   feature. Skip release notes and pricing pages unless directly relevant.
+4. If you find a page titled "Limitations" or "Known issues" for the feature, always read it
+   — it is gold for edge-case test cases.
+
+### What to write down (private working notes)
+
+Keep a running outline you will use in Phase 3. Mark each fact with its source:
+
+```
+[D] from docs (help.hiverhq.com URL) — fact
+[L] from live UI — fact (to be filled in Phase 2)
+```
+
+Tag everything `[D]` for now. This dual-source tagging lets the qa-kit phase distinguish
+"this is documented" from "this is how it actually behaves" — critical for risk register.
+
+### Phase 1 checkpoint
+
+Print a brief summary to the user:
+
+```
+Docs explored for: <Feature>
+Pages read: <N>
+Sub-features found: <list>
+Roles involved: <Admin/Agent/Both>
+Plans: <HIG/Omni/Both/unclear>
+Notable edge cases from docs: <list>
+Gaps the docs don't cover: <list — anything where docs are silent>
+```
+
+Ask: "Ready to proceed to live UI exploration? I'll attach to your Chrome and click through
+the feature to verify what the docs say and capture real behaviour." Wait for confirmation
+(or for user to say "skip live, go straight to spec").
+
+---
+
+## PHASE 2 — Live UI Structure Capture
+
+Capture structural facts (selectors, navigation order, async timing, quirks) needed by an
+automation script. Do NOT walk every test case — qa-kit Phase 5 handles case-by-case
+verification.
+
+Use the driver selected in Phase 0.
+
+### Driver `playwright` — scripted capture via the POC `authedPage` fixture
+
+Use this when you want a repeatable, artifact-producing capture (see Driver selection above).
+You write a one-off Playwright exploration script, run it headed, and read the artifacts.
+
+**1. Write the script** at
+`~/Documents/poc-playwright/scripts/exploration/explore-<slug>.ts`:
+
+```typescript
+import { test } from '../../fixtures/auth.fixture'
+import { mkdirSync, writeFileSync } from 'fs'
+import path from 'path'
+import { HiverExtensionPage } from '../../pages/hiver-extension.page'
+
+const ARTIFACTS = path.resolve(__dirname, `../../test-results/exploration/<slug>`)
+
+test.describe.serial('<Feature> — exploration', () => {
+  test.setTimeout(240_000)
+
+  test('capture primary path', async ({ authedPage }) => {
+    mkdirSync(ARTIFACTS, { recursive: true })
+    const capture = async (label: string) => {
+      await authedPage.screenshot({ path: `${ARTIFACTS}/${label}.png`, fullPage: true })
+      writeFileSync(`${ARTIFACTS}/${label}.html`, await authedPage.content())
+    }
+
+    await capture('01-loaded')
+
+    const ext = new HiverExtensionPage(authedPage)
+    await ext.openFirstSmConversation()
+    await capture('02-conversation-open')
+
+    // Add feature-specific captures here — one per primary-path step.
+  })
+})
+```
+
+**2. Run it headed** so the user can watch:
+
+```bash
+cd ~/Documents/poc-playwright
+npx playwright test scripts/exploration/explore-<slug>.ts --headed
+```
+
+If the run takes more than ~60s, use `Bash` with `run_in_background: true` and let it
+complete notifying you. Do not poll in a sleep loop.
+
+**3. Read the artifacts**
+
+Use the `Read` tool on each `.html` snapshot to extract selectors, classes, IDs, hidden-state
+markers, and DOM structure. Read `.png` files only when visual inspection is required (e.g.
+to confirm an empty-state vs error-state visual difference).
+
+**Cleanup**: leave the exploration script and artifacts on disk. They become source evidence
+in the spec's Source References. Delete only if the user asks.
+
+### Driver `chrome` (default) — Claude in Chrome attached to your live logged-in session
+
+This drives the real tab the user has already authenticated (Gmail or `app.hiverhq.com`), so it
+reaches Gmail-based features directly. No separate Chromium, no persona profile needed.
+
+1. `mcp__claude-in-chrome__list_connected_browsers` — confirm a browser is attached.
+2. If none attached: stop and tell the user to open Chrome with the Claude in Chrome extension
+   active, open the account/tab that has the feature enabled, and hit Connect.
+3. `mcp__claude-in-chrome__select_browser` and `mcp__claude-in-chrome__tabs_context_mcp` —
+   identify the target tab (the logged-in Gmail or Omni tab).
+4. Confirm the tab is logged in and on the right account before acting. If a `navigate` is
+   blocked or the session is logged out, ask the user to log in / grant access in that tab
+   (or fall back to the `playwright` driver). Do NOT assume Gmail is unreachable — attached to
+   a logged-in session it works.
+
+### Exploration plan
+
+For each sub-feature identified in Phase 1, do ONE focused run:
+
+1. Navigate to the entry point (sidebar link, compose button, right-panel section, etc.)
+2. Take a screenshot before action: `mcp__claude-in-chrome__computer` with screenshot,
+   or `mcp__claude-in-chrome__read_page`
+3. Perform the action (click, fill, select). Use `mcp__claude-in-chrome__find` to locate
+   elements when DOM selectors aren't obvious.
+4. Observe and record:
+   - **DOM state changes** — what appeared, what disappeared, what got disabled
+   - **Async timing** — did the UI flash an intermediate state? Was there a spinner?
+   - **Network calls** — `mcp__claude-in-chrome__read_network_requests` to capture API
+     endpoints hit (useful for qa-kit's environment section)
+   - **Console messages** — `mcp__claude-in-chrome__read_console_messages` for errors or
+     warnings that hint at hidden state machines
+   - **Right-panel injection** — Hiver-specific: does the right panel update for this action?
+     (See HIVER-QUIRKS #19, #38 — right-panel injection is gated on SM context.)
+5. Test at least two edge cases per sub-feature where possible:
+   - Empty / default state (before any data exists)
+   - Max-length / boundary input
+   - Cancel-mid-flow (open dialog, click Cancel, verify clean exit)
+
+### Cross-reference HIVER-QUIRKS.md
+
+For each interaction, ask: "Does this match a known quirk?" If yes, note the quirk number
+in the working notes. If you observe a new quirk (e.g. a click that needs `page.evaluate()`
+because the native click fails, or an async toolbar activation delay), record it in the
+spec's **Live behaviour observations** section so that `playwright-gen` knows to apply the
+workaround upfront.
+
+### Things to capture explicitly
+
+- **Exact CSS / DOM selectors** for each major interactive element (Hiver IDs prefixed
+  with `h-`, class names, role/aria attributes)
+- **Order of operations** that triggers the feature (e.g. "must expand SM first, then
+  open Unassigned, THEN the bulk toolbar appears")
+- **Race conditions visible to the user** (e.g. "toolbar takes 5–15s to activate after
+  selection")
+- **Anything documented in help.hiverhq.com that does NOT match what you see** — flag
+  these as `[D≠L]` discrepancies. These become Risk Register items in the qa-kit phase.
+
+### Phase 2 checkpoint
+
+Print a brief summary:
+
+```
+Live exploration complete for: <Feature>
+Sub-features verified: <N>/<M>
+Doc-vs-live discrepancies found: <list>
+New quirks observed (not in HIVER-QUIRKS.md): <list>
+Selectors captured: <count>
+Edge cases attempted: <list with outcomes>
+Anything that failed to behave at all: <list>
+```
+
+Ask: "Ready to synthesise the spec markdown?" Wait for go-ahead.
+
+---
+
+## PHASE 3 — Synthesise the Feature Spec
+
+Write a single markdown file:
+
+**Path:** `~/Documents/poc-playwright/knowledgebase-claude/features/<slug>.md`
+
+Use the template at `references/spec-template.md`. The template is structured so that when the
+user invokes `/qa-kit` next, that skill's Phase 1 ("Parse the Confluence Page") can ingest this
+file as if it were a Confluence paste — same fields, same shape.
+
+### Required sections
+
+1. **Header** — feature name, slug, date explored, persona used, extension version (read
+   from the extension manifest if accessible, otherwise note "unknown — please confirm")
+2. **Source references** — list of help.hiverhq.com URLs read, plus a note "Live UI observed
+   in <persona>'s session on <date>"
+3. **Problem statement & Goal** — synthesised from docs ("Why does this feature exist?")
+4. **Plans** — HIG / Omni / Both
+5. **In scope / Out of scope** — list the sub-features in scope; explicitly call out related
+   features that are NOT in scope (e.g. "Bulk notes are out of scope — covered in a separate
+   Bulk Actions spec")
+6. **User stories** — one per sub-feature. For each:
+   - Actor (Admin / Agent / Both)
+   - Entry point (where the user starts)
+   - Steps (numbered, user-visible actions)
+   - Source tag: `[D]`, `[L]`, or `[D+L]` (matches docs AND live)
+7. **Core system rules** — invariants the system enforces (e.g. "Notes are visible only to
+   team members on the SM, never to external participants on the email thread")
+8. **Edge cases** — bullet list from docs + live observation
+9. **Constraints & limits** — max lengths, max counts, plan limits
+10. **Integrations** — any CRM, third-party app, webhook touched
+11. **Live behaviour observations** — Hiver-specific UI behaviour that an automation script
+    needs to know upfront:
+    - Selectors for key elements
+    - Async timing that affects test stability
+    - Required navigation order (e.g. "must establish SM context before this UI injects")
+    - Cross-references to HIVER-QUIRKS.md by number
+    - **New quirks not yet in HIVER-QUIRKS.md** — write these as candidate quirk entries
+      (the user can promote them to HIVER-QUIRKS.md after review)
+12. **Doc-vs-live discrepancies** — every `[D≠L]` finding from Phase 2, with source URL
+    and live observation side by side
+13. **Open questions** — anything you couldn't determine from docs OR live UI. These will
+    become qa-kit's Phase 2 clarifying questions later.
+
+### Tone
+
+Write it the way a PM would write a Confluence spec — descriptive, neutral, no test-case
+language ("Verify that…" belongs in qa-kit's output, not here). This document describes the
+**feature**; the test cases come later.
+
+### After writing
+
+Print to the user:
+
+```
+Spec written: <path>
+Sections: <count>  |  User stories: <count>  |  Open questions: <count>
+Doc-vs-live discrepancies: <count>  |  New quirks observed: <count>
+```
+
+Then ask: "Spec ready. Do you want me to hand off to `qa-kit` now to generate the test plan
+and tracker, or do you want to review the spec first?"
+
+---
+
+## PHASE 4 — Handoff to qa-kit
+
+If the user says yes:
+
+1. **Write your output record + handoff to the run dir** (see `handoff-contract.md` + `eval.md`):
+   - `steps/hiver-explore-spec.json` — the step record. `input`: feature + help URLs read.
+     `output`: `{ "artifact": "<spec path>", "summary": "<n sections · n stories · n open-qs>" }`.
+     `self_check`: no unfilled `<placeholders>`? every claim tagged `[D]`/`[L]`? Leave `verdict` null
+     — `qa-eval` fills it.
+   - `handoff.json` — `{ from: "hiver-explore", to: "qa-kit", feature, slug, product (or null),
+     spec_path, open_questions, qa_owner (if known) }`. Copy it to
+     `handoffs/hiver-explore-to-qa-kit.json` for the audit trail.
+   - Append a final `handoff` line to `logs/hiver-explore.jsonl`.
+2. Invoke the `qa-kit` skill (Skill tool, `skill: qa-kit`). **Do NOT paste the spec into chat.**
+   qa-kit reads `qa-output/.current-run` → `handoff.json` → `spec_path`, and loads the spec with
+   `Read` itself. Its Phase 1 ingests the spec as if it were a Confluence paste.
+3. The spec's **Live behaviour observations** section is carried in the handoff, so the downstream
+   run agent can skip re-discovering selectors and timing.
+
+If the user says "let me review first":
+
+- Stop. The run dir, spec, step record, and action log are already on disk. Print the run dir path.
+- Tell the user: "When ready, run `/qa-kit` — it picks up this run from `qa-output/.current-run`."
+
+---
+
+## WHEN TO USE THIS SKILL VS GOING STRAIGHT TO qa-kit
+
+| Situation | Use |
+|---|---|
+| User has a Confluence spec link or pastes the full text | `qa-kit` directly — skip this skill |
+| User has no spec, only the feature name + help.hiverhq.com docs | `hiver-explore` first, then `qa-kit` |
+| User wants to add coverage to a feature already specced in `knowledgebase-claude/features/` | Read the existing spec; if it's older than 30 days OR the user mentions extension version changes, run `hiver-explore` in **refresh** mode to update |
+| User asks "what does <feature> do in Hiver?" with no automation intent stated | Answer from docs only (WebFetch). Do NOT run the full skill. Ask if they want a spec generated. |
+| User mentions a new Hiver feature not yet documented on help.hiverhq.com | Stop. Tell user: "help.hiverhq.com has no coverage for this feature yet. Either share the internal Confluence spec or wait until the help doc is published. I can do live-UI-only exploration if you confirm — but the spec will have gaps." |
+
+---
+
+## CODE QUALITY RULES
+
+- Do not modify `qa-kit` or `playwright-gen` skills. This skill is purely a feeder.
+- Do not write test cases, Playwright code, or page objects in this skill. Stop at the
+  markdown spec.
+- Do not invent behaviour. If something is not in docs AND not observable in live UI, list
+  it as an Open Question, not as a system rule.
+- Every claim in the spec must be tagged `[D]`, `[L]`, or `[D+L]` so the next skill knows
+  the confidence level.
+- Save artefacts (screenshots, DOM dumps) from Phase 2 alongside the spec if the user wants
+  them retained — default is not to retain (the spec text is enough).

package/collections/qa-skills/skills/hiver-explore/references/spec-template.md

@@ -0,0 +1,204 @@
+# Feature Spec Template
+
+This is the markdown template the `hiver-explore` skill produces in Phase 3 and writes to
+`knowledgebase-claude/features/<slug>.md`. It is designed to be ingested by the `qa-kit`
+skill's Phase 1 ("Parse the Confluence Page") with no transformation step.
+
+When filling in the template:
+
+- Replace every `<…>` placeholder with real content. Do not leave bracketed placeholders in
+  the final document.
+- Every factual claim must end with a source tag: `[D]` (docs only), `[L]` (live UI only),
+  or `[D+L]` (matches both).
+- Mark every discrepancy with `[D≠L]` and write doc-side and live-side observations.
+- If a section genuinely doesn't apply to the feature, write `Not applicable.` and a one-line
+  reason. Don't delete the section heading.
+- Use plain English. Avoid testing language like "Verify that…" or "Assert that…" — those
+  belong in qa-kit's output, not here.
+
+---
+
+# `<Feature Name>` — Feature Spec
+
+**Slug:** `<slug>`
+**Date explored:** `<YYYY-MM-DD>`
+**Persona used:** `<Tony / Steve / Thor / other>`
+**Extension version:** `<v7.5.x or "unknown — confirm">`
+**Hiver env / backend:** `<admirals-3 / prod / other — see HIVER-QUIRKS #31>`
+**Status:** Draft from hiver-explore — ready for qa-kit ingestion
+
+---
+
+## Source References
+
+**Docs read:**
+- `<https://help.hiverhq.com/...>` — `<page title>`
+- `<https://help.hiverhq.com/...>` — `<page title>`
+- (list every page actually fetched)
+
+**Live UI session:**
+- Browser: Chrome attached via Claude in Chrome MCP
+- Persona: `<persona>`
+- SM: `<SM_NAME from .env>`
+- Session date: `<YYYY-MM-DD>`
+
+---
+
+## Problem Statement & Goal
+
+`<1–3 sentences describing why this feature exists from the user's perspective>` [D|L|D+L]
+
+**Goal:** `<one sentence — what success looks like for the user>` [D|L|D+L]
+
+---
+
+## Plans
+
+`<HIG / Omni / Both>` [D|L]
+
+(If plan-gating was observed live — e.g. "UPGRADE" placeholder appeared for one persona — note
+that explicitly. Cross-reference HIVER-QUIRKS #32 if Analytics-style upgrade gates are involved.)
+
+---
+
+## In Scope
+
+- `<sub-feature 1>` [D|L|D+L]
+- `<sub-feature 2>` [D|L|D+L]
+- …
+
+## Out of Scope
+
+- `<related but separate feature>` — covered elsewhere or not part of this exploration
+- …
+
+---
+
+## User Stories
+
+### Story 1 — `<short title>`
+
+- **Actor:** `<Admin / Agent / Both>`
+- **Entry point:** `<where the user starts — e.g. "sidebar → SM → Notes tab" or "compose window → Hiver toolbar">` [D|L|D+L]
+- **Steps:**
+  1. `<step 1 — user-visible action>`
+  2. `<step 2>`
+  3. `<step 3>`
+- **Expected end state:** `<what the user sees when done>` [D|L|D+L]
+- **Source:** [D] / [L] / [D+L]
+
+### Story 2 — `<short title>`
+
+… (repeat for every sub-feature observed)
+
+---
+
+## Core System Rules
+
+- `<invariant 1 — e.g. "Notes are visible only to team members on the SM, never to external email participants">` [D|L|D+L]
+- `<invariant 2>` [D|L|D+L]
+- …
+
+---
+
+## Edge Cases
+
+- `<edge case 1 — e.g. "Adding a note with only whitespace shows error 'Note cannot be empty'">` [D|L|D+L]
+- `<edge case 2>` [D|L|D+L]
+- …
+
+---
+
+## Constraints & Limits
+
+| Constraint | Value | Source |
+|---|---|---|
+| `<e.g. Max note length>` | `<5000 chars>` | [D] |
+| `<e.g. Max notes per conversation>` | `<no limit observed>` | [L] |
+
+---
+
+## Integrations
+
+`<List any CRM, third-party app, webhook, or other Hiver feature this touches. If none, write "None observed.">`
+
+Examples to consider:
+- Salesforce / HubSpot lookups
+- Automations / Auto-assign rules
+- SLA policies
+- Tags / Conversation views
+- Out of Office handoff
+
+---
+
+## Live Behaviour Observations
+
+This section is the most valuable handoff to `playwright-gen` later. Capture everything that
+an automation script would need to know upfront to avoid flakes.
+
+### Key selectors
+
+| Element | Selector | Notes |
+|---|---|---|
+| `<element name>` | `<#hiver-id or .class or [aria-label="..."]>` | `<e.g. "Hiver-injected, stable across sessions">` |
+
+### Required navigation order
+
+1. `<e.g. "Expand SM section in sidebar — JS click required in compact mode (HIVER-QUIRKS #22)">`
+2. `<e.g. "Open Unassigned sub-view — wait for tr.zA rows to render">`
+3. `<e.g. "Open conversation — waitForRightPanel() before any feature interaction">`
+
+### Async timing
+
+- `<e.g. "Right panel takes 2–5s to inject after conversation open">`
+- `<e.g. "Bulk toolbar can be CSS-hidden for 5–15s after first selection — see HIVER-QUIRKS #1">`
+- …
+
+### Known quirks that apply
+
+Cross-reference `knowledgebase-claude/HIVER-QUIRKS.md`:
+
+- HIVER-QUIRKS #`<N>` — `<one-line why it matters for this feature>`
+- HIVER-QUIRKS #`<N>` — `<…>`
+
+### New quirks observed (candidate additions to HIVER-QUIRKS.md)
+
+For each, write a complete entry the user can review and promote:
+
+#### Candidate quirk: `<short title>`
+
+**Symptom:** `<what fails or behaves unexpectedly>`
+**Root cause (hypothesis):** `<best guess from what you observed>`
+**Workaround:** `<what made it work in your live session>`
+**Affected features:** `<list>`
+
+---
+
+## Doc-vs-Live Discrepancies `[D≠L]`
+
+| Topic | Docs say | Live shows | Likely cause |
+|---|---|---|---|
+| `<e.g. Note pin limit>` | `<"Pin up to 3 notes" — help.hiverhq.com/…>` | `<Live UI allowed 5 pinned notes>` | `<docs may be outdated; v7.5.x may have lifted the limit>` |
+
+(If none: write "None observed in this session.")
+
+---
+
+## Open Questions
+
+These become qa-kit's Phase 2 clarifying questions:
+
+- `<Q1: what was unclear from docs AND live UI>`
+- `<Q2: behaviour only triggered in edge case we couldn't reproduce>`
+- `<Q3: plan-gating that needs PM confirmation>`
+
+---
+
+## Handoff Notes
+
+- This spec was generated by `hiver-explore` from docs + live UI observation. It has not been
+  reviewed by a PM. Any claim tagged `[L]`-only should be treated as best-effort.
+- `qa-kit` should treat the `Live Behaviour Observations` section as ground truth for its
+  Phase 5 (browser testing) — the selectors and timing are already verified.
+- `playwright-gen` should treat the `Known quirks that apply` and `New quirks observed`
+  subsections as required reading before generating page objects.