/managing-dashboards

Managing dashboards

Use this skill for a dashboard change that affects the dashboard platform, dashboard scene, or an existing non-widget tile type.

Use manage-dashboard-widgets for a new widget_type or a WidgetCard change.

1. Route the request

Before coding, decide the effect on each surface. Record affected, unaffected, or not applicable.

• Authenticated dashboard
• Public shared dashboard
• Embedded dashboard
• Exported dashboard
• Product-embedded dashboard
• Dashboard template
• Dashboard list and project homepage, if the change changes metadata or visibility

Read surfaces and ownership before you select files.

2. Define feature intake and acceptance criteria

Do this before implementation for a new dashboard feature. Skip it for a narrow bug fix with an existing contract.

1. State the user problem, intended actor, and explicit non-goals.
2. State the feature action and its default behavior.
3. State where the feature stores its state: dashboard, tile, request, user, URL, or a separate team-scoped resource.
4. State the availability, read permission, and mutation permission.
5. State behavior for new rows, existing rows, and invalid or absent state.
6. State the acceptance criteria for allowed, denied, shared, and failure paths.
7. State the expected query, cache, and database-write effect.
8. State the metric or event that shows adoption, failure, or regression.
9. If the feature adds persisted state or relations, define migration, cleanup, and concurrent-edit behavior.
10. Check whether the user-facing API, setting, or workflow needs a documentation update.

Read feature lifecycle and rollout before you choose a persisted feature contract.

3. Define the change contract

State these decisions before implementation.

1. Name the user action and the persisted data that changes.
2. Name every placement that renders the affected UI.
3. Define view, edit, and mutation permissions for each actor.
4. Define shared and embedded behavior. Never assume the authenticated behavior is safe there.
5. Define the result when the dashboard has zero, one, and hundreds of tiles.
6. Define the result at narrow and wide widths.
7. Define filter, variable, quick-filter, and tile-override precedence.
8. Define cache, refresh, query, and failure behavior.
9. If templates apply, define scope, portability, copy semantics, and later edits.
10. Define lifecycle, API, streaming, quota, audit, and project-tree effects.
11. For a new API, add MCP tools for its supported operations. Exclude an operation only with a documented reason. Record required scopes.

Use this checklist as a design gate. Read the linked reference when an item applies.

4. Implement across layers

1. Change the product model, serializer, API action, and generated types together when the persisted contract changes.
2. Keep dashboard and tile data team-scoped. Use the dashboard’s project context for every lookup and mutation.
3. Update each placement deliberately. Do not hide a feature only in the frontend when the API still permits it.
4. Preserve old rows and old layouts. Treat existing layout JSON and template payloads as versioned input.
5. Keep query work bounded. Do not turn dashboard load into unbounded tile queries or concurrent requests.
6. Keep grid updates stable during drag, resize, and tile refresh. Avoid a full grid relayout for each tile result.
7. Add observability when a change creates a new loading, query, cache, access, or refresh path.
8. For list-only state, render controls only where that state applies.
9. After a selector rename, search every dashboard consumer and test for the old name. Then run TypeScript.
10. Keep dashboard mutation actions on the authenticated dashboard placement unless another placement has an explicit contract.

5. Test the boundary, not only the happy path

Cover each affected boundary.

• View versus edit access.
• Authenticated, shared, embedded, and export rendering.
• Public output contains no private metadata or live data that public viewers cannot access.
• Cache hit, cache miss, stale result, forced refresh, query error, and request cancellation.
• Empty dashboard, a single tile, and a dense dashboard.
• Narrow layout, wide layout, drag, resize, insertion, duplication, and persisted layout reload.
• Template scope, permissions, variable substitution, and project-specific references.
• API schema and generated types after serializer changes.
• Paginated list ordering, each page, and client continuation when the UI loads every result.
• Filter and variable precedence, shared-token behavior, and quick-filter validation.
• Soft-delete, restore, move, copy, and project-transfer behavior.
• Streaming completion, disconnect, and individual tile failure behavior.
• Resource limits, audit events, and subscription behavior.
• Schema rollout, relation cleanup, concurrent edits, accessibility, and public content safety.

Run the focused tests for each edited layer. Then run the relevant checks from the verification guide.

6. Code map

Companion skills