KPI Alert System Skill#

Automated KPI monitoring with threshold alerts for business financial health. Pulls data from QBO, Google Sheets, or CSV exports, evaluates rules, and fires alerts to Telegram/Slack/email.

---

Supported KPIs#

KPIDescriptionTypical Alert ThresholdAR Aging (30/60/90+)Outstanding receivables by age bucket>$X in 90+ days, or >30% of ARCash RunwayMonths of runway at current burn<3 months = red, <6 months = yellowMonthly Burn RateNet cash outflow per month>$X/month or >Y% above budgetRevenue Growth (MoM/QoQ)Revenue trend vs prior period<0% = alert, <5% = warningGross Margin %(Revenue - COGS) / Revenue<X% below targetNet Income / LossP&L bottom lineNegative for N consecutive monthsDSO (Days Sales Outstanding)AR / (Revenue / 30)>45 days = yellow, >60 = redCurrent RatioCurrent Assets / Current Liabilities<1.2 = alertQuick Ratio(Cash + AR) / Current Liabilities<1.0 = alertPayroll % of RevenuePayroll costs as % of top line>X% = alert

---

Setup Steps#

1. Define Your KPI Config#

Create a YAML config file for the client or firm:

yaml

# kpi-config-clientname.yaml
client: "Acme Corp"
alert_channels:
  - type: telegram
    target: "@irfan_dm"  # or channel ID
  - type: slack
    webhook: "https://hooks.slack.com/services/..."
  - type: email
    to: "imussa@precisionledger.io"

kpis:
  ar_aging_90plus:
    label: "AR 90+ Days"
    source: qbo  # or sheets, csv
    threshold_red: 15000
    threshold_yellow: 8000
    message: "AR aging 90+ days is ${value} — collections action needed"

  cash_runway_months:
    label: "Cash Runway"
    source: qbo
    threshold_red: 3
    threshold_yellow: 6
    direction: below  # alert when BELOW threshold (default: above)
    message: "Cash runway is {value} months — review burn rate immediately"

  revenue_growth_mom:
    label: "MoM Revenue Growth"
    source: sheets
    sheet_id: "1BxiM..."
    tab: "P&L Summary"
    cell_range: "C5"
    threshold_red: -5
    threshold_yellow: 0
    direction: below
    message: "Revenue growth is {value}% MoM — investigate pipeline"

  gross_margin_pct:
    label: "Gross Margin %"
    source: qbo
    threshold_red: 30
    threshold_yellow: 40
    direction: below
    message: "Gross margin at {value}% — below target of 40%"

---

2. Data Source Integration#

QuickBooks Online (via QBO Automation skill)

bash

# Pull P&L summary for current month
qbo report pl --period this-month --format json > /tmp/pl-current.json

# Pull AR aging
qbo report ar-aging --format json > /tmp/ar-aging.json

# Pull balance sheet for liquidity ratios
qbo report balance-sheet --period this-month --format json > /tmp/bs-current.json

Google Sheets (via gog skill)

bash

# Read a named range
gog sheets read --id SHEET_ID --range "KPI Dashboard!B2:C20"

CSV / Excel Export

Place exports at a consistent path and reference in config:

yaml

source: csv
file: "/tmp/monthly-export-2026-03.csv"
column: "AR_90plus"
row_filter: "Month=March"

---

3. KPI Evaluation Logic#

Core algorithm (Python pseudocode for reference):

python

def evaluate_kpi(config, value):
    direction = config.get("direction", "above")

    if direction == "above":
        if value >= config["threshold_red"]:
            return "RED", config["message"].format(value=value)
        elif value >= config["threshold_yellow"]:
            return "YELLOW", config["message"].format(value=value)
    else:  # below
        if value <= config["threshold_red"]:
            return "RED", config["message"].format(value=value)
        elif value <= config["threshold_yellow"]:
            return "YELLOW", config["message"].format(value=value)

    return "GREEN", None

def run_kpi_check(config_path):
    config = load_yaml(config_path)
    alerts = []

    for kpi_id, kpi_config in config["kpis"].items():
        value = fetch_kpi_value(kpi_config)  # pulls from QBO/Sheets/CSV
        status, message = evaluate_kpi(kpi_config, value)

        if status in ["RED", "YELLOW"]:
            alerts.append({
                "kpi": kpi_config["label"],
                "status": status,
                "value": value,
                "message": message
            })

    return alerts

---

4. Alert Formatting#

Telegram message format:

text

🚨 KPI ALERT — Acme Corp
Date: March 15, 2026

🔴 AR 90+ Days: $18,500
   → Collections action needed immediately

🟡 Gross Margin: 38%
   → Below 40% target — review COGS

✅ Cash Runway: 8.2 months
✅ Revenue Growth: +4.2% MoM

Run by: Sam Ledger / PrecisionLedger

Slack format (with attachments):

json

{
  "attachments": [
    {
      "color": "#ff0000",
      "title": "🔴 AR 90+ Days — $18,500",
      "text": "Collections action needed. 90+ day bucket exceeds $15,000 threshold.",
      "footer": "KPI Alert System | PrecisionLedger",
      "ts": 1742076000
    }
  ]
}

---

5. Scheduling with OpenClaw Cron#

Monthly KPI check (1st of month, 9 AM CST):

json

{
  "name": "Monthly KPI Check — Acme Corp",
  "schedule": {
    "kind": "cron",
    "expr": "0 9 1 * *",
    "tz": "America/Chicago"
  },
  "payload": {
    "kind": "agentTurn",
    "message": "Run KPI alert check for Acme Corp using kpi-config-acme.yaml. Pull QBO AR aging and P&L, evaluate thresholds, and send alerts to the configured channels."
  },
  "sessionTarget": "isolated",
  "delivery": {
    "mode": "announce"
  }
}

Weekly cash runway check (every Monday, 8 AM CST):

json

{
  "name": "Weekly Cash Runway Check",
  "schedule": {
    "kind": "cron",
    "expr": "0 8 * * 1",
    "tz": "America/Chicago"
  },
  "payload": {
    "kind": "agentTurn",
    "message": "Check cash runway and burn rate for all active clients. Alert if any client is below 6 months runway."
  },
  "sessionTarget": "isolated"
}

---

Example Prompts#

Setup#

"Set up KPI alerts for my client TechStartup LLC. Alert me on Telegram when AR aging hits 90 days, burn rate exceeds $40k/month, or runway drops below 4 months."

Manual Check#

"Run a KPI check on Acme Corp right now and tell me which thresholds are breached."

Threshold Adjustment#

"Update the gross margin alert for TechStartup to yellow at 45% and red at 35%."

Report Generation#

"Generate a weekly KPI summary for all active clients and post to the #weekly-metrics Telegram channel."

---

KPI Calculation Reference#

Cash Runway#

text

Runway (months) = Current Cash Balance / Average Monthly Burn Rate
Average Monthly Burn = (Cash 3 months ago - Cash today) / 3

Days Sales Outstanding (DSO)#

text

DSO = (Accounts Receivable / Revenue) × 30

Burn Rate#

text

Net Burn = Total Cash Outflows - Total Cash Inflows (monthly)
Gross Burn = Total Cash Outflows only (monthly)

Current Ratio#

text

Current Ratio = Current Assets / Current Liabilities

AR Aging Concentration Risk#

text

90+ Day Concentration = AR 90+ days / Total AR × 100
Alert when concentration > 20%

---

Multi-Client Monitoring Pattern#

For firms managing multiple clients:

yaml

# master-kpi-config.yaml
clients:
  - name: "Acme Corp"
    config: "./clients/acme/kpi-config.yaml"
    qbo_realm: "123456789"

  - name: "TechStartup LLC"
    config: "./clients/techstartup/kpi-config.yaml"
    qbo_realm: "987654321"

  - name: "Retail Co"
    config: "./clients/retailco/kpi-config.yaml"
    data_source: csv
    csv_path: "/data/retailco/monthly-export.csv"

Loop pattern:

"Check KPI thresholds for all clients in master-kpi-config.yaml. Consolidate alerts into one Telegram message grouped by client."

---

Negative Boundaries — When NOT to Use This Skill#

• Real-time stock/crypto price alerts → use defi-position-tracker or a dedicated market data feed
• Live BI dashboards (charts, drill-downs) → use Power BI, Looker, or Metabase
• ERP systems (SAP, Oracle, NetSuite) → requires dedicated API connectors, not this skill
• Sub-minute alerting (high-frequency trading signals) → wrong latency class
• PTIN-regulated tax analysis → use qbo-to-tax-bridge (Moltlaunch service only)
• Client-facing automated reports → requires Irfan approval before sending externally
• Write operations to QBO → read-only by default; journal entries need explicit approval

---

Integration Stack#

LayerToolData Pull (QBO)qbo-automation skillData Pull (Sheets)gog skillAlerting (Telegram)message tool (channel=telegram)Schedulingcron toolStorageworkspace/clients//kpi-data/Config FormatYAML (kpi-config-.yaml)

---

Alert Severity Guide#

ColorMeaningResponse Time🔴 REDThreshold critically breached — action requiredSame day🟡 YELLOWWarning zone — monitor closelyWithin 48 hours✅ GREENWithin acceptable rangeNo action needed

---

KPI Alert System — PrecisionLedger Skill v1.0.0