Boardroom Analyst

Boardroom Analyst

Boardroom Analyst is a governed executive analytics skill pack for local, dbt-documented DuckDB datamarts.

It gives leaders a way to ask boardroom-level questions such as "Why did ad revenue growth slow last month?" or "Which monetization surface is driving the change?" and receive answers that are grounded in documented metrics, read-only SQL, chart-ready data, and explicit caveats.

The core idea: make agentic analytics credible enough for executive review by forcing every claim to show its work.

Demo

Hosted MVP product demo

The animated preview is optimized for GitHub README rendering. Open the source MP4 recording for the full end-to-end MVP product flow: a leadership question, dbt semantic context, read-only SQL, evidence, an executive brief, and a governed follow-up answer.

Why It Exists

Most companies already have useful datamarts, but the last mile from governed data to executive insight is still slow. Analysts answer recurring leadership questions manually, dashboards rarely explain the "why", and generic AI tools can hallucinate metrics or silently use the wrong grain.

Boardroom Analyst packages a safer workflow:

• Use dbt docs as the semantic authority.
• Query local DuckDB data in read-only mode.
• Attach every material claim to source SQL and result hashes.
• Produce an executive brief plus a follow-up query loop.
• Refuse or qualify answers when metric definitions, grain, or joins are missing.

What Ships

The plugin lives at plugins/boardroom-analyst and includes three skills:

• boardroom-onboarding: validates dbt artifacts and builds datamart_context.json.
• boardroom-brief: creates an executive brief with SQL-backed findings, chart data, caveats, and a query appendix.
• boardroom-query: answers follow-up executive questions through local read-only DuckDB queries.

It also includes deterministic helper scripts for:

• Parsing dbt manifest.json, catalog.json, and YAML model metadata.
• Rejecting mutating or multi-statement SQL.
• Running local DuckDB queries in read-only mode.
• Exporting chart-ready CSV data.
• Writing brief.md and analysis_run.json.

Requirements

• Python 3.11+
• uv
• A DuckDB database file
• dbt-compatible documentation:
  • Required: target/manifest.json
  • Recommended: target/catalog.json
  • Recommended: model YAML docs with metric, grain, caveat, join, and priority-question metadata

Setup

Create the Python environment with uv:

uv venv --python python3
uv pip install -e ".[dev]"

Run the test suite:

.venv/bin/python -m pytest

Validate the plugin:

python3 /Users/kasra/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py plugins/boardroom-analyst

Validate individual skills:

python3 /Users/kasra/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/boardroom-analyst/skills/boardroom-onboarding
python3 /Users/kasra/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/boardroom-analyst/skills/boardroom-brief
python3 /Users/kasra/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/boardroom-analyst/skills/boardroom-query

Usage

Set the plugin root once:

PLUGIN_ROOT="plugins/boardroom-analyst"

1. Build Semantic Context

.venv/bin/python "$PLUGIN_ROOT/scripts/build_datamart_context.py" \
  --dbt-project path/to/dbt_project \
  --output datamart_context.json

This produces a normalized context file covering documented models, columns, metrics, grain, joins, caveats, priority questions, trust level, and warnings.

2. Run a Read-Only Query

.venv/bin/python "$PLUGIN_ROOT/scripts/run_duckdb_query.py" \
  --database path/to/warehouse.duckdb \
  --query-id q001 \
  --sql "select surface, sum(net_revenue_millions) as net_revenue_millions from ad_revenue_by_surface group by 1 order by 1" \
  --output analysis_runs/q001.json

The SQL guard rejects writes, extension loading, database attachment, and multi-statement SQL before execution.

3. Export Chart Data

.venv/bin/python "$PLUGIN_ROOT/scripts/export_chart_csv.py" \
  --query-result analysis_runs/q001.json \
  --output reports/run_001/charts/revenue_by_surface.csv

4. Write the Executive Brief

.venv/bin/python "$PLUGIN_ROOT/scripts/write_insight_brief.py" \
  --run analysis_run.json \
  --output-dir reports/run_001

This writes:

• reports/run_001/brief.md
• reports/run_001/analysis_run.json

Agent Workflow

Example prompts:

Use $boardroom-onboarding to validate my DuckDB datamart and dbt docs.

Use $boardroom-brief to explain why ad revenue growth slowed last month using this datamart.