Client Dashboard / KPI Report — SKILL.md

What This Skill Does

Generates a client-facing executive KPI dashboard from QuickBooks Online data. Produces an Excel workbook with traffic-light scoring, 6-month trend sparklines, client-specific watch items, and a CDC log tracking KPI changes month-over-month.

When To Use

• Monthly close is complete and it's time to generate the client dashboard
• User asks for KPI report, dashboard, or executive summary for any client
• After running P&L Quick Compare and bank rec — this is the final deliverable step

When NOT To Use

• NOT a substitute for P&L Quick Compare (different purpose — this is executive summary, not variance analysis)
• NOT for mid-month snapshots — designed for complete monthly periods
• NOT for YTD / annual reports — use P&L Deep Analysis for those
• NOT for clients without QBO integration (no data source)

Pipeline: scripts/pipelines/client-dashboard.py

Prerequisites

pip install openpyxl
# Node.js qbo-client must be authenticated for the target slug

Usage

# Example — March 2026
python3 scripts/pipelines/client-dashboard.py --slug \x3Cclient-slug> --month 2026-03

# Custom output directory
python3 scripts/pipelines/client-dashboard.py --slug \x3Cclient-slug> --month 2026-03 --out ~/Desktop/reports

# QBO sandbox
python3 scripts/pipelines/client-dashboard.py --slug \x3Cclient-slug> --month 2026-03 --sandbox

Arguments

Output: Excel Workbook

Filename: KPI_Dashboard_{slug}_{YYYY_MM}.xlsx

KPIs Computed

All math uses Python Decimal for precision.

Traffic Light Scoring

Each KPI is scored GREEN / YELLOW / RED based on configurable thresholds per client SOP.

🟢 GREEN  = On target (within green band)
🟡 WATCH  = Approaching threshold (yellow band)
🔴 ACTION = Below/above acceptable range (outside yellow band)
⬜ N/A    = KPI not applicable or not configured

Thresholds are defined in CLIENT_CONFIGS in the script — one config block per client slug.

Client SOP Integration

Adding a New Client

Add a block to CLIENT_CONFIGS in the script:

"new-slug": {
    "company_name": "Company Name",
    "industry": "Industry",
    "has_ar": True,
    "has_headcount": False,
    "kpis_enabled": ["revenue_mom", "gross_margin", ...],
    "thresholds": {
        "gross_margin": {"green": (Decimal("45"), None), "yellow": (Decimal("35"), Decimal("45"))},
        ...
    },
    "watch_items": [...],
    "benchmarks": {...},
    "benchmark_source": "Source description",
}

CDC (Change Data Capture)

Cache stored at: .cache/client-dashboard/{slug}.json

• First run: saves full KPI snapshot, CDC tab shows "First run" message
• Subsequent runs: diffs current KPIs vs. prior run
• CDC log shows: KPI label | Prior | Current | Delta | % Change | Improved/Declined

Trend Sparklines

6-month trend for each KPI uses two formats:

1. Direction arrows: ↑↑ ↑ ↗ → ↘ ↓ ↓↓ (based on % change over period)
2. Block bars: █▇▅▃▁_ (relative to max value — in Trends tab mini-chart section)

Peer Benchmarks

Manual config only. Benchmark values live in CLIENT_CONFIGS[slug]["benchmarks"]. Source attribution displayed in every tab footer. To update: edit benchmarks dict and benchmark_source string per client.

Integration with Pipeline Suite

This pipeline is designed to run after monthly close is complete:

1. Bank Reconciliation      (bank-reconciliation.py)
2. P&L Quick Compare        (pl-quick-compare.py)
3. P&L Deep Analysis        (pl-deep-analysis.py)      ← optional for controller level
4. Client Dashboard         (client-dashboard.py)      ← this script
5. Cash Flow Forecast       (cash-flow-forecast.py)    ← quarterly advisory

File Locations

Troubleshooting

QBO CLI error: Ensure your QBO integration is authenticated for the slug.

Missing KPIs: If Balance Sheet accounts don't match expected labels, values default to 0. Check extract_bs_metrics() candidates list for account name variants.

New client config: Add slug to CLIENT_CONFIGS before first run. Default config uses generic thresholds (not client-specific).

Decimal errors: All financial math uses Python Decimal. Do not mix float — use to_d() helper for any external values.