tableau-spec

tableau-spec

Step 7 of 8, and non-skippable. It turns the approved mock.html into an IMPLEMENTATION-SPEC.md that maps every mock element to a concrete Tableau construct, so tableau-build builds from an explicit spec instead of guessing. It ends with a coverage reconciliation — the mirror of the mock's checklist — proving every mock element is mapped, and applies a simplest-primitive guard so the workbook uses the simplest construct that does the job.

Reads	Required: mock-version/<v_N>/mock.html (from mock) — the elements to map, tagged with data-plan-id; and DASHBOARD-PLAN.md (from plan) — the shared element/filter/interaction ids and the interaction intents (CONTRACT.md §6).
Writes	mock-version/<v_N>/IMPLEMENTATION-SPEC.md — a standalone deliverable copy (CONTRACT.md §4.3).
STATE.md update	Sets spec = approved; flips a downstream approved build step to stale on a re-run (CONTRACT.md §4.2). Does not touch current_version — only tableau-mock bumps it (§4.3).
Entry gate	Refuses to run until plan is resolved and DASHBOARD-PLAN.md exists, and mock is resolved and mock.html exists at current_version (CONTRACT.md §4.1).
Next step	tableau-build (or tableau-route to confirm).

The mechanical guarantees — the entry gate, the coverage reconciliation (every mock element mapped, nothing unmapped), the simplest-primitive guard (any advanced feature carries a justification), the version bump, and the STATE.md transition — live in spec.py (CLI) and reconcile.py (the reconciliation + guard core). Your job is the judgment part: choosing the right, simplest Tableau construct for each element and justifying any escalation. Run the script at the points below; do not hand-edit STATE.md.

The one convention the reconciliation depends on

reconcile.py decides "mapped" mechanically, so the spec must carry a single Element Mapping table (see references/IMPLEMENTATION-SPEC-TEMPLATE.md):

• The table's first column header is id and it has a column whose header contains construct and one whose header contains justif.
• One row per mock element, with the id matching a data-plan-id from mock.html exactly. A mock id with no row is an unmapped element that blocks approval — this is what makes "nothing unmapped" a guarantee.
• The construct cell names the Tableau construct; the justification cell explains any escalation (leave it blank / - for a simple primitive).

The simplest-primitive guard

Default every element to the simplest sufficient Tableau primitive. Only escalate to an advanced feature when the simpler option genuinely cannot do the job — and when you do, write why in the justification cell (what simpler alternative you rejected and the concrete reason). The guard flags these advanced features when their justification is blank:

advanced feature	simpler default to justify against
Dynamic Zone Visibility (DZV)	a show/hide button container
LOD expression ({FIXED ...})	a plain aggregate (SUM, AVG) or the view's default grain
table calculation (WINDOW_*, RUNNING_*, INDEX(), RANK)	a native aggregate or quick table calc on the view
parameter action	a filter action / highlight action, or a static parameter

The concrete "what's simplest for this interaction" knowledge lives in the validated snippet library. Map the shared interaction terms to their simplest construct first (CONTRACT.md §6): cross-filter → a Filter action (Use as Filter); highlight → a Highlight action; drill → a hierarchy expand/collapse; swap view / toggle panel / parameter swap → these legitimately need DZV / parameter — justify them.

How to run

1. Precheck. From the project directory, run:

   python "${CLAUDE_SKILL_DIR}/scripts/spec.py" precheck "<project-dir>"
   

   (Use python3 if python is unavailable.) If it prints [BLOCKED], relay the reason and stop — the analyst must resolve the named upstream step (tableau-mock for the approved mock, tableau-plan for the blueprint) first. Otherwise note its signals: the mock path to map from, the list of element ids every one of which needs a mapping row, and the target path to write IMPLEMENTATION-SPEC.md into (the mock's current_version — spec writes beside the mock.html it maps and never bumps the version).

2. Read the inputs. Read mock.html at the reported mock path — its data-plan-id attributes are your exact mapping list. Read DASHBOARD-PLAN.md for what each id is (KPI / chart kind / filter / interaction) and the interaction intents, so you map to the right construct.

3. Author IMPLEMENTATION-SPEC.md at the precheck's target path. Fill the Element Mapping table with one row per mock element, defaulting to the simplest primitive and justifying every escalation. Add the supporting detail the build needs (calculated fields, data source / joins, actions, parameters) following the template. When refining an existing spec at this version, Edit it in place.

4. Self-check, then present. Validate the draft before showing it:

   python "${CLAUDE_SKILL_DIR}/scripts/spec.py" validate "<project-dir>"
   

   It prints the reconciliation checklist (one line per mock element, each [x] mapped or [ ] unmapped / unjustified-escalation) and the guard result. If it prints [INVALID], map the missing element(s) / add the missing justification(s) and re-run. When it prints [OK], show the checklist to the analyst (it's the proof nothing was dropped and nothing is over-engineered) and present the spec for approval.

5. Commit — only after the analyst approves:

   python "${CLAUDE_SKILL_DIR}/scripts/spec.py" commit "<project-dir>"
   

   Commit re-runs the full reconciliation + guard (spec is non-skippable, so it only ever sets approved). If it prints [REFUSED], fix what the checklist names and re-run. On success it records spec = approved, sets current_version to the target v_N, and reports any downstream step it marked stale. Relay the summary and tell the analyst to open a fresh conversation and run the next step (tableau-build, or tableau-route to confirm).

Notes

• Non-skippable. The build needs an explicit spec; commit only ever sets approved.
• Versioned deliverable. IMPLEMENTATION-SPEC.md lives under mock-version/<v_N>/ beside its mock.html (CONTRACT.md §4.3). Spec writes into the mock's current_version and overwrites in place on a re-run; it never bumps current_version. A new spec version is created by re-running tableau-mock (which bumps and stales spec). The target path is reported by precheck.

The full STATE.md schema and the ordering / staleness / versioning rules live in CONTRACT.md at the repo root. This skill restates only its own slice; spec.py / reconcile.py are the executable mirror of the contract it enforces.