diagnostic-playground

name	diagnostic-playground
description	Generates interactive HTML dashboards using real Supabase data to debug app issues. Testers interact with live data, flag problems, and copy structured feedback back to Claude.
user-invocable	true

Diagnostic Playground

Build interactive HTML dashboards that embed real Supabase data so testers can explore, filter, flag issues, and copy structured feedback back to Claude for action.

This plugin works with any Supabase-backed project. Claude discovers the project's schema, writes appropriate queries, and adapts the templates to the actual data model.

When to use this skill

Use when debugging requires seeing real data in context — not just raw SQL output. Examples:

• "Why aren't users completing the core action?" → user-funnel template
• "Show me recent submission issues" → entity-flow-debugger template
• "Check data integrity across tables" → data-integrity-checker template
• Any time you need a tester to visually validate data before you act on it

How to use this skill

Step 0: Discover the project schema

Before anything else:

1. Identify the Supabase project ID from the codebase (check environment files, config, or CLAUDE.md)
2. Run mcp__supabase__list_tables to see available tables
3. Identify the key entities: users table, primary content table, any ledger/transaction tables, any status/category tables
4. Map the project's schema to the template's generic concepts:
   • Users table → the table with user profiles (e.g., user_profiles, profiles, users)
   • Primary content table → the main user-generated content (e.g., orders, posts, reports, submissions, listings)
   • Ledger/points table → any table tracking points, credits, or transactions (e.g., xp_ledger, credits_log, transactions)
   • Categories/items table → reference data (e.g., products, categories, tags)
   • Locations/targets table → what the content relates to (e.g., locations, projects, channels)

Step 0.5: Discover the pipeline (for entity-flow-debugger)

If using the entity-flow-debugger template, also discover the action pipeline:

1. Find the main action entry point — Read the code to find the function that handles entity creation (e.g., submitReport(), createOrder(), handleSubmit())
2. Trace the sequential steps — Identify the order of operations:
   • Auth checks (is user signed in?)
   • Validation (is input valid?)
   • Permission checks (geofencing, rate limits, access control)
   • Database writes (INSERT/UPDATE)
   • Side-effects (XP awards, notifications, cache invalidation)
   • Success confirmation
3. Classify each step:
   • action — User-initiated action (tap, select, submit)
   • decision — Validation or guard check that can fail
   • success — Completion state
   • failure — Error state
4. Note failure conditions — What error message shows at each decision point?
5. Query for pipeline counts — If analytics exist (PostHog, Amplitude), query for funnel counts. Otherwise estimate from database (e.g., users with 0 entities = failed before creation)

This becomes DATA.pipeline in the generated dashboard, enabling the visual flow diagram with real data annotations.

Step 1: Pick a template

Read the appropriate template file for the diagnostic type:

• templates/entity-flow-debugger.md — Debug the primary user action flow (creation, processing, side-effects, volume trends)
• templates/user-funnel.md — Signup → first action conversion analysis (cohort breakdown, drop-off points)
• templates/data-integrity-checker.md — Cross-table consistency checks (count mismatches, balance drift, orphaned records)

Step 2: Run ALL Supabase queries FIRST

This is mandatory. Before writing any HTML:

1. Read the template's Data Requirements section
2. Read references/supabase-queries.md for query patterns
3. Adapt the example SQL to the actual project schema discovered in Step 0
4. Execute every query using mcp__supabase__execute_sql
5. Store the results — you will embed them in the HTML

Never generate HTML with placeholder or mock data. The entire value of this plugin is real data.

Step 3: Generate the HTML dashboard

1. Read references/dashboard-theme.md for the CSS foundation
2. Read references/feedback-schema.md for the feedback panel structure
3. Read references/flow-diagram.md for SVG flow diagram patterns (if using entity-flow-debugger)
4. Follow the template's Layout and Interactive Features sections
5. Embed query results as JavaScript constants:

<script>
// Real data from Supabase — queried at {timestamp}
const DATA = {
  entities: [/* actual rows */],
  summary: {/* actual aggregates */},
  queriedAt: "{ISO timestamp}"
};
</script>

5. Include the feedback panel (every dashboard gets one)
6. Save as diagnostic-{template-name}.html in the project root
7. Open with open diagnostic-{template-name}.html

Step 4: Handle feedback

When the tester pastes back structured feedback:

1. Parse the feedback block
2. For each finding:
   • bug: Investigate the code path, propose a fix
   • data-issue: Write a migration or SQL fix, run it
   • missing-analytics: Add the tracking event to the relevant view/component
   • question: Research and answer with data
3. If the finding references specific IDs, query them for more context
4. After acting, offer to regenerate the dashboard with fresh data

Core requirements (every dashboard)

• Single HTML file — inline all CSS and JS, no external dependencies
• Real data only — all data comes from Supabase queries run before generation
• Filterable tables — click column headers to sort, use search/filter inputs
• Feedback panel — sidebar or bottom panel where testers flag findings
• Copy Feedback button — copies structured text to clipboard with "Copied!" confirmation
• Timestamp — show when the data was queried (so testers know freshness)
• Dark theme — uses the Brutalist dark theme from references/dashboard-theme.md
• Flow diagram (entity-flow-debugger) — SVG pipeline visualization with real data annotations on each step

Data embedding pattern

// Embed as frozen constants — never mutate source data
const DATA = Object.freeze({
  // Template-specific data sections
  entities: Object.freeze([...rows]),
  summary: Object.freeze({...aggregates}),

  // Always include metadata
  _meta: Object.freeze({
    queriedAt: "2026-01-31T12:00:00Z",
    projectId: "{supabase-project-id}",
    template: "{template-name}",
    rowCounts: { entities: 150, users: 42 }
  })
});

Feedback panel pattern

Every dashboard includes a findings panel where testers can:

1. Click "Add Finding" to open a form
2. Select a category (bug, data-issue, missing-analytics, question)
3. Add a description and optionally reference specific row IDs
4. All findings accumulate in a list
5. "Copy Feedback" serializes everything as structured text for Claude

See references/feedback-schema.md for the exact format.

Common mistakes to avoid

• Querying inside the HTML — all data must be pre-embedded, not fetched at runtime
• Using mock data — if a query fails, report the error instead of faking it
• Skipping the feedback panel — it's the whole point; testers need to flag issues
• External dependencies — no CDN links, no fetch calls, everything is self-contained
• Forgetting the timestamp — stale data without context causes confusion
• Over-filtering — show all data by default, let testers narrow down
• Hardcoding table names — always discover the schema first and adapt queries