Checklist (all paths are inside the project directory the skill is executed in, except `.env` — see note below):
- [ ] QUERIES.md — SQL queries grouped under database type headings (e.g., PostgreSQL)
      OR sample-data/ directory with CSV files
- [ ] <DASHBOARD-NAME>-PRD.md — Human-language dashboard request
- [ ] .env — Database credentials (skip if using sample-data/). Does **not** need to live
      inside the project directory — `load_dotenv()` walks upward from the current
      working directory and picks up the closest `.env` it finds, so the user can keep
      credentials in a parent directory and avoid copying secrets into the project.
      Required variables (PostgreSQL): `PG_HOST`, `PG_DATABASE`, `PG_USER`, `PG_PASSWORD`,
      and optionally `PG_PORT` (defaults to `5432`).
- [ ] branding/ directory (required) containing ONE of:
      - branding.md — brand spec (palette, fonts, padding, sizing)
      - template.twb — Organization's Tableau template workbook
      Optionally, a logo (.svg or .jpg) can be added to branding/ in either case.

If any are missing, immediately run Project Scaffolding (below) before doing anything else. Do NOT ask the user to manually provide files — scaffold first, then let them customize.

Only check for the files listed above. Do NOT check for design-tokens.md, DS-ARCHITECTURE.md, DASHBOARD-PLAN.md, or any files inside mock-version/ — those are outputs generated by the workflow steps, not user-provided inputs.

QUERIES.md Format

Queries must be grouped under a heading matching the database type:

## PostgreSQL
SELECT * FROM public.table2

The agent selects the correct query script based on the heading.

Adding other databases: The skill ships with PostgreSQL support. To add other databases (Databricks, Snowflake, MySQL, BigQuery, etc.), create a matching query_<dbtype>.py script in the installed skill's scripts/ directory following the same pattern as query_postgresql.py, add the corresponding heading to QUERIES.md, and update references/step-a-data-exploration.md.

Required Python packages

# PostgreSQL
psycopg2-binary, python-dotenv, pandas

Workflow Overview

[Scaffolding] ──[user approval]──> Step 0: Brand Setup
Step 0: Brand Setup ──[user approval]──> Step A: Data Exploration
Step A: Data Exploration ──[user approval]──> Step B: Dashboard Planning
Step B: Dashboard Planning ──[user approval]──> Step C: HTML Mock
Step C: HTML Mock ──[user approval]──> Step D: Implementation Spec
Step D: Implementation Spec ──[user approval]──> Step E: TWB Generation (Experimental)

Do NOT skip steps. Wait for explicit user approval before moving to the next step.

Project Scaffolding

When to run: Automatically when the prerequisites check finds missing files. Skip only if all prerequisite files already exist.

Process:

Ask the user for permission to scaffold their project directory
Read each file from skeleton/ in the skill directory and write its contents into the user's project root, preserving the directory structure. This creates:
- sample-data/ — starter CSV files (sales orders, customer segments, monthly targets) for immediate testing
- .env.example — database credentials template (rename to .env when ready)
- EXAMPLE-PRD.md — blank PRD template with section headers and placeholder examples
- QUERIES.md — SQL query template with database type headings
- branding/branding.md — branding spec template with section headers and placeholder values
- SalesPerformance-PRD.md — partially filled Sales Performance PRD as a starting reference
List every file created and briefly explain what the user should fill in or customize
Be explicit about scaffold state:
- sample-data/ means the project is immediately usable in demo mode
- database mode is only ready after the user fills in .env and QUERIES.md
- branding mode is only ready after the user finishes branding/branding.md and optionally adds a logo or icons
Encourage the user to explore the demo/ directory in the skill repository for a complete worked example with all steps already generated
If both sample-data/ and a real database setup exist, explicitly tell the user which source will be used in Step A and why before proceeding
Wait for the user to confirm they have reviewed/customized the files, then proceed to Step 0

Important: Do NOT use shell cp commands — the skeleton directory is inside the skill installation, not the user's project. Read each skeleton file with the Read tool and write it to the user's project root with the Write tool.

Every step is iterative. The agent will not produce a perfect result in a single pass — this is expected and by design. Encourage the user to review each artifact carefully, request changes, and iterate until satisfied. This is especially true for Step C (HTML mock) and Step E (TWB generation). For Step C, encourage the user to share the mock with stakeholders for validation before approving — a well-reviewed mock prevents costly rework downstream.

Step 0: Brand Setup

Identity: Tableau design systems engineer.

Read references/step-0-brand-setup.md for detailed instructions.

Summary:

Ask the user for the minimum target Tableau Desktop version first (2024.2 – 2025.x default, or 2026.1+). Record the answer in design-tokens.md — it controls Step E's XML emission.
Detect branding source inside branding/: branding.md OR template.twb
Extract design tokens from branding.md (or from the .twb XML), plus optional logo if present
If fallback defaults are used for any missing brand decision, call out each fallback decision explicitly in design-tokens.md
Generate design-tokens.md in the project root
Present design-tokens.md to the user for approval

Step A: Data Exploration

Identity: Senior Data Engineer.

Read references/step-a-data-exploration.md for detailed instructions.

Summary:

Check for local data first: If sample-data/ directory exists with CSV files and the user has not clearly signaled database intent, scan those files directly
If QUERIES.md or .env clearly indicates DB intent, say which source you are using and why before continuing
If using the database path, read QUERIES.md, identify the database type from headings, and execute each query via the matching script from the installed skill:
- PostgreSQL: run the installed skill's scripts/query_postgresql.py; it permits one read-only SELECT, WITH, or plain EXPLAIN query and enforces a hard 500-row cap
- Other databases: add a query_<dbtype>.py script following the same read-only-by-default pattern
Analyze schema and sample data
Create DS-ARCHITECTURE.md with datasource and field descriptions
Present DS-ARCHITECTURE.md to the user for approval

Step B: Dashboard Planning

Identity: Senior Data Analyst specialized in informative graphs and dashboards.

Read references/step-b-dashboard-planning.md for detailed instructions.

Summary:

Read the PRD file, DS-ARCHITECTURE.md, and design-tokens.md
Identify KPIs and chart types from the user request
Map each visualization to specific columns from DS-ARCHITECTURE.md
Assign stable IDs for KPIs, charts, filters, and actions so later steps can reuse the same identifiers
Suggest additional KPIs and interesting data patterns
Propose filter strategy and dashboard actions
Present the dashboard plan to the user with approval criteria before moving to Step C

Step C: HTML Mock Creation

Identity: Tableau Developer.

Read references/step-c-mock-creation.md for detailed instructions.

Summary:

Read design-tokens.md (generated in Step 0)
Select appropriate template layout based on design tokens
Ask the user for their target screen size: Standard Laptop (1100×800) for portable devices, Home Screen (2100×1000) for wide external displays, or Custom dimensions. Defaults to Standard Laptop if skipped.
Create interactive HTML mock with Chart.js and sample data using the chosen screen dimensions as the dashboard frame
Save to mock-version/v_N/mock.html
Prevent empty-space-heavy, compressed, or out-of-bounds chart layouts by enforcing explicit slot sizes and readable chart occupancy
Present the mock to the user for approval
If approved, update DASHBOARD-PLAN.md and design-tokens.md if the mock diverged from them

Step D: Tableau Implementation Spec

Read references/step-d-implementation-spec.md for detailed instructions.

Summary:

Translate the approved HTML mock into a technical Tableau implementation spec
Document container hierarchy, sheets, calculated fields, parameters, and stable IDs in a strict markdown schema
Save to mock-version/v_N/TABLEAU-IMPLEMENTATION.md
Include enough structured detail for Step E to consume without guessing
If approved, update DASHBOARD-PLAN.md if the implementation spec diverged from it

Step E: TWB Workbook Generation (Experimental)

Scaffold build string: 2025.1.10 (20251.25.1121.1650) — all snippets are authored against this build. The emitted workbook version attribute and the inclusion of <explain-data> are driven by the Target Tableau Version captured in Step 0. See references/step-e-twb-generation.md § Tableau Version Targeting.

Read references/step-e-twb-generation.md for detailed instructions.

Snippet library: The references/snippets/ directory contains validated .twb files organized by domain. Each domain has a companion .md explaining the XML patterns. Read the relevant snippet files and companion docs before generating XML — assemble from validated patterns, do not generate XML from scratch.

Summary:

Read the approved TABLEAU-IMPLEMENTATION.md and design-tokens.md
Read DS-ARCHITECTURE.md for field names and types
Select snippet patterns based on requirements:
- Data model: snippets/data-model/ → single CSV, relationship, or join
- Chart types: snippets/worksheets/ → bar, line, text-table, area, pie, scatter, dual-axis, map
- Styling: snippets/worksheets/bar-chart-styled.twb → fonts, colors, axis titles
- Filters: snippets/worksheets/bar-chart-filtered.twb → categorical, date range, context
- Sorting: snippets/worksheets/bar-chart-sorted.twb → computed sort
- Tooltips: snippets/worksheets/custom-tooltip.twb → formatted tooltip template
- Dashboard layout: snippets/dashboard/ → single/multi-sheet, nested containers
- Actions: snippets/dashboard/ → filter, highlight, parameter actions
- Features: snippets/features/ → calculated fields, parameters, LOD expressions, Dynamic Zone Visibility
Assemble the .twb using the scaffold skeleton (snippets/scaffold/workbook-skeleton.twb) as the base, inserting parameterized snippet patterns in strict element order
Generate as live connection — do NOT include <extract> sections
Package as .twbx (ZIP archive bundling the .twb + all CSV data files)
Save both dashboard.twb and dashboard.twbx to mock-version/v_N/
Instruct the user to open dashboard.twbx in Tableau Desktop and use Data → Replace Data Source to connect live data

Handling Unknown Features

If the user requests a Tableau feature that has no validated snippet in references/snippets/, ask the user which approach they prefer:

Provide a reference .twb — the user builds a minimal example in Tableau Desktop demonstrating just that feature, provides the path, and the agent extracts the pattern from it
Attempt from examples/ — the agent searches the examples/ directory for a similar pattern in the existing complex workbooks, adapts it, and flags it as ⚠️ UNVALIDATED
Skip and document — the agent generates everything else correctly and writes a MANUAL_STEPS.md listing what the user needs to add manually in Tableau Desktop

Version Management

All mock and implementation files go inside mock-version/v_N/ (e.g., mock-version/v_1/)
Each version is a full standalone copy (mock.html + TABLEAU-IMPLEMENTATION.md + dashboard.twb + dashboard.twbx)
When the user requests revisions after Step D or E, increment the version number. Step C revisions overwrite the current mock in-place (same v_N directory).
DS-ARCHITECTURE.md, DASHBOARD-PLAN.md, and design-tokens.md live at the project root and always represent the latest approved global truth
Each versioned artifact should note which approved root-level files and mock version it was derived from

File Structure (per project)

project-root/
├── QUERIES.md                      (user input — with DB type headings)
├── <DASHBOARD-NAME>-PRD.md         (user input)
├── .env                            (user input — DB credentials)
├── branding/                       (user input — required; contains brand source)
│   ├── branding.md                 (option A: brand spec)
│   ├── template.twb                (option B: org Tableau template)
│   ├── logo.svg / logo.jpg         (optional, either case)
│   └── icons/                      (optional)
├── sample-data/                    (user input — optional, skip DB queries)
│   └── *.csv
├── design-tokens.md                (generated - step 0)
├── DS-ARCHITECTURE.md              (generated - step A)
├── DASHBOARD-PLAN.md               (generated - step B)
└── mock-version/
    ├── v_1/
    │   ├── mock.html               (generated - step C)
    │   ├── TABLEAU-IMPLEMENTATION.md (generated - step D)
    │   ├── dashboard.twb           (generated - step E, raw XML)
    │   └── dashboard.twbx          (generated - step E, packaged with data)
    └── v_2/
        ├── mock.html
        ├── TABLEAU-IMPLEMENTATION.md
        ├── dashboard.twb
        └── dashboard.twbx

tableau-dashboard-creator

Tableau Dashboard Creator

Prerequisites