Lightdash

Checks whether a self-hosted Lightdash upgrade is safe to run, and reads the tooling's answer without over-reading it. Use when upgrading a self-hosted instance, planning a maintenance window, answering "is this upgrade safe", or recovering a failed, hung, parked or lock-stuck migration — covers `lightdash upgrade-check` and `migrate preflight`, how to gate on their exit codes and JSON, and the readings that look calm but mean "could not check".

Test and assess an open Renovate dependency-bump PR. Picks the first open Renovate PR, checks out the branch, starts the app, exercises code paths affected by the upgraded package, reviews the changelog and (if needed) the upstream source diff, and reports whether the bump is safe to merge. Use when asked to "test a renovate PR", "triage renovate", "assess a renovate bump", or "check a dependency upgrade".

Guide for Lightdash's CASL-based authorization system. Use when working with scopes, custom roles, abilities, permissions, ForbiddenError, authorization, or access control. Helps with adding new scopes, debugging permission issues, understanding the permission flow, and creating custom roles.

Replay a HAR file as a mock backend to reproduce frontend performance issues with production data. Use when asked to replay a HAR file, reproduce a dashboard with a HAR, or test frontend performance with captured traffic.

Manage stacked PRs with Graphite CLI (gt) instead of git for branch/PR operations. Auto-detects Graphite repos via .git/.graphite_repo_config. Use when: creating stacked PRs, navigating branches, submitting PRs, syncing with main, restacking after changes, or any gt command usage.

Apply the Lightdash frontend style guide and design principles when working on React components or styling frontend code. Use when editing TSX files, building or reviewing UI, fixing styling issues, or when the user mentions Mantine, design, styling, or CSS modules.

Fix a Snyk vulnerability PR by regenerating the pnpm lockfile, checking changelogs for breaking changes, and posting findings as a PR comment. Use when asked to fix a vulnerability PR or handle a Snyk dependency upgrade.

Use when writing or modifying dbt model SQL — deciding whether to add a subquery or reuse an existing dimension/metric, structuring a query, joining models, or refactoring a metric's SQL. Encodes SQL semantic-correctness rules: reuse existing fields, prefer CTEs over correlated subqueries, and make joins and column lists explicit.

Use when working with Lightdash YAML files, dbt models with Lightdash metadata, the lightdash CLI (deploy, upload, download, preview, lint, warehouse-catalog, sql, set-warehouse, apps create/preview/validate), or managing charts, dashboards, spaces and access, AI agents, scheduled content, data apps, custom chart types (Chart Studio, `apps create --chart-type`, `--chart-types`), organization Data App themes, data-app external connections, users, groups, custom roles, metrics, and dimensions as code

Use when deprecating, sunsetting, or removing a backend HTTP API endpoint in Lightdash — wiring deprecation logging, deadline/sunset dates, response headers, and Sentry alerting onto a TSOA controller route. Also covers making the deprecation visible on docs.lightdash.com and llms.txt (description lead line, x-mint migration banner). Covers the first-party-caller precondition and the shared deprecation middleware.

Debug the Lightdash app using PM2 logs, Maple traces, and browser automation. Use when investigating issues, tracking down bugs, understanding request flow, or correlating frontend actions with backend behavior.

Use when creating, opening, or writing the title/description of a pull request, or writing PR bodies via `gh pr create` or `gt submit`. Covers what must go in the PR description (a ticket — GitHub issue or Linear) and what must never appear (client/customer names or their data).

Break up a large PR into vertical feature slices delivered incrementally via Graphite stacked PRs. All verticals share a single feature flag so the entire feature ships atomically. Use when: splitting a large PR, breaking up a diff, vertical slicing, incremental delivery, phased rollout, or when a PR is too large to review.

Guide for AI agents running in the isolated agent-harness environment. Use when you need to discover your agent ID, find your ports, manage your stack with agent-cli.sh, run verification, or understand the multi-agent development setup.

Add a generated in-product walkthrough (a training module) for a permission scope, e.g. manage:PinnedItems, manage:Space, manage:SavedChart. Use when the user wants a new training lesson, tour, or walkthrough for a Lightdash feature, or asks to teach a scope. Produces markers and anchors in the frontend, a generated tour, and a recorded verification flow; never hand-written steps or prose.

Add a first-run guided tour, product walkthrough, coachmarks, or empty-state mock/example data to a Lightdash frontend feature. Use when the user wants to onboard users to a page, add a "Take the tour" flow, explain an unfamiliar UI, or show sample data on an empty page.