develop-data-analysis-dashboard

# Data Analysis Dashboard Development Skill Provides full data analysis dashboard (instrument panel) development capabilities—project creation, card plan, data cleaning, dashboard development, validation, and delivery—as one end-to-end workflow. Data cleaning is an important part of dashboard development. --- ## Code Execution Method All tool calls via `from sdk.tool import tool` in this skill must be executed by passing code to `run_sdk_snippet`'s `python_code` parameter. When a skill snippet calls tools through the SDK, always use `result.ok` to determine success and read failure details from `result.content`. Do not read or call `result.error`, because SDK `Result` stores failure text in `content`. --- ## Quick Start **Important**: Detailed rules are inlined later in this document; while executing steps, consult Workflow Summary, Project Setup, Dashboard Development, and Dashboard Data Cleaning Guide. **Runtime base files**: Do not modify, overwrite, or delete `index.html`, `dashboard.js`, or `index.css`; violations make the data dashboard unusable. **Default card counts for new dashboards — MANDATORY unless the user explicitly requests a reduced scope:** | Card type | Required count | Notes | | --------- | -------------- | ---------------------------------------------------------------------------- | | metric | **≥ 6** | Key KPI overview cards | | echarts | **26 – 30** | Core of the dashboard; pad with same-type charts across different dimensions | | table | **2 – 3** | At least 1 must be a detail-level table | | markdown | 0 | Omit unless the user asks for notes/commentary | | **Total** | **34 – 39** | Self-check before delivery | **Enforcement rules (non-negotiable):** - You **must** list every card in `cards_plan` before calling `create_dashboard_project`; do not defer cards to later. - `card_id` in `cards_plan` must exactly match the `id` used in subsequent `create_dashboard_cards` calls. - If echarts count falls short, add same-type charts covering different dimensions or time ranges — do **not** lower the floor. - Before delivery, call `query_dashboard_cards` and count by `type`; if any type is below the required count, create the missing cards before proceeding. - These counts are overridden **only** when the user explicitly states they want a smaller dashboard. --- ## Workflow Summary **Path overview** - **New dashboard**: Planning prep (brainstorm + read sources) → Create dashboard project → Data cleaning → Dashboard development → Validate → Complete delivery - **Edit dashboard**: Project identification → Data cleaning (as needed) → Dashboard editing and card-tool maintenance → Validate → Complete delivery **Step details** - **Project identification**: Understand user needs and identify the target project (edit scenarios) - **Planning prep (new dashboards)**: Before `create_dashboard_project`, brainstorm questions and angles; **read sources in depth** (fields, grain, definitions, time, distributions, missingness, comparable dimensions), then author `cards_plan` strictly following the **mandatory counts in Quick Start** (metric ≥6, echarts 26–30, table 2–3, total 34–39)—**every card must be listed before project creation**; a handful of representative charts is not acceptable - **Create project**: Must call `create_dashboard_project` with the required `cards_plan` in the same call; the tool writes `cards_plan.md` from it; plan card identifiers must match `id` in later `create_dashboard_cards` - **Data cleaning**: From `cards_plan.md` and data goals, create and run `data_cleaning.py` in the project to supply data for the dashboard - **Dashboard editing**: Change allowed files as needed (e.g. data_cleaning.py, cleaned_data/, config.js; never modify or delete index.html, dashboard.js, index.css) (edit scenarios) - **Dashboard development**: Per `cards_plan.md`, use card tools (create_dashboard_cards, update_dashboard_cards, delete_dashboard_cards, query_dashboard_cards) to create or maintain cards - **Validate dashboard**: Call `validate_dashboard(project_path="PROJECT_NAME")`; fix errors and re-run until passing (do not delete cards to pass validation) - **Complete delivery**: Summarize the project and analysis results, then close the task **Core principles** Follow the steps in order; validation must pass before delivery or the page will not work. Never modify, overwrite, or delete `index.html`, `dashboard.js`, or `index.css`, or the data dashboard becomes unusable (maintain allowed files such as `data.js` only via card tools and other permitted paths). **Preferences** - New dashboards: **planning prep** first, then `cards_plan`; **strictly follow the mandatory card counts table in Quick Start** — metric ≥6, echarts 26–30, table 2–3, total 34–39; self-check with `query_dashboard_cards` before delivery - Prefer setting `title` on cards (skip on metric cards when it would duplicate the metric `label`) - Prefer ECharts; many charts → same-type charts across dimensions - Card standard size examples (24-column grid): metric `{w:4,h:3}`, chart `{w:8,h:8}`, table `{w:12,h:8}`, Markdown `{w:12,h:(calculate height based on content)}` --- ## Decision Tree New or edit dashboard? ├─ New → Planning prep (brainstorm, read sources) → Author cards_plan [metric ≥6, echarts 26–30, table 2–3, total 34–39, ALL cards listed] → create_dashboard_project → Data cleaning → Dashboard development → Validate → Complete delivery └─ Edit → Identify existing dashboard project → Data cleaning (as needed) → Dashboard development/editing → Validate → Complete delivery Need data cleaning? ├─ New dashboard → Must execute data_cleaning.py ├─ Edit dashboard with data/requirement changes → Execute as needed └─ Edit dashboard without changes → Can skip Card count check before delivery? ├─ call query_dashboard_cards → count by type ├─ metric < 6 or echarts < 26 or table < 2 → create missing cards first └─ counts met → proceed to validate Validation failed? → Fix issues and re-run validate_dashboard until result.ok with no errors --- ## Core Tools ### create_dashboard_project — Create Dashboard Project | Param | Required | Type | Description | | ------------ | -------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | Yes | string | Project name; the dashboard is created under this directory in the workspace | | `cards_plan` | Yes | array | Card plan list (at least one item); the tool generates `cards_plan.md` from this; field definitions and how to author entries are in the tool usage example below | Finish **Planning prep**, then author `cards_plan`. For new dashboards, the mandatory per-type counts are defined in Quick Start under **Default card counts for new dashboards** (metric ≥6, echarts 26–30, table 2–3, total 34–39). **You must list every card in `cards_plan` before calling this tool — partial plans are not allowed.** Only if the user explicitly requests a reduced dashboard may you go below these counts; otherwise every card must be listed upfront. You may call `create_dashboard_cards` in batches after project creation. This tool does not validate counts — it is your responsibility to meet them. **Return (`result`)**: On success `result.ok` is true and `result.content` includes the created path and related information; on failure `result.ok` is false and `result.content` contains the error (e.g. "Directory already exists"). ### validate_dashboard — Validate Dashboard | Param | Required | Type | Description | | -------------- | -------- | ------ | ------------------------------------------------------------ | | `project_path` | Yes | string | Dashboard project directory path, relative to workspace root | **Return (`result`)**: On success `result.ok` is true with no errors; on failure `result.ok` is false and `result.content` contains validation failure reasons. **Validation must pass before delivery; otherwise the page will not be accessible.** ### Card Management Tools You must use the card management tools to work on `data.js`; direct editing is strictly prohibited. Card fields and CardData are defined under Card Data DSL below; layout workflow and validation are under Dashboard Development. | Tool | Description | | ---------------------- | -------------------------------------------------------------------------- | | create_dashboard_cards | Batch create; prefer ≤6 `cards`/call; `auto_layout` (may omit `layout`) | | update_dashboard_cards | Batch update; 1–10 `updates`/call, prefer ≤6; single-field edits supported | | delete_dashboard_cards | Batch delete; `card_ids` 1–20; auto-compacts layout after delete | | query_dashboard_cards | Query all or by id; optional `fields` to filter returned properties | **create_dashboard_cards** `auto_layout` (default false): When true, omit per-card `layout`; the tool generates gap-free layout by type order to reduce validate churn. Recommend `auto_layout=true` for new dashboards. Prefer about 6 or fewer `cards` per call when feasible (not a hard cap). | Param | Required | Type | Description | | -------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------ | | `project_path` | Yes | string | Dashboard project path | | `cards` | Yes | List | Card list; each item has id, type, source, getCardData; when auto_layout=true, `layout` may be omitted | | `auto_layout` | No | boolean | When true, omit `layout` and let the tool fill the grid | **update_dashboard_cards** Each update must include `id` and at least one other field to change (type, source, title, titleAlign, layout, getCardData, etc.). `layout` accepts partial objects (e.g. only `y`). | Param | Required | Type | Description | | -------------- | -------- | ------ | ---------------------------------------------- | | `project_path` | Yes | string | Dashboard project path | | `updates` | Yes | List | Update objects, 1–10 items; prefer ≤6 per call | **delete_dashboard_cards** | Param | Required | Type | Description | | -------------- | -------- | --------- | ---------------------------------------- | | `project_path` | Yes | string | Dashboard project path | | `card_ids` | Yes | List[str] | IDs to delete, 1–20 items, no duplicates | **query_dashboard_cards** | Param | Required | Type | Description | | -------------- | -------- | --------- | ---------------------------------------------------------------------------------------------- | | `project_path` | Yes | string | Dashboard project path | | `card_ids` | No | List[str] | Omit for all cards; if set, 1–20 IDs |