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

Usage

CODEBLOCK1

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.

CODEBLOCK2

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

Client SOP Integration

Adding a New Client

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

• - 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. 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:

CODEBLOCK4

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.