poc-analysis

# POC Analysis Skill ## Required Environment Variables - `HUBSPOT_ACCESS_TOKEN` — HubSpot private app token (needs deals read scope) - `METABASE_API_KEY` — Metabase API key - `POC_BOT_SLACK_TOKEN` — Slack bot OAuth token (`xoxb-...`) - `SLACK_CHANNEL` — Target channel (default: `#poc-bot`) ## Workflow ### Step 1: Fetch Data Run the fetch script to pull all companies and their Metabase metrics: ```bash python3 scripts/fetch_poc_data.py ``` Dashboard cards, output labels, and parameter bindings are defined in `config/metabase_cards.json` (override the path via `METABASE_CARDS_CONFIG`). With the default labels, this writes `/tmp/poc_data.json` containing, per company: - `name`, `team_id`, `demo_held_date`, `date_range` (demo date → today) - `usage_overview`: `total_primary_metric`, `users_on_team`, `active_users`, `wau`, `primary_feature_wau`, `secondary_feature_wau` - `user_breakdown`: `users_active_days` (aggregate per user), `users_daily_activity` (per user per day) See `references/metabase_config.md` for the full column schemas for these tables. ### Step 2: Analyze Before analyzing, read `config/methodology.md` for this deployment's primary metric definition, user tier criteria, and summary framing guidance. For each company in `/tmp/poc_data.json`: **Usage Overview (from `usage_overview`):** - Compute the activation rate and call out the primary metric total prominently - Trace each weekly trend column week-over-week to identify growth, plateau, or decline - Note any significant divergence between the general engagement trend and the primary metric trend **User Breakdown — categorize users into tiers (criteria in `config/methodology.md`):** - **Power users**: high primary metric, high activity signal - **Mid-tier**: moderate primary metric, consistent presence - **Core-only**: active `days_active` but near-zero primary metric — using the product but not its key value feature; note as a growth opportunity - **Joined but inactive**: low `days_active`, `last_active_day` is recent but usage is minimal - **Never used**: `last_active_day` is null **Daily activity trends** (from `users_daily_activity`): - Identify users who started strong then fell off - Identify users who started slow but are ramping - Note bursty vs. consistent usage patterns - Highlight if a user's primary metric usage is concentrated vs. broad ### Step 3: Write Analysis JSON Write `/tmp/poc_analysis.json` — a list of objects, one per company: ```json [ { "company": "<Company Name>", "text": "POC Analysis: <Company Name>", "blocks": [ ...Slack Block Kit JSON... ] } ] ``` **Block Kit structure per company (in order):** 1. `header` block — company name and date range 2. `section` with `fields` — key metrics: team size, active users, activation %, primary metric total, WAU trend, primary-feature WAU trend 3. `divider` 4. `section` — Power users bullet list 5. `section` — Mid-tier users bullet list 6. `section` — Engagement snapshot (core-only + inactive + never-used) 7. `section` — Summary (1–2 sentence synthesis of notable trends and patterns) Keep each section block under 3,000 characters. Use `*bold*` for names and metric values. ### Step 4: Post to Slack ```bash python3 scripts/post_to_slack.py ``` Reads `/tmp/poc_analysis.json` and posts one top-level message per company to `$SLACK_CHANNEL`. ## Reference - Metabase dashboard structure, card IDs, and metric definitions: `references/metabase_config.md`