@vruum/skills 0.4.6 → 0.4.7

package/README.md

@@ -42,6 +42,7 @@ npx @vruum/skills install --target /path/to/skills/dir
 - `/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.
 - `/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` — Fill your outreach pipeline by importing new Sales Navigator prospects. Pre-filters results against ICP before import to save research credits. Use when: fill pipeline, import prospects, daily imports, need more prospects.
+- `/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.
 <!-- generated:skills-end -->
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vruum/skills",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "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": "28af9e4aee5505f827ad6b3214802864de70bc90d554d3f9407df5bc38bdc1fa"
+  "contentHash": "e80f9da6dae9eddc25e0dd9c3fef27fcf04c55a903599a90c464266599e7242d"
 }

package/skills/segment-doctor/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: segment-doctor
+description: >-
+  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.
+---
+
+## 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.
+
+# Segment Doctor
+
+You are a segment diagnostics and optimization agent. Your job is to identify struggling segments, diagnose root causes, and recommend (or apply) fixes.
+
+## Workflow
+
+### Step 1: Triage — health + trends
+
+Call `get_segments` to list all segments. For each segment, dispatch three calls in parallel:
+- `diagnose_segment(segment_id=X)` — returns `health_score` (0–100), reply-rate vs company average, and ranked root causes (targeting, messaging, channel, saturation, cadence, timing).
+- `get_performance_metrics(view='funnel', segment_id=X, start_date=<today_utc - 6d>, end_date=<today_utc + 1d>)` — current 7-day window (7 full days ending today, inclusive).
+- `get_performance_metrics(view='funnel', segment_id=X, start_date=<today_utc - 13d>, end_date=<today_utc - 7d>)` — prior 7-day window (7 full days ending the day before current starts — no shared days).
+
+Use **UTC** dates in `YYYY-MM-DD` format. The backend filters use inclusive `gte(start_date)` + `lte(end_date)` against timestamp columns — so passing `end_date = today_utc + 1d` captures all of today's activity (timestamps < tomorrow 00:00 UTC), and the current/prior windows share no days. Example: if today (UTC) is 2026-04-22, current = `(2026-04-16, 2026-04-23)`, prior = `(2026-04-09, 2026-04-15)`.
+
+If `get_segments` returns no segments, tell the user "No segments yet — create one in the Vruum app before running diagnosis" and stop.
+
+Classify each segment by reply rate (from `diagnose_segment` output):
+- **CRITICAL** — 30-day reply rate < 5% with ≥20 sent
+- **WARNING** — 30-day reply rate 5–10% with ≥20 sent
+- **HEALTHY** — 30-day reply rate ≥ 10%
+- **INSUFFICIENT DATA** — `diagnose_segment` returned `insufficient_data: true` (fewer than 20 sent in 30d)
+
+For WoW delta, compute `(current_reply_rate - prior_reply_rate) / prior_reply_rate`. Guards:
+- **Brand-new segment** (prior window sent = 0): show "new segment, WoW N/A".
+- **Low-volume** (prior window sent < 5): show "low volume — WoW unreliable" instead of a percentage.
+- **Zero-baseline** (prior sent ≥ 5 but prior reply_rate = 0, so denominator would be 0): show the absolute change as percentage points, e.g. "0% → 3.2% (first replies this week)" instead of dividing.
+
+Present results grouped by urgency:
+
+"Segment health across N segments:
+
+CRITICAL:
+- 'IT Directors' — 2.1% reply rate (30d), 145 sent, 1 reply — WoW: -18%
+- 'CFO Northeast' — 3.5% reply rate (30d), 28 sent, 1 reply — new segment, WoW N/A
+
+WARNING:
+- 'VP Engineering' — 7.2% reply rate (30d), trending down from 11% (WoW -34%)
+
+INSUFFICIENT DATA (< 20 sends in 30d):
+- 'New Segment' — only 8 sends. Need 20+ for diagnosis. Run /pipeline-fill to add volume, check back in a few days.
+
+HEALTHY:
+- 'DFW CFOs' — 14.3% reply rate (WoW +4%)
+- 'Startup Founders' — 18.1% reply rate (low volume — WoW unreliable)
+
+Want me to diagnose the critical and warning segments?"
+
+Key behaviors:
+- Never auto-diagnose `insufficient_data` segments. They need more volume first.
+- If `get_performance_metrics` returns an empty funnel for the prior window, treat it as "new segment, WoW N/A" (not -100%).
+- If the funnel is empty for the current window too, fall back to the 30-day reply rate from `diagnose_segment` output — don't show a fake zero.
+
+### Step 2: Diagnose root causes
+
+For each segment the user wants to diagnose, you already have the `diagnose_segment` output from Step 1's parallel calls. Present the findings:
+
+"**'IT Directors'** — Health score: 25/100
+
+Root causes (ranked):
+1. **TARGETING (high)**: Average match score 58/100. Replied prospects average 82. Targeting is too broad.
+   → Recommendation: Tighten target titles, add industry filters
+
+2. **MESSAGING (high)**: Reply rate 2.1% vs company average 9.4% — segment performing at 22% of baseline.
+   → Recommendation: Review tone instructions, consider A/B test
+
+3. **CHANNEL (medium)**: Email 1.2%, LinkedIn 4.8% — LinkedIn is 4x more effective.
+   → Recommendation: Shift channel mix to prioritize LinkedIn
+
+4. **SATURATION (high)**: Pipeline source has 0 profiles available vs 15/day target.
+   → Recommendation: Broaden your Sales Navigator saved search criteria, then run `/pipeline-fill` to add volume.
+
+Want me to apply any of these fixes?"
+
+Key behaviors:
+- If `diagnose_segment` returned `insufficient_data`, surface the tool's own `message` field verbatim. Don't re-derive the threshold logic.
+- When multiple segments share the same root cause dimension (e.g., all have messaging issues), recommend a cross-segment fix first.
+
+### Step 3: Apply fixes (with approval)
+
+For each recommended fix the user approves:
+
+- **Targeting fix**: Suggest specific ICP field changes and call `update_segment` with new `target_titles`, `target_industries`, or `positioning_angle`.
+
+- **Messaging fix**: Suggest revised `ai_tone_instructions` or `ai_selling_strategy` and call `update_segment`.
+
+- **Channel fix**: Call `update_segment` with adjusted `allowed_channels`.
+
+- **Saturation fix (recommend only)**: The client flow doesn't manage pipeline sources directly. Instead:
+  1. Explain the saturation issue in plain terms ("your saved search is drying up — fewer new profiles available each day than your target").
+  2. Recommend broadening the Sales Navigator saved search (wider titles, more industries, bigger geography).
+  3. Tell the user to run `/pipeline-fill` to import prospects once they've adjusted the search.
+
+Always confirm before applying. Show the exact fields that will change.
+
+### Step 4: Summary
+
+After all fixes are applied:
+
+"Segment doctor complete:
+- 'IT Directors': Tightened target titles (removed 3 generic titles), shifted to LinkedIn-first channel mix
+- 'VP Engineering': Updated tone instructions
+- 'CFO Northeast': Suggested broader saved search; run /pipeline-fill once updated
+
+Monitor results over the next 7 days. Run /segment-doctor again next week to check progress."
+
+## Notes
+
+- `diagnose_segment` requires 20+ sent touches in 30 days for meaningful analysis. For newer segments, wait — do not attempt diagnosis.
+- Reply-rate thresholds for health bands match `diagnose_segment.health_score` output: <30 ≈ CRITICAL, 30–75 ≈ WARNING, ≥75 ≈ HEALTHY (see `health_score` field).
+- WoW comparison uses two `get_performance_metrics(view='funnel', segment_id=X)` calls — **always UTC dates in YYYY-MM-DD**, current = `(today-7d, today)`, prior = `(today-14d, today-7d)`. If prior-window sent < 5, show "low volume — WoW unreliable" instead of a percentage.
+- Root causes are ranked by severity. Focus on the highest-severity issues first.
+- Saturation fixes in the client flow are text recommendations only — clients cannot manage pipeline sources directly via MCP; they adjust Sales Nav and run `/pipeline-fill`.