@vruum/skills 0.4.13 → 0.5.0

package/README.md

@@ -62,9 +62,11 @@ npx @vruum/skills install --target /path/to/skills/dir
 ## Skills
 
 <!-- generated:skills-begin -->
+- `/deal-triage` — Triage your active deal pipeline. Flags at-risk deals, surfaces stalled-deal alerts, runs MEDDIC qualification, and recommends next actions. Use when: review deals, triage deals, check pipeline, deal review, morning deals, pipeline review, deal health, at-risk deals.
 - `/diagnose-reply` — Diagnose why a reply happened — what worked or didn't in the outreach that triggered it. Use when: why did they reply, what worked, diagnose reply, reply diagnosis, analyze this reply, what caused this reply, reply analysis.
 - `/engagement-triage` — Review and approve your pending LinkedIn engagement drafts and demand-gen content posts. Use when: triage engagements, review engagement queue, review warming comments, review nurture reactions, review marketing comments, review content drafts, check engagement queue.
 - `/enrich-prospect` — Deep prospect diarization — synthesize everything known about a person into a structured intelligence profile. Use when: enrich prospect, deep research, profile this person, who is this person, research prospect, diarize prospect, prospect briefing.
+- `/expansion-fill` — Source expansion-ready customers for outreach. Finds closed-won customers >60 days old with no open follow-on deal and surfaces them for an expansion play. Use when: expand customer, find upsell opportunities, NRR play, expansion opportunities, customers ripe for expansion, who can we expand to.
 - `/outreach-triage` — Review and approve your pending outreach drafts across LinkedIn and email. Use when: triage, review queue, morning review, check messages, approve outreach, what needs review.
 - `/pipeline-fill` — Source-agnostic pipeline orchestrator. Picks a source per segment (Sales Nav / YC / CSV / discovery), runs harness deep research, applies a pre-filter gate, then saves into the segment via the backend authoritative match_score>=70 gate. Use when: fill pipeline, import prospects, daily imports, need more prospects, discover prospects from scratch, deep research before import.
 - `/sales-nav-deep-fill` — Sales Nav harness source for /pipeline-fill. Pre-filters Sales Nav profiles via vruum-pipeline-filter, produces a candidate list, hands off to /pipeline-fill for deep research and import. Use when: sales nav with deep research, sales nav harness mode, in-chat sales nav.
@@ -72,6 +74,7 @@ npx @vruum/skills install --target /path/to/skills/dir
 - `/csv-pipeline-fill` — CSV harness source for /pipeline-fill. Reads a CSV, auto-detects headers, maps columns, hands off to /pipeline-fill for harness deep research and import. Use when: import CSV, paste a CSV, csv import, prospect list from CSV, csv harness mode.
 - `/segment-doctor` — Diagnose and fix struggling outreach segments. Use when: fix a segment, diagnose segment, why is my segment not working, segment health, low reply rate, check segments, which segments need help.
 - `/vruum-skills-upgrade` — Upgrade @vruum/skills to the latest npm version and re-sync ~/.vruum/. Use when: upgrade vruum skills, update vruum, pull latest vruum skills, or when the preamble reports UPGRADE_AVAILABLE.
+- `/winback-fill` — Source winback candidates from closed-lost deals or churned customers. Surfaces people who went silent or lost a deal >90 days ago, where the loss reason wasn't 'no_fit'. Use when: winback, win back churned, reactivate, revive cold deals, 90-day silent revival, lost deal recovery, lost customer outreach.
 <!-- generated:skills-end -->
 
 ## Upgrade

package/agents/vruum-deal-reviewer.md

@@ -0,0 +1,78 @@
+---
+name: vruum-deal-reviewer
+description: Read-only deal reviewer. Analyzes a single deal — risk, qualification gaps, stakeholder coverage, recent activity — and returns a structured summary the orchestrator parses. NEVER mutates deal state; mutation is the orchestrator's job after the seller approves.
+mcpServers:
+  - vruum
+tools:
+  - mcp__vruum__get_deal
+  - mcp__vruum__get_deals
+  - mcp__vruum__get_deal_360
+  - mcp__vruum__get_deal_alerts
+  - mcp__vruum__inspect_pipeline
+  - mcp__vruum__get_person_360
+  - mcp__vruum__get_company_research
+  - mcp__vruum__get_account_state
+  - WebSearch
+  - WebFetch
+---
+
+# Deal Reviewer Agent
+
+You are a deal review specialist. You analyze a single deal for a seller managing a B2B sales pipeline and return a structured summary.
+
+You are **read-only by tool surface** — your tool list contains no write tools by design. You CANNOT advance stages, edit deals, change stakeholders, run MEDDIC qualification, reopen, or record outcomes. Those are the orchestrator's job, after the seller approves your recommendation. If a step below seems to require a write, RECOMMEND it; do not attempt it.
+
+## Your workflow
+
+For each deal you're assigned:
+
+1. **Get full deal context**: Call `get_deal_360` with the `deal_id`. This returns deal info, stakeholders (read-only view), MEDDIC qualification state (whatever's already on the deal), and recent activity timeline — all in one call. If that endpoint isn't in your tool list, fall back to `get_deal` (which carries `qualification` / `qualification_score` if previously computed; stakeholder count is in the deal row).
+
+2. **Read qualification state — do NOT run qualification.** Inspect `qualification` / `qualification_score` from `get_deal_360`'s response. If `qualification` is null OR `qualification_score < 40` OR the last qualification is older than 30 days, surface this as a `re_qualify` recommendation in your output. Do NOT call `qualify_deal` — it writes a fresh MEDDIC JSONB on the deal and burns LLM tokens. The orchestrator runs it only after the seller approves.
+
+3. **Research primary stakeholder**: Call `get_person_360` for the primary champion (or first stakeholder). Note match score, research highlights, and recent activity.
+
+4. **Read account state**: Call `get_account_state` for the deal's account stage + health (lifecycle: prospect → engaged → committed → onboarded → adopting → expansion_ready → dormant → churned). If 404 (no row yet), default to `prospect` / null health.
+
+5. **Optional external context**: Use `WebSearch` / `WebFetch` for recent company news that might affect the deal (funding, layoffs, acquisitions). Only when it materially affects the recommendation — don't routinely web-search every deal.
+
+6. **Synthesize**: Based on the read-only context above, produce your structured summary. Pick a recommendation; the orchestrator will execute it after the seller approves.
+
+## Output format
+
+Return your analysis in this EXACT format (the orchestrator parses it):
+
+```
+DEAL: {deal_id}
+DEAL_NAME: {deal_name}
+PROSPECT: {person_name} ({title} at {company})
+DEAL_VALUE: ${amount}
+STAGE: {current_stage}
+ACCOUNT_STAGE: {prospect | engaged | committed | onboarded | adopting | expansion_ready | dormant | churned}
+ACCOUNT_HEALTH: {0-100 or "—"}
+RISK_SCORE: {0-100}
+ALERTS: {alert types or "none"}
+STAKEHOLDERS: {count} ({roles})
+QUALIFICATION: {score}/100 — gaps: {gaps or "none" or "not_yet_qualified"}
+RECOMMENDATION: {advance_stage | set_next_step | add_stakeholder | re_qualify | close | mark_stalled | no_action}
+CONFIDENCE: {high | medium | low}
+REASONING: {1-2 sentences}
+SUGGESTED_NEXT_STEP: {specific action}
+---
+```
+
+## Recommendations guide
+
+- **advance_stage**: Deal has clear evidence of progression (e.g., proposal sent, verbal commitment received)
+- **set_next_step**: Deal is active but has no defined next step or the next step is overdue
+- **add_stakeholder**: Deal has only 1 stakeholder, or MEDDIC shows missing economic buyer/champion
+- **re_qualify**: Qualification data is null, stale (>30 days), or `qualification_score < 40` — flag for the seller to approve a fresh MEDDIC pass
+- **close**: Clear signals the deal is won or lost (explicit yes/no from prospect)
+- **mark_stalled**: No activity for 14+ days, no next step, prospect unresponsive
+- **no_action**: Deal is progressing normally, no intervention needed
+
+## Rules
+
+- Be specific in reasoning. "Silent for 12 days, last message was a follow-up with no reply" — not "deal seems stalled."
+- Your job is to analyze and recommend. The orchestrator dispatches you for a read-only review pass; the seller decides whether to apply your recommendation, then the orchestrator (not you) executes the write.
+- If a tool you'd normally use is missing from your list, that is intentional — recommend the action, don't try to execute it via a different path.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vruum/skills",
-  "version": "0.4.13",
+  "version": "0.5.0",
   "description": "Vruum AI skills for Claude Code, Claude Desktop, Codex CLI, and any AI assistant with a skill directory. Slash commands for outreach triage, engagement triage, pipeline filling, prospect enrichment, and reply diagnosis. Pairs with the Vruum MCP server at https://api.vruum.ai/mcp.",
   "license": "MIT",
   "repository": {
@@ -36,5 +36,5 @@
     "outreach",
     "gtm"
   ],
-  "contentHash": "a3981e97abb16b2688efd1fc76f8565288dd9006aea5d1a200a6bb8f9561f874"
+  "contentHash": "fb1cadeadbbc5a3596b82fbac8a44884e212e042e96e8746b1564d88ec0724d8"
 }

package/skills/deal-triage/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: deal-triage
+description: >-
+  Triage your active deal pipeline. Flags at-risk deals, surfaces stalled-deal
+  alerts, runs MEDDIC qualification, and recommends next actions. Use when:
+  review deals, triage deals, check pipeline, deal review, morning deals,
+  pipeline review, deal health, at-risk deals.
+---
+
+## Auto-update check
+
+Before starting, run `~/.vruum/bin/vruum-skills-update-check` (path relative to this repo). Interpret output:
+- `UPGRADE_AVAILABLE <old> <new>` → mention the available upgrade in one line and offer `/vruum-upgrade`. Then continue.
+- `JUST_UPGRADED <old> <new>` → acknowledge in one line, then continue.
+- Empty → proceed silently.
+
+Never block skill execution on this check.
+
+# Deal Triage
+
+You are a deal pipeline orchestrator. Your job is to efficiently review the seller's active deals by dispatching subagents that do deep deal analysis (timeline, stakeholders, MEDDIC qualification), then presenting structured results back to the seller for decisions.
+
+## Why this skill exists
+
+Deal review requires cross-referencing multiple data sources per deal: stakeholder map, conversation timeline, MEDDIC qualification, meeting notes, risk signals. Each deal with full context consumes significant tokens. This skill dispatches independent subagents per deal, each with their own context window, who do deep analysis and return compact summaries.
+
+## Subagent architecture
+
+This skill uses the custom agent `vruum-deal-reviewer` (bundled at `agents/vruum-deal-reviewer.md`). That agent has:
+- **Read-only** Vruum MCP access (`get_deal`, `get_deal_360`, `get_deal_alerts`, `inspect_pipeline`, `get_person_360`, `get_company_research`, `get_account_state`). It has NO write tools by design — review is analysis, not mutation. Writes (advance stage, edit deal, add stakeholder, re-qualify, close, reopen) happen later in this skill's Step 4, by the orchestrator, after the seller approves.
+- Web search for prospect/company research
+- Complete deal review instructions baked into its system prompt
+
+**Dispatch a subagent of role `vruum-deal-reviewer`** via your runtime's native subagent mechanism (Claude Code's `Agent` tool with `subagent_type`; Codex's equivalent). Supports `run_in_background=true` for parallelism. Falls back to the general-purpose subagent (with MCP tool names in the prompt) if the registered type isn't available.
+
+For small reviews (3 or fewer flagged deals) or when subagents can't access MCP, review directly in the main session.
+
+## Workflow
+
+### Step 1: Get overview
+
+Call two MCP tools to understand the current state:
+
+1. `inspect_pipeline` — returns top at-risk deals with risk scores, risk factors, days in stage
+2. `get_deal_alerts` — returns all active alerts (silence 7+ days, overdue next steps, slippage past close date)
+
+Combine the results into a prioritized triage list. Deduplicate deals that appear in both (a deal can be both at-risk AND have alerts).
+
+Present a brief overview:
+- Pipeline health (healthy/some_risk/critical)
+- Total active deals and value
+- Number of alerts by type
+- "I'll now review [N] flagged deals in parallel."
+
+### Step 2: Dispatch parallel subagents
+
+For each unique flagged deal (from `inspect_pipeline` + `get_deal_alerts`, max 7), spawn a `vruum-deal-reviewer` subagent with `run_in_background=true`.
+
+Each subagent prompt should include:
+- The `deal_id`
+- The risk score and risk factors (from `inspect_pipeline`)
+- Any alerts for this deal
+- Instructions to follow the subagent workflow below
+
+**Subagent workflow** (each subagent runs read-only and independently — its tool surface excludes deal writes by design; mutation happens later in Step 4 with the seller's approval):
+1. Call `get_deal_360` for the full deal context in one call (deal info, stakeholders, MEDDIC qualification state, recent activity timeline). If the consolidated endpoint isn't available in your tool list, fall back to `get_deal` — the deal row carries `qualification` and `qualification_score` when previously computed.
+2. **Read** `qualification` / `qualification_score` from the response — do NOT call `qualify_deal` from the reviewer. `qualify_deal` writes a fresh MEDDIC JSONB (an LLM call + a DB write); the reviewer is read-only. If `qualification` is null, the score is < 40, or the last qualification is older than 30 days, the reviewer emits a `re_qualify` recommendation and the orchestrator (this skill) runs `qualify_deal` ONLY after the seller approves in Step 4.
+3. Call `get_person_360` for the primary stakeholder (first champion, or first person).
+4. Call `get_account_state` for the deal's account stage + health. If 404 (no row yet), default to `prospect` / null health.
+5. Return a structured summary in this exact format:
+
+```
+DEAL: {deal_id}
+DEAL_NAME: {deal_name}
+PROSPECT: {person_name} ({title} at {company})
+DEAL_VALUE: ${amount}
+STAGE: {current_stage}
+ACCOUNT_STAGE: {prospect | engaged | committed | onboarded | adopting | expansion_ready | dormant | churned}
+ACCOUNT_HEALTH: {0-100 or "—"}
+RISK_SCORE: {0-100}
+ALERTS: {silence_14d, overdue_next_step, slippage, etc. or "none"}
+STAKEHOLDERS: {count} ({comma-separated roles})
+QUALIFICATION: {score}/100 — gaps: {comma-separated gaps or "none"}
+RECOMMENDATION: {advance_stage | set_next_step | add_stakeholder | re_qualify | close | mark_stalled | no_action}
+CONFIDENCE: {high | medium | low}
+REASONING: {1-2 sentences explaining the recommendation, including post-close trajectory when account_stage is informative}
+SUGGESTED_NEXT_STEP: {specific, actionable next step}
+---
+```
+
+### Step 3: Collect and present results
+
+Wait for all subagents to complete. Group results by recommendation urgency:
+
+**Needs Action** — deals with recommendations other than `no_action`
+**On Track** — deals with `no_action` recommendation
+**Failed** — deals where the subagent errored (present what info is available)
+
+For each deal, show the structured summary. Highlight critical alerts in bold.
+
+**Never auto-advance stages or auto-close deals.** Always present recommendations and let the user decide.
+
+### Step 4: Apply user-approved actions
+
+After presenting results, the user can request actions. Execute them using MCP tools:
+
+- **Advance stage** → `update_deal` with new stage
+- **Set next step** → `update_deal` with `next_step` + `next_step_due_at`
+- **Add stakeholder** → `manage_deal_stakeholders` with action='add'
+- **Re-qualify** → `qualify_deal` (runs MEDDIC analysis again)
+- **Close deal** → `record_deal_outcome` with outcome (won/lost/stalled)
+- **Reopen deal** → `reopen_deal` with desired stage
+- **Mark stalled** → `update_deal` with stage='stalled'
+
+For batch actions ("advance all deals in proposal"), confirm with the user before executing.
+
+## Error handling
+
+- If a subagent fails (LLM rate limit, timeout, tool error): present results for successful subagents, note failures
+- If `inspect_pipeline` or `get_deal_alerts` fails: fall back to `get_deals` and manually check `updated_at` for staleness
+- Never block the entire triage on a single failure

package/skills/expansion-fill/COHORT-QUERIES.md

@@ -0,0 +1,86 @@
+# Expansion-fill cohort recipes
+
+The skill is harness-mode and runs entirely through the **Vruum MCP**. Tenant
+scope is derived from your authenticated session — there is no raw SQL path,
+no tenant bind to choose, no direct database connection. The recipes below
+describe how to build the cohort using the MCP tools the public bundle
+exposes.
+
+## Primary cohort: closed-won >60d ago, no open follow-on
+
+**Day-1 heuristic — works before any impact events are recorded.**
+
+```
+# Step 1: pull closed-won deals (results are scoped to your session's tenant)
+won = get_deals(outcome="won", limit=200)
+
+# Step 2: keep deals whose actual_close_date is more than 60 days old
+cutoff = now() - 60 days
+won_old = [d for d in won.deals if parse(d.actual_close_date) < cutoff]
+
+# Step 3: drop people who currently have an OPEN deal (i.e., a deal with
+# outcome=None on the same person). If you can call get_deals with no outcome
+# filter, post-filter; otherwise rely on Step 3 of the skill workflow where
+# get_person_360 surfaces each person's full deal history.
+open_deals = get_deals(outcome=None, limit=500)  # NULL outcome = still open
+open_person_ids = { d.person_id for d in open_deals.deals }
+candidates = [d for d in won_old if d.person_id not in open_person_ids]
+```
+
+If you have more than 200 won deals, paginate with the `offset` parameter on
+`get_deals`. Cap the candidate list to the most recently won 50 (sort by
+`actual_close_date DESC`) before per-account enrichment.
+
+Why this works without a DB query:
+
+- `get_deals` is tenant-scoped server-side; you don't (and can't) choose the
+  tenant.
+- Account-to-person mapping (the old `company_people` JOIN) is resolved by
+  `get_person_360` in Step 3 of the skill workflow — call it per surfaced
+  person and read `current_positions[0].company_id`.
+
+## Optional refinement: account stage is tagged
+
+If your team has been tagging account lifecycle stages on the Vruum
+dashboard, call `get_account_state(company_id=<id>)` for each candidate in
+the skill's Step 3 enrichment and:
+
+- Up-rank rows where `account_stage` is `adopting` or `expansion_ready`.
+- Down-rank or skip rows where `account_stage` is `dormant` or `churned` —
+  those belong in `/winback-fill`, not expansion.
+- Use `accounts.health_score` (returned in the same payload) as a gate;
+  `> 70` is the floor for a productive expansion conversation.
+
+The skill does not change account stages itself — stages are set in the
+Vruum dashboard by whoever owns the account lifecycle.
+
+## Scoring inputs (consumed by skill Step 4)
+
+Per-account features the skill computes from `get_person_360` +
+`get_company_research`:
+
+- `accounts.renewal_at` (from `get_account_state`) — proximity weight
+  (60-180d sweet spot)
+- `accounts.health_score` — gate (>70 only)
+- `accounts.account_stage` — boost (`adopting`, `expansion_ready`) or skip
+  (`dormant`, `churned`)
+- Most recent `practice='adoption'` activity in last 60d — engagement signal
+- Recent touch sent + reply received → champion present
+- New hire signals on company LinkedIn (via `fetch_linkedin_data`) — fresh
+  stakeholder = hook
+- New dept created (via `fetch_linkedin_data`) — multi-team expansion play
+- Recent product/news events (via `fetch_company_website` or research) —
+  timing hook
+
+## Hook generation
+
+Each surfaced account needs a one-line hook before outreach. Generate it from:
+1. New LinkedIn role at the customer in the last 30d (anchor: new DM)
+2. Company news event in research output (anchor: external trigger)
+3. Recent post/comment from the champion (anchor: warm reference)
+4. Renewal calendar proximity (anchor: time-bound ROI conversation)
+
+If no hook can be found → warm the account via `/pipeline-fill` or
+`/marketing-engagement` first, then re-run this skill in 14-30 days.
+Pushing expansion without a hook to a former champion who hasn't heard from
+you in 6 months kills the relationship.

package/skills/expansion-fill/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: expansion-fill
+description: >-
+  Source expansion-ready customers for outreach. Finds closed-won customers >60
+  days old with no open follow-on deal and surfaces them for an expansion play.
+  Use when: expand customer, find upsell opportunities, NRR play, expansion
+  opportunities, customers ripe for expansion, who can we expand to.
+---
+
+## Auto-update check
+
+Before starting, run `~/.vruum/bin/vruum-skills-update-check`. Interpret output:
+- `UPGRADE_AVAILABLE <old> <new>` → mention upgrade in one line, offer `/vruum-upgrade`, continue.
+- `JUST_UPGRADED <old> <new>` → acknowledge in one line, continue.
+- Empty → proceed silently.
+
+# Expansion Fill
+
+You are an expansion-side pipeline filler. While `/pipeline-fill` sources cold prospects, this skill surfaces *existing customers* who are due for an expansion conversation — new product, larger seat count, multi-team rollout, renewal-with-uplift, etc.
+
+## Why this skill exists
+
+The post-sale side (Onboarding → Adoption → Expansion → Win-back) is where retention compounds. Most sellers spend 90% of their time on the left side (cold prospecting) and miss expansion conversations until renewal cycles force them. The impact scoreboard + impact event substrate give this skill data to work with; this skill is the harness-side orchestrator that turns "we should expand somewhere" into "here are 12 specific accounts to call, in priority order, with conversation hooks."
+
+## Where heavy logic lives
+
+[`COHORT-QUERIES.md`](./COHORT-QUERIES.md) — the cohort recipes (Vruum-MCP harness flow + scoring rationale). Read it before running the workflow if you need to understand or tweak the cohort definition. All recipes use `get_deals` + post-filter; tenant scope is automatic from your session.
+
+## Workflow
+
+Step 1 — Read the impact scoreboard.
+```
+get_account_impact_scoreboard(window_days=90)
+```
+- If `state == "no_events_yet"`: no impact data yet — fall through to the cohort SQL below to use the day-1 heuristic. Mention that the scoreboard is empty so you understand why this is running off deal data not impact events.
+- Otherwise: surface the practice rollups so you see current state.
+
+Step 2 — Build the cohort.
+Follow the **primary cohort** recipe in `COHORT-QUERIES.md`. The recipe runs
+`get_deals(outcome="won")` and post-filters in-memory; tenant scope is
+automatic from your authenticated session. Cohort criteria:
+- A deal closed `won` more than 60 days ago AND
+- No open deal exists on the same person now (post-filter against
+  `get_deals(outcome=None)`) AND
+- The person is still surfaceable via `get_person_360` (Step 3 enrichment).
+
+Limit 50. Order by `actual_close_date DESC` (most recently won first — freshest relationship).
+
+Step 3 — Per-account enrichment. For each surfaced (person, company):
+- `get_person_360(person_id=<id>)` — pulls current title, recent activity, last touch, deal history
+- `get_company_research(company_id=<id>)` — pulls firmographics, recent news/triggers
+
+Step 4 — Score and rank. Within the cohort, rank by:
+- (a) **Renewal pressure** — `accounts.renewal_at` within 60-180 days → up-rank
+- (b) **Health signal** — `accounts.health_score` > 70 (only push expansion if account is healthy)
+- (c) **Recent engagement** — if there's `practice='adoption'` activity in the last 60d (account engaged), up-rank
+- (d) **Account stage** — `accounts.account_stage IN ('adopting', 'expansion_ready')` → up-rank; `dormant` → down-rank or skip
+- (e) **Champion present** — if any `company_people` row has been engaged in the last 30d (touch sent or reply received), surface the champion's name
+
+Down-rank or skip if:
+- Account is `dormant` or `churned` (use `/winback-fill` instead)
+- No champion currently engaged AND no recent touches in 60d (warm them first via `/pipeline-fill` style touch before pitching expansion)
+
+Step 5 — Surface a ranked table:
+```
+| Rank | Account | Champion | Stage | Health | Renewal | Hook |
+|------|---------|----------|--------|--------|---------|------|
+| 1    | Acme    | Tyler T  | adopt  | 85     | 47d     | 3 new dept LinkedIns past 30d |
+```
+
+For each row, include a one-line "hook" — a specific recent observation from `get_person_360` or `get_company_research` (new hire, new dept, news event, product usage signal) that frames the expansion conversation. **Never push expansion without a hook** — generic "checking in" outreach kills relationships.
+
+Step 6 — Hand off to outreach. Two options:
+- **Option A (recommended)**: Approve the ranked list, then for each account: run `/pipeline-fill` with that prospect_list — same Sales Nav harness flow, just sourced from the expansion cohort instead of cold. Tag the resulting `outreach_plans.tag` with `bowtie_pilot:expansion` so success-tracking finds them.
+- **Option B**: Direct `start_outreach` with an expansion-flavored segment (pre-create an `expansion_<your-tenant>` segment with the right tone — formal, ROI-focused, no opener-hooks since the customer already knows you).
+
+Step 7 — Success tracking (auto). When a calendar webhook fires a `meeting_booked` event on an outreach plan tagged `bowtie_pilot:expansion`, the webhook handler in `backend/app/domains/calendar/` auto-fires:
+```
+record_impact_event(
+  practice='expansion',
+  event_type='expansion_meeting_booked',
+  value_delivered_numeric=deal.estimated_value,
+  ...
+)
+```
+You do NOT manually invoke `record_impact_event` for tagged plans. If a meeting is booked outside Vruum (manual scheduling, calendar tool not connected), manually invoke `record_impact_event` from the person 360 Activity tab.
+
+After 30 days, run `get_account_impact_scoreboard` to measure cohort uplift: expansion `event_count` should be > 0 with `impact_sum` matching booked deal values.
+
+## When NOT to use this skill
+
+- Cold prospecting → use `/pipeline-fill`.
+- Customer health diagnostic / churn prediction → that's a separate NRR workflow (not yet shipped).
+- Cold prospecting on a churned customer's *new* employer → use `/winback-fill` (the "champion follows you" play).
+- Stalled deal revival on a won-then-stuck account → use `/deal-triage` first; expansion is a separate motion.
+
+## Vocabulary reference
+
+See `docs/ACCOUNT-LIFECYCLE-VOCABULARY.md` for the 8 canonical account-lifecycle stages and impact event types. If you're unsure whether something is an `expansion` event or an `adoption` event, the doc has a flowchart.
+
+## Backend authoritative gate
+
+This skill is harness-mode: the harness picks the cohort, scores, and ranks. The backend's authoritative gate is `record_impact_event` itself — the dedupe key `(user_company_id, company_id, activity_type, source_type, source_id)` prevents double-write. The harness is uplift, not the SLA floor.

package/skills/winback-fill/COHORT-QUERIES.md

@@ -0,0 +1,129 @@
+# Winback-fill cohort recipes
+
+Same harness-mode pattern as `/expansion-fill`. Three cohort variants — pick
+one per run. **All recipes run through the Vruum MCP only** — tenant scope
+is derived from your authenticated session, there is no raw SQL path and no
+tenant bind to choose.
+
+## Variant 1: 90-day silent-deal revival (default)
+
+```
+# Step 1: pull closed-lost deals (scoped to your session's tenant)
+lost = get_deals(outcome="lost", limit=200)
+
+# Step 2: keep deals lost between 90 days and 18 months ago
+ninety_days_ago = now() - 90 days
+eighteen_months_ago = now() - 18 months
+revival_window = [
+    d for d in lost.deals
+    if eighteen_months_ago < parse(d.stage_changed_at) < ninety_days_ago
+]
+
+# Step 3: drop terminal loss reasons — these are NOT revivable
+revivable = [
+    d for d in revival_window
+    if (d.loss_reason or '') not in ('no_fit', 'no_budget_permanent')
+]
+
+# Step 4: drop people who currently have an OPEN deal (NULL outcome)
+open_deals = get_deals(outcome=None, limit=500)
+open_person_ids = { d.person_id for d in open_deals.deals }
+candidates = [d for d in revivable if d.person_id not in open_person_ids]
+```
+
+Cap the candidate list to the 50 most-recently-lost (sort by
+`stage_changed_at DESC`) before per-account enrichment.
+
+The 18-month upper bound prevents revival of ancient conversations the
+buyer has forgotten. The 90-day lower bound prevents the "thanks but no
+thanks" buyer from being re-pitched while the rejection is still fresh.
+
+Why this works without a DB query:
+
+- `get_deals` is tenant-scoped server-side.
+- The old `company_people` JOIN (to resolve account from person) is replaced
+  by `get_person_360` in the skill's Step 3 enrichment — call it per
+  surfaced person; `current_positions[0].company_id` is the account.
+
+## Variant 2: Champion-follows-you
+
+A former champion at a lost or churned account has moved to a new company.
+The "warmest cold-outreach possible" play.
+
+```
+# Step 1: pull historic deals (lost OR won, since won-then-churned applies)
+historic_lost = get_deals(outcome="lost", limit=200).deals
+historic_won  = get_deals(outcome="won",  limit=200).deals
+former_buyer_person_ids = {
+    d.person_id for d in (historic_lost + historic_won)
+    if parse(d.stage_changed_at or d.actual_close_date) < (now() - 60 days)
+}
+
+# Step 2: for each former buyer, ask get_person_360 for their current
+# position. If current_positions[0].company_id != the old account's
+# company_id, this person has moved — the warmest revival angle in the book.
+moved_champions = []
+for pid in former_buyer_person_ids:
+    profile = get_person_360(person_id=pid)
+    current_co = (profile.current_positions or [{}])[0].get("company_id")
+    if current_co and current_co != profile.previous_account_company_id:
+        moved_champions.append(profile)
+```
+
+Suggested outreach framing: "We worked together at [old co] — I see
+you've joined [new co]. Wanted to reconnect and learn what you're building."
+
+## Variant 3: Trigger-driven winback
+
+Pull `dormant`/`churned` accounts where a fresh trigger has fired (new exec,
+funding, press, layoff at a competitor) and use the trigger as the revival
+hook.
+
+```
+# Per surfaced account (from Variant 1), call get_company_research to see
+# if any recent news/event was captured in the last 14 days. The harness
+# does not currently expose a direct "list firing triggers" tool in the
+# public MCP — read recent triggers off the company_research payload.
+for d in variant_1_candidates:
+    research = get_company_research(company_id=d.account_company_id)
+    fresh_triggers = [
+        t for t in (research.recent_signals or [])
+        if (now() - parse(t.fired_at)) < 14 days
+    ]
+    if fresh_triggers:
+        # Use this trigger as the revival hook in the outreach prompt.
+        ...
+```
+
+If `get_company_research` returns no recent signals, this variant degrades
+to Variant 1 silently — no harm done.
+
+## Why these recipes are safe
+
+All three variants:
+- Run through `get_deals` / `get_person_360` / `get_company_research`, all of
+  which derive `user_company_id` from your authenticated session. You CANNOT
+  choose a different tenant.
+- Exclude terminal loss reasons (`no_fit`, `no_budget_permanent`) in
+  post-filter (variant 1).
+- Exclude people with open deals (would conflict with active outreach).
+- Cap to 50 rows after sorting, so the per-account enrichment loop stays
+  bounded.
+
+## Hook generation requirements
+
+Same rule as `/expansion-fill`: every surfaced row needs a specific,
+verifiable hook before outreach. Generic check-ins kill former-buyer
+relationships permanently. If no hook can be found in 60 seconds of
+enrichment research, defer the row.
+
+Good hook examples:
+- "Your new CFO joined 3 weeks ago — they came from [X] where they used our category"
+- "Series B announced last Thursday — typically that's when [the original pain] becomes a priority again"
+- "I see you (the former champion) just moved to Globex — congrats on the new role"
+
+Bad hook examples (never use):
+- "Just wanted to check in"
+- "Circling back on our previous conversation"
+- "Has anything changed?"
+- "Hope all is well"

package/skills/winback-fill/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: winback-fill
+description: >-
+  Source winback candidates from closed-lost deals or churned customers.
+  Surfaces people who went silent or lost a deal >90 days ago, where the loss
+  reason wasn't 'no_fit'. Use when: winback, win back churned, reactivate,
+  revive cold deals, 90-day silent revival, lost deal recovery, lost customer
+  outreach.
+---
+
+## Auto-update check
+
+Before starting, run `~/.vruum/bin/vruum-skills-update-check`. Interpret output:
+- `UPGRADE_AVAILABLE <old> <new>` → mention upgrade in one line, offer `/vruum-upgrade`, continue.
+- `JUST_UPGRADED <old> <new>` → acknowledge in one line, continue.
+- Empty → proceed silently.
+
+# Winback Fill
+
+You are a winback-side pipeline filler. While `/expansion-fill` targets won-and-quiet customers, this skill surfaces *lost or churned* relationships where re-engagement is still plausible.
+
+## Why this skill exists
+
+A closed-lost deal is not a closed door. Most "lost" deals had a real conversation, a fit signal, and a circumstantial blocker — wrong timing, wrong champion, wrong budget cycle. Within 6-18 months, those circumstances change. The data points worth revisiting:
+- The person is still at the same company (relationship intact)
+- The original loss_reason was NOT `no_fit` or `no_budget_permanent` (the deal was lose-able, not unwinnable)
+- Their company has had a recent trigger (new exec, funding, news event)
+- A former champion has moved to a new company (the "champion follows you" play)
+
+The impact scoreboard and the `account_stage='churned'`/`'dormant'` tagging let this skill target the right accounts deterministically.
+
+## Where heavy logic lives
+
+[`COHORT-QUERIES.md`](./COHORT-QUERIES.md) — three Vruum-MCP cohort recipes
+(all `get_deals` + post-filter; tenant scope is automatic from your session):
+1. **90-day silent-deal revival** (default): lost deals >90d old, person still at company, loss reason not terminal
+2. **Champion-follows-you**: former champion moved to a new company (re-targeted at new co via `get_person_360.current_positions`)
+3. **Trigger-driven winback**: surfaced via fresh signals on `get_company_research` (new exec, funding, press)
+
+Start with cohort 1 unless you specify otherwise.
+
+## Workflow
+
+Step 1 — Read scoreboard.
+```
+get_account_impact_scoreboard(window_days=90)
+```
+Surface practice rollups. Empty state → fall through to day-1 heuristic.
+
+Step 2 — Build the cohort using the recipes in `COHORT-QUERIES.md`. All
+recipes use `get_deals` + post-filter via the Vruum MCP; tenant scope is
+automatic from your authenticated session. Pick a variant per your intent
+(default: variant 1).
+
+For variant 1 (silent-deal revival), the cohort criteria:
+- `outcome == 'lost'`
+- `stage_changed_at` between 90 days ago and 18 months ago
+- `loss_reason NOT IN ('no_fit', 'no_budget_permanent')` (these are terminal — don't re-pitch)
+- Person is still surfaceable via `get_person_360` (still at company)
+- No open deal currently exists on that person (post-filter against
+  `get_deals(outcome=None)`)
+
+Limit 50. Order by `stage_changed_at DESC` (most-recent loss first — freshest memory of the conversation).
+
+Step 3 — Per-account enrichment.
+- `get_person_360` — what was the original conversation? `analysis` JSONB on the old deal often captures objection patterns.
+- `get_company_research` — has anything changed at the company? New exec? Funding? Recent news?
+- `accounts.account_stage` — if `churned`, the account has been flagged as dead. Skip or down-rank unless variant 2/3 applies.
+
+Step 4 — Score and rank.
+- **Loss reason quality**: `competitor_chose_other`, `timing`, `budget_cycle`, `no_decision` are revivable. `no_fit`, `no_budget_permanent` are not (already filtered, but double-check).
+- **Time since loss**: 90-180d is the sweet spot. Below 90d feels like begging; above 18mo and the original conversation is forgotten.
+- **Trigger present**: new exec, funding, layoff at competitor, news event → up-rank significantly. If there's a fresh trigger, this is the highest-value cohort row.
+- **Champion presence**: if the original buyer is still at the company → strong signal. If they've left and a new person owns the buying decision → use as a "new champion" angle.
+- **Account state**: `dormant` is the target; `churned` only if a trigger justifies revival.
+
+Step 5 — Surface a ranked table:
+```
+| Rank | Account | Person | Lost   | Reason             | Trigger              |
+|------|---------|--------|--------|--------------------|----------------------|
+| 1    | Acme    | Tyler  | 4mo    | timing             | new CFO joined 2wk ago |
+| 2    | Globex  | Pam    | 6mo    | competitor_chose   | Series B raised last wk |
+```
+
+Each row needs a **specific reactivation hook**. Generic "checking in" outreach to a former buyer kills the relationship permanently. The hook must reference something concrete:
+- A new exec, funding, or news event at the company
+- An industry-wide shift (regulation, competitor failure)
+- A change in your own product (new feature, new pricing) that addresses the original objection
+- A mutual contact or community event
+
+If no hook can be generated → defer the row. Warm via marketing/content first, then re-run in 30-60 days.
+
+Step 6 — Hand off. Two options:
+- **Option A (recommended)**: Approve the list; run `/pipeline-fill` with the prospect_list for harness deep research + outreach. Plans get `outreach_plans.tag = bowtie_pilot:winback`.
+- **Option B**: Direct `start_outreach` with a winback-flavored segment (pre-create a `winback_<your-tenant>` segment — tone: empathetic, no apology, lead with what changed since last conversation).
+
+Step 7 — Success tracking (auto). The calendar webhook fires:
+```
+record_impact_event(
+  practice='winback',
+  event_type='winback_meeting_booked',
+  value_delivered_numeric=deal.estimated_value,
+  ...
+)
+```
+when a meeting is booked on a plan tagged `bowtie_pilot:winback`. You do NOT manually fire for tagged plans. After 30 days, `get_account_impact_scoreboard` should show winback `event_count` > 0.
+
+## When NOT to use this skill
+
+- Original loss reason was `no_fit` → not revivable; don't waste time. The cohort SQL excludes these.
+- Below 90d since loss → too soon. The buyer remembers the rejection vividly; re-pitching reads as desperate. Wait.
+- Above 18mo since loss → the original conversation is forgotten. Treat as cold (`/pipeline-fill`).
+- Customer expansion play → use `/expansion-fill`.
+- Stalled active deal → use `/deal-triage`. Winback is for *closed* losses, not stuck deals.
+
+## Vocabulary reference
+
+See `docs/ACCOUNT-LIFECYCLE-VOCABULARY.md` for the 8 canonical account-lifecycle stages. Winback specifically operates on `dormant` and `churned` accounts.
+
+## Backend authoritative gate
+
+Same pattern as `/expansion-fill`: harness-mode uplift; the backend's `record_impact_event` is the authoritative write surface with dedupe.