Documentation

fsds/claude-enhance-superset-skill.md

Plan: Enhance acsis-superset Skill

Goal

Completely overhaul the acsis-superset Claude skill to make it actually useful for agents. The current skill exists but isn't being used, leading to repetitive explanations.

Key objectives:

  1. Make it discoverable - Update description to trigger agent use for Superset tasks
  2. Front-load critical info - Put the most important gotchas right at the top
  3. Include working code - Complete, tested examples that agents can copy
  4. Fix the dashboard problem - Include proper Python code for adding charts to dashboards

Pain points to address:

  1. Authentication - Complete, verified auth flow
  2. Chart Types - ECharts vs legacy viz_type confusion
  3. Dashboard Charts - How to correctly add charts to dashboards (the position_json issue)
  4. Backup Scripts - Document existing export/import scripts
  5. Custom Image - Document the custom Superset 4.1.1 image

Key Findings from Investigation

Authentication Flow (Verified)

  1. Login: POST /api/v1/security/login with {"username","password","provider":"db"} → returns access_token
  2. CSRF: GET /api/v1/security/csrf_token/ with Bearer token + cookies → returns result
  3. All write operations need BOTH Bearer token AND X-CSRFToken header

Chart Types (Confusion Clarified)

  • Legacy charts: dist_bar, pie, table, treemap_v2, big_number_total
  • ECharts charts: echarts_timeseries_bar, echarts_timeseries_line, echarts_area, echarts_pie, etc.
  • Key insight: Use echarts_* versions for new charts - they're more feature-rich and better maintained
  • Superset 4.1.1 adds: echarts_sankey, echarts_heatmap, echarts_histogram

Dashboard Position JSON (Critical Issue Identified)

The "chart definition missing" problem occurs when charts are not properly structured in position_json. Correct structure requires:

  1. ROOT_ID → contains ["GRID_ID"] as children
  2. GRID_ID → contains ["ROW-xxx", ...] as children
  3. ROW-xxx → contains ["CHART-xxx", ...] as children, needs parents array
  4. CHART-xxx → needs meta.chartId (the actual chart ID), parents array, width, height

The simple approach in superset-expansion.py:add_charts_to_dashboard() puts CHARTs directly under GRID_ID (skipping ROW containers). This works but may cause issues. The proper approach uses ROW containers.

Backup Scripts

Superset-specific (dashboards/charts):

  • projects/bbu-rfid/resources/superset/export-dashboards.sh - Exports all dashboards to zip
  • Auto-import on startup via docker-entrypoint.sh if /app/exports/dashboards.zip exists

Database-level (full PostgreSQL backup):

  • projects/bbu-rfid/resources/scripts/backup-local-db.sh - Full pg_dump of local database
  • projects/bbu-rfid/resources/scripts/restore-to-azure.sh - Restore to Azure PostgreSQL

Custom Image

  • Based on apache/superset:4.1.1 (not 5.0 due to tooltip bug #34198)
  • Adds psycopg2-binary and redis drivers
  • Custom superset_config.py handles Aspire connection string conversion
  • Custom docker-entrypoint.sh auto-configures database connection and imports dashboards

Files to Modify

1. .claude/skills/acsis-superset/SKILL.md (MAJOR REWRITE)

Complete restructure for agent usability:

  • Critical Gotchas section at TOP - The 3-5 things that ALWAYS trip agents up
  • Streamlined Quick Start with verified commands
  • Clear TOC to sub-documents
  • Remove verbose prose, use tables and bullet points
  • Add "When to Use This Skill" section to help discoverability

2. .claude/skills/acsis-superset/api-reference.md (REWRITE)

Complete auth flow documentation:

  • Working bash script template agents can copy verbatim
  • Token lifecycle notes (15 min expiry!)
  • Cookie handling for CSRF (critical for POST/PUT)
  • Common auth errors and fixes
  • Rate limiting awareness

3. .claude/skills/acsis-superset/chart-types.md (NEW FILE)

The ECharts confusion resolver:

  • Complete viz_type lookup table - every type with description
  • Legacy vs ECharts comparison (use ECharts!)
  • When to use each chart type (decision tree)
  • Common parameter patterns for each type
  • Example params JSON for the most-used types

4. .claude/skills/acsis-superset/dashboard-charts.md (NEW FILE - replaces dashboard-recipes.md)

Fix the "chart definition missing" problem:

  • Complete position_json anatomy with annotated example
  • Working Python function for properly adding charts to dashboards
  • The ROW container requirement (THIS IS THE KEY ISSUE)
  • Step-by-step: Create dashboard, add charts, verify
  • Debug checklist for "chart definition missing"

5. .claude/skills/acsis-superset/backup-restore.md (NEW FILE)

Complete backup/restore guide:

  • export-dashboards.sh usage and output location
  • Auto-import on Azure deployment
  • Manual import via API (with working curl)
  • Database-level backup (pg_dump scripts)
  • Restore procedures

6. .claude/skills/acsis-superset/infrastructure.md (NEW FILE - replaces custom-image.md)

The custom Superset image:

  • Why 4.1.1 (tooltip bug #34198 in 5.0)
  • What's installed and why
  • Auto-configuration features (database discovery)
  • How to modify configuration
  • How Aspire orchestrates Superset

7. DELETE: views-and-datasets.md, troubleshooting.md

Consolidate into other docs:

  • Views/datasets info → SKILL.md quick reference
  • Troubleshooting → api-reference.md and dashboard-charts.md

Implementation Order

  1. SKILL.md (main rewrite) - Set the tone, add Critical Gotchas at top
  2. dashboard-charts.md (new) - Fix the #1 pain point with working Python code
  3. chart-types.md (new) - Resolve ECharts confusion with lookup table
  4. api-reference.md (rewrite) - Complete auth flow with copy-paste commands
  5. backup-restore.md (new) - Document all backup/restore options
  6. infrastructure.md (new) - Custom image documentation
  7. Cleanup - Delete old files, verify cross-references

Success Criteria

  • Agents use the skill proactively when working with Superset
  • Agents can authenticate correctly on first try (verified flow)
  • Agents use correct viz_type identifiers (ECharts preferred)
  • Agents can add charts to dashboards that actually display (working Python code)
  • Agents know where backup scripts are and how to use them
  • No more repetitive explanations about the same Superset issues

Critical Files

.claude/skills/acsis-superset/
├── SKILL.md                 # Main entry point with Critical Gotchas
├── api-reference.md         # Auth flow, endpoints
├── chart-types.md           # viz_type lookup table (NEW)
├── dashboard-charts.md      # position_json + working code (NEW)
├── backup-restore.md        # Export/import scripts (NEW)
└── infrastructure.md        # Custom image docs (NEW)

projects/bbu-rfid/resources/superset/
├── export-dashboards.sh     # Dashboard export script
├── Dockerfile               # Custom image definition
├── superset_config.py       # Python configuration
└── docker-entrypoint.sh     # Auto-configuration script

projects/bbu-rfid/resources/scripts/
├── backup-local-db.sh       # Database backup
└── restore-to-azure.sh      # Database restore