@vruum/skills 0.2.0 → 0.4.1

package/skills/engagement-triage/SKILL.md

@@ -1,9 +1,22 @@
 ---
 name: engagement-triage
-description: "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."
+description: >-
+  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.
 ---
 
-# /engagement-triage
+## 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.
+
+# Engagement Triage
 
 You review the user's pending LinkedIn engagement drafts (warming comments, nurture reactions, marketing comments) and demand-gen content posts, dispatching review subagents in parallel and presenting results for approval. Separate from `/outreach-triage` (which handles outreach messages).
 
@@ -23,7 +36,7 @@ Falls back to general-purpose subagent with MCP tool names in the prompt if the
 
 ### Step 1: Summarize the queue
 
-Call `get_marketing_overview` (single-company view) to see what's pending. Present a one-liner:
+Call `get_marketing_overview` to see what's pending. Present a one-liner:
 
 "X warming drafts, Y nurture drafts, Z marketing drafts, N content posts pending."
 
@@ -64,84 +77,80 @@ For each queue type the user selected, call the appropriate list endpoint, get I
 
 Spawn up to 4 subagents concurrently. For larger queues (15+), dispatch in waves.
 
-**Subagent prompt — engagement items:**
+Subagent prompt template:
 
 ```
-You are an engagement review agent.
+You are an engagement review agent for {company_name}.
 
-{SENDER PROFILE block}
+SENDER PROFILE:
+{sender_profile_block}
 
-Engagement IDs: {comma_separated_engagement_ids}
-Queue type: {warming | nurture | marketing}
+Engagement IDs: {comma_separated_ids}
 
-Call get_engagement_review with engagement_ids="{ids}" and content_length="full" to load your items. Each item includes the original post, the target persona, match analysis, budget status, bundle info, and the draft comment.
+Call get_engagement_review with engagement_ids="{comma_separated_ids}" and content_length="full" to load your assigned items.
 
-For each item:
-1. Voice fit — does the draft sound like the sender? (check SENDER PROFILE above; flag anything generic or out-of-voice)
-2. Relevance — does the comment add value to the post's conversation, or is it a thin "great post!" type?
-3. Relationship stage — is the engagement appropriate for where you are with this person? (warming = not yet in outreach, nurture = mid-conversation, marketing = brand surfacing)
-4. AI tells — generic phrases, em dashes, overused words, robotic cadence
-5. Strategic fit — is this specific post worth engaging with for this specific person, or is it a thin excuse?
+For each engagement:
+1. Check voice fit against sender profile (would this person actually say this?)
+2. Check relevance to the prospect's post
+3. Check for AI tells (generic phrasing, hollow flattery, buzzwords)
+4. Check for over-pitching (warming comments should NOT sell)
+5. Rate quality: genuine value-add vs generic engagement
 
-If the draft needs editing, call manage_engagement with action=edit. If it's bad enough to drop entirely (off-persona, low-value, stale post), recommend skip.
+If a comment needs fixes, edit it via manage_engagement. Only edit when there's genuine improvement — don't rewrite solid comments.
 
-Return:
-ENGAGEMENT: {id} | TARGET: {person name} | TYPE: {warming|nurture|marketing} | RECOMMENDATION: {approve|edited|skip} | CONFIDENCE: {high|medium|low} | REASONING: {1-2 sentences} | EDITED: {yes/no} | ISSUES_FOUND: {list or "none"}
-```
-
-**Subagent prompt — content posts:**
+IMPORTANT: Do NOT approve or skip engagements. Return recommendations only.
 
+Return a structured summary for each item:
+ENGAGEMENT: {id} | TYPE: {reaction|comment} | PERSON: {name} | SOURCE: {warming|nurture|marketing} | RECOMMENDATION: {approve|edited|flag|skip} | CONFIDENCE: {high|medium|low} | REASONING: {1-2 sentences} | EDITED: {yes/no} | COMMENT_TEXT: {the comment text, or "reaction" for likes}
 ```
-You are a content review agent.
 
-{SENDER PROFILE block}
+For high-value comments (match score 80+, nurture, cold marketing), use research mode: 1 comment per subagent. The subagent reads the prospect's actual post via `get_person_360`, understands what they're saying, and edits only if there's a real opportunity to improve.
 
-Post IDs: {comma_separated_post_ids}
+### Step 5: Present results — always show content
 
-Call get_content_review with post_ids="{ids}" and content_length="full" to load drafts. Each includes the post text, scheduled time, past-performance stats for similar posts, and calendar context.
+Do NOT approve engagements without showing them to the user.
 
-For each post:
-1. Voice fit — sounds like the sender? (SENDER PROFILE above; flag anything generic)
-2. Hook quality — does the first line stop scroll? Is it specific and worth reading further?
-3. AI tells — em dashes, AI-vocabulary ("delve", "robust", "comprehensive"), uniform sentence length, generic openers
-4. Strategic fit — does this post serve the sender's ICP and positioning, or is it generic thought-leadership?
-5. Calendar fit — appropriate timing relative to other recent posts? (get_content_review returns calendar context)
+**Reactions:** Present as a batch with count. "12 warming reactions — all look good. Approve?" If any flagged, show those individually.
 
-If the post needs editing, call manage_content_post with action=edit. If it's bad enough to reject, recommend reject.
+**Comments:** Always show the actual comment text for every comment. Group by recommendation:
 
-Return:
-POST: {id} | SCHEDULED: {time} | RECOMMENDATION: {approve|edited|reject} | CONFIDENCE: {high|medium|low} | REASONING: {1-2 sentences} | EDITED: {yes/no} | ISSUES_FOUND: {list or "none"} | HOOK_RATING: {1-10}
-```
+1. **Clean approvals**: Show comment text and one-line note. User can bulk-approve.
+2. **Edited comments**: Show the new comment, what changed, and why. User reviews each.
+3. **Flagged/skipped**: Show the issue and recommendation.
 
-### Step 5: Present results — show drafts before approving
+**Content posts:** Always show full post text with calendar context and past performance. User approves individually.
 
-Group by recommendation:
+### Step 6: Skip cascade
 
-1. **Clean approvals** — show the draft and a one-line "why it's good". Bulk-approve with one response.
-2. **Edited drafts** — show the new version, what changed, why. User reviews each.
-3. **Skip / reject** — show the draft and the issue. One action to confirm.
+When skipping an engagement because the prospect is a bad fit (not because the comment quality is poor), offer to stop the outreach/warming plan:
 
-For content posts, always walk through one at a time — they're user-visible and higher stakes than a comment.
+"Keith Hemmert (match score 33) — weak fit, no evidence of relevant practice. Skip this engagement and stop warming for this person?"
 
-### Step 6: User overrides
+This bundles skip + stop plan since a bad-fit engagement almost always means warming should stop entirely. Only offer the cascade for fit-based skips, not quality-based edits.
 
-- Pull full context for any item
-- Adjust any subagent edit before approving
-- Skip the whole queue type ("actually, don't review marketing, just warming")
-- Ask to see a specific person's engagement history (`get_engagement_queue` filtered by person_id)
+### Step 7: Early pattern detection
 
-## Edge cases
+After the first batch returns for any engagement type:
 
-**Tiny queue (10 or fewer total):** skip subagents, review inline with the user. Subagent overhead isn't worth it.
+- **All reactions clean:** "First batch of reactions all approved. N more look similar — approve the rest?" Apply without more agents.
+- **All comments have the same issue** (e.g., all too generic, all missing sender voice): Flag the pattern to the user. "First 8 comments are all generic 'great post' style — likely a prompt issue. Want me to edit them all with the same fix, or skip the batch?"
+- **Systematic voice mismatch:** If comments consistently don't sound like the sender, flag it as a segment/prompt config issue rather than fixing each one individually.
 
-**Only warming, no content:** skip Step 4's content-post branch.
+### Step 8: Summary
 
-**Subagent can't reach Vruum MCP:** fall back to inline review. Tell the user: "Subagents can't reach Vruum MCP — run `claude mcp add --transport http --scope user vruum-local https://api.vruum.ai/mcp` once (OAuth), then retry."
+After all queues are processed, present a summary:
+- Total items reviewed
+- Approved (with user confirmation)
+- Edited and approved
+- Flagged for review
+- Skipped
+- Plans stopped (from skip cascades)
+- Content posts approved/scheduled
 
-**User wants to see past performance before approving content:** `get_content_review` already returns past performance stats per post — reference them in your presentation so the user can calibrate.
+## Edge cases
 
-## After triage
+- Queue <= 10 items: skip subagent dispatch, review inline
+- Single item: review directly, no subagents
+- Subagent MCP errors: fall back to inline review
+- **Homogeneous pattern detected**: If first batch all has the same issue, apply fix to remaining without more agents. Confirm with the user first.
 
-Offer:
-- "Want to review your outreach queue next?" (runs `/outreach-triage`)
-- "Check your marketing overview?" (calls `get_marketing_overview` for a recap)

package/skills/engagement-triage/references/content-subagent-instructions.md

@@ -0,0 +1,59 @@
+# Subagent Instructions: Content Post Review Agent
+
+You are reviewing LinkedIn post drafts before they go to a human operator for approval. These posts are public and brand-facing. Quality bar is higher than engagement comments.
+
+## Step 1: Load your posts
+
+Call `get_content_review`. This returns for each post:
+- The draft content, type, tags, status, scheduled date
+- Past performance stats (avg engagement for same content type)
+- Calendar neighbors (other posts within 3 days)
+- Tone instructions from company settings
+
+## Step 2: Review each post
+
+### 2a. Topic freshness
+Check calendar neighbors. If a similar topic was published or scheduled within the last 2 weeks, flag: "similar topic covered recently: [post_id]".
+
+### 2b. Post structure
+LinkedIn posts that perform well:
+- Strong hook in first line (no more than 8 words)
+- White space aggressively used, short paragraphs or single-line statements
+- Ends with a question or clear takeaway, never a CTA to buy
+- No more than 1-2 hashtags
+- No bullet-point overload (3 max)
+
+Flag if: generic opening line, one dense text block, 3+ hashtags, direct product pitch.
+
+### 2c. Brand voice
+Check against `content_tone_instructions`. Common failures:
+- Uses first-person plural ("we've seen") when instructions say first-person singular
+- Too formal when brand voice calls for conversational
+- Uses banned words (moreover, furthermore, additionally, etc.)
+
+### 2d. Factual claims
+If the post makes specific claims (statistics, market sizes), flag as "unverified claim: [the claim]". Do not verify, let the human decide.
+
+## Step 3: Edit if needed
+
+For structural issues (no line breaks, weak hook), use `manage_content_post` with action="edit". For brand voice and factual issues, FLAG rather than edit.
+
+## Step 4: Return structured summary
+
+```
+POST: {post_id}
+CONTENT_TYPE: {original|repost_commentary|video_script}
+SCHEDULED: {scheduled_at or "unscheduled"}
+RECOMMENDATION: {approve | edited | flag | reject}
+CONFIDENCE: {high | medium | low}
+REASONING: {1-2 sentences}
+EDITED: {yes/no}
+ISSUES_FOUND: {comma-separated or "none"}
+---
+```
+
+## Confidence Guide
+
+**HIGH**: Well-structured, on-brand, no duplicate topics, no suspicious claims.
+**MEDIUM**: Needed structural fixes, or topic is adjacent to a recent post but different enough.
+**LOW**: Topic repetition, factual claims to verify, or brand voice issues.

package/skills/engagement-triage/references/engagement-subagent-instructions.md

@@ -0,0 +1,79 @@
+# Subagent Instructions: Engagement Review Agent
+
+You are reviewing AI-generated LinkedIn engagement items (comments, reactions, reposts) before they go to a human operator for approval.
+
+## Step 1: Load your items
+
+Call `get_engagement_review` with your assigned `engagement_ids`, `content_length="full"`. This returns for each item:
+- The draft comment text (if comment or repost_commentary)
+- The reaction type (if reaction)
+- The target post text (what the prospect posted)
+- Person info: name, title, match score, segment, outreach plan status
+- Warming/nurture progress: e.g. "2/4 warming engagements sent"
+- Source: warming, nurture, or marketing
+- ICP match reasoning
+- Budget status for the sender account
+
+## Step 2: Review each item
+
+### 2a. Relevance check
+Does the comment address something specific in the post? A comment that could apply to any post fails.
+- Bad: "Great insights here. Definitely something to think about."
+- Good: "The stat on ramp time resonating, we've seen similar patterns when hiring reps with zero SDR background"
+
+### 2b. AI tell detection
+Comments are short (under 300 chars). They fail fast if robotic.
+Check for:
+- Generic opener ("Great post!", "Loved this!", "So true!")
+- Transition words: moreover, furthermore, additionally
+- Emoji overuse (one is fine, three or more is a tell)
+- Round numbers that feel fabricated ("100% agree")
+- Commenting on something not in the post text (hallucination)
+- Em dashes (banned)
+
+### 2c. Relationship stage fit
+- **Warming**: purely value-add, never reference the outreach company's services. Read like a thoughtful peer.
+- **Nurture**: slightly warmer but still not salesy. Reference shared context only if genuinely relevant.
+- **Marketing**: professional and non-salesy. Represents the sender's professional brand.
+
+### 2d. Reactions
+If engagement_type = reaction, confirm the reaction_type fits:
+- like/thumbs_up: most posts
+- celebrate: milestones/announcements
+- support: challenges/difficulties
+Flag if the reaction type seems wrong for the post context.
+
+### 2e. Budget check
+If `budget_status` shows the sender account is near daily limits, note it in REASONING.
+
+## Step 3: Edit if needed
+
+Use `manage_engagement` with action="edit" and the engagement_id to update content.
+- Keep to 1-3 sentences max
+- Make it specific to the post
+- Sound like a real person's quick reaction
+- No em dashes
+- Vary sentence rhythm
+
+## Step 4: Return structured summary
+
+For each item:
+```
+ENGAGEMENT: {engagement_id}
+PERSON: {person_name} ({person_title})
+TYPE: {comment|reaction|repost_commentary}
+SOURCE: {warming|nurture|marketing}
+RECOMMENDATION: {approve | edited | flag | reject}
+CONFIDENCE: {high | medium | low}
+REASONING: {1 sentence}
+EDITED: {yes/no}
+NEW_CONTENT: {if edited}
+ISSUES_FOUND: {comma-separated or "none"}
+---
+```
+
+## Confidence Guide
+
+**HIGH**: Specific, human-sounding, correctly staged. No edits or minor word changes only.
+**MEDIUM**: Acceptable but substantive edits made, or relationship stage fit is uncertain.
+**LOW**: References things not in the post, clearly generic, or stage fit is wrong. Flag for human.

package/skills/engagement-triage/references/quality-standards.md

@@ -0,0 +1,45 @@
+# Engagement Comment Quality Standards
+
+These apply to LinkedIn comments and reposts in the engagement queue.
+
+## Universal rules
+
+- Never generic: a comment that could apply to any post fails immediately
+- Under 300 characters, hard limit
+- No em dashes, ever
+- No "Great post!", "Love this!", or any pure agreement opener without substance
+- One emoji maximum. Zero is fine.
+- Reference something specific from the post: a number, an example, a named decision
+- No transition words: moreover, furthermore, additionally
+- No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, pivotal
+- Vary sentence rhythm even in short comments
+- Sound like typing fast, not crafting a message
+
+## Warming-specific
+
+- Zero product or service references, ever
+- Read like a thoughtful industry peer, not a vendor
+- Never reference the sender's company by name
+- Never imply prior familiarity unless there is actual history
+
+## Nurture-specific
+
+- Can be slightly warmer than warming
+- May reference shared context only if genuinely relevant
+- Still not salesy. No pitch. No ask.
+
+## Marketing-specific
+
+- Professional and non-salesy
+- Represents the sender's professional brand
+- Can express opinions and takes
+- Can share relevant experience from the sender's domain
+
+## Content post standards
+
+- Strong hook (first line, under 8 words)
+- White space: short paragraphs, single-line punchy statements
+- Ends with a question or clear takeaway, never a CTA to buy
+- 1-2 hashtags maximum
+- No bullet-point overload (3 max)
+- Must match content_tone_instructions from company settings

package/skills/enrich-prospect/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: enrich-prospect
-description: "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."
+description: >-
+  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.
 ---
 
 # /enrich-prospect
@@ -11,7 +15,7 @@ This is not a database lookup. This is an analyst's brief.
 
 ## Step 1: Gather all sources
 
-Call these in parallel with `for_company`:
+Call these in parallel:
 - `get_person_360` — profile, match analysis, research, activity, outreach plan, deal
 - `get_person_research` — structured research data (if exists)
 - `get_company_research` — company intelligence
@@ -19,7 +23,7 @@ Call these in parallel with `for_company`:
 If research is thin (no person_research, or match_analysis is null):
 - `fetch_linkedin_data` — pull their recent posts and profile
 - WebSearch for "[person name] [company name]" — recent news, talks, publications
-- `search_knowledge_base` with `for_company` — relevant sales docs
+- `search_knowledge_base` — relevant sales docs
 
 ## Step 2: Diarize