poc-not-customer-usage

name

poc-not-customer-usage

description

Runs an end-to-end usage report for PoCs that still have an active enterprise service agreement but do not yet have a closed-won non-PoC enterprise deal. Use this skill when asked to summarize this still-open PoC cohort by recent primary metric consumption while still including company name, owner, deal context, and related metadata. The skill posts one compact summary message to Slack with the full ranked company list in that same post.

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:

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:

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:

{
  "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:

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.