poc-not-customer-usage

# Active Enterprise PoC 30-Day Usage Skill See `config/methodology.md` for the primary metric definition, cohort logic, and display configuration for this deployment. Metabase parameter bindings and warehouse table/column names are configured in `config/data_sources.json` (override the path via `DATA_SOURCES_CONFIG`). ## Required Environment Variables - `GENERAL_HUBSPOT_APP_TOKEN` or `HUBSPOT_ACCESS_TOKEN` — HubSpot private app token for company owner enrichment (prefers `GENERAL_HUBSPOT_APP_TOKEN`) - `METABASE_API_KEY` — Metabase API key - `POC_BOT_SLACK_TOKEN` — Slack bot OAuth token (`xoxb-...`) - `SLACK_CHANNEL` — Target channel (default: `#poc-bot`) ## Optional Environment Variables - `PRIMARY_METRIC_LABEL` — display label for the primary metric (default: `primary metric`) - `PRIMARY_METRIC_EMOJI` — Slack emoji for the primary metric (default: `:bar_chart:`) - `DATA_SOURCES_CONFIG` — path to the data sources config file (default: `config/data_sources.json` inside the skill) - `DB_TEAMS_FACTS_TABLE` / `DB_SERVICE_AGREEMENTS_TABLE` / `DB_ENTERPRISE_DEALS_TABLE` — override the warehouse table names from `config/data_sources.json` - `DB_DEALS_TEAM_ID_COLUMN` — override the column in the deals table holding the team ID (default comes from `config/data_sources.json`) - `POC_PIPELINE_LABEL` — `pipeline_label` value identifying PoC deals (default: `poc pipeline`) - `INTERNAL_TEAM_NAMES` — comma-separated internal demo/test team names to exclude (empty by default) - `HUBSPOT_ENGINEER_COUNT_PROPERTIES` — comma-separated HubSpot custom company property names used to prefer better-enriched company matches (empty by default) - `INTERNAL_EMAIL_DOMAINS` — comma-separated domains whose admin emails are flagged as internal/test (empty by default) - `PERSONAL_EMAIL_DOMAINS` — comma-separated personal email domains flagged for review (defaults to common providers) ## Workflow ### Step 1: Fetch Data Run: ```bash python3 .agents/skills/poc-not-customer-usage/scripts/fetch_poc_not_customer_usage_data.py ``` This writes `/tmp/poc_not_customer_usage_data.json` with one object per company in the active-enterprise PoC cohort. The cohort logic is: 1. start from active enterprise service agreements (type/status filter values configured in `config/data_sources.json`) 2. require `current_period_end >= current_date()` 3. subtract teams with any non-PoC closed-won deal in the deals table (configured in `config/data_sources.json`; `DB_ENTERPRISE_DEALS_TABLE` overrides) using the same real-contract filter 4. exclude known internal/demo/test teams by name (via `INTERNAL_TEAM_NAMES`) 5. enrich the remaining teams with the latest PoC deal when available, but do not exclude teams just because the PoC pipeline record is missing Each output object includes: - `company_name` - `product_team_name` - `team_id` - `service_agreement_id` - `service_agreement_end` - `admin_email_domain` - `team_size` - `active_team_members` - `members_using_primary_feature` - `deal_name` - `deal_id` - `poc_pipeline_label` - `poc_deal_stage` - `poc_seats` - `company_email_domain` - `owner_name` - `hubspot_owner_id` - `classification` - `review_flags` - `date_range` - `primary_metric_30d` The primary metric is defined in `config/methodology.md`. The script intentionally does not reconstruct the broader customer-health score; it is specifically a usage view over still-open PoCs on active enterprise service agreements. It queries the configured primary metric tile on the Metabase dashboard (set via `METABASE_DASHBOARD_ID`, `METABASE_PRIMARY_METRIC_DASHCARD_ID`, `METABASE_PRIMARY_METRIC_CARD_ID`) with `team_id` and `date_range` parameter mappings only; the parameter targets are read from `config/data_sources.json`. If that metric query fails, the script exits rather than publishing a misleading zero-usage report. ### Step 2: Build Report Run: ```bash python3 .agents/skills/poc-not-customer-usage/scripts/build_report.py ``` This reads `/tmp/poc_not_customer_usage_data.json` and writes `/tmp/poc_not_customer_usage_report.json`. The report JSON has this shape: ```json { "text": "Active enterprise PoC 30-day <PRIMARY_METRIC_LABEL> usage summary", "main_blocks": [ ...Slack Block Kit JSON... ], "thread_replies": [], "run_summary": { "companies_analyzed": 0, "primary_metric_30d": 0, "top_company": "", "top_company_primary_metric_30d": 0 } } ``` ### Step 3: Post to Slack Run: ```bash python3 .agents/skills/poc-not-customer-usage/scripts/post_to_slack.py ``` This posts one top-level summary message. ## Slack output expectations The top-level summary should stay compact and scannable: - report header with date - quick summary of how many companies are in the cohort - ranked list of all companies by 30-day primary metric in the same post - each company should use the compact one-line format defined in `config/methodology.md` Keep all sections readable in Slack. Use `n/a` for missing fields rather than leaving blanks.