echart-skill

# EChart Data Analysis Skill Use this skill to turn structured data into evidence-backed analysis and standalone ECharts deliverables. The invariant is not “an HTML file exists”; it is that the data, metric definition, analysis claim, visual expression, and live browser result all reconcile. ## Required pipeline Follow these stages for every analysis. Read only the references needed for the requested deliverable. For recurring work, first run `python scripts/project_task.py list` from the user project. Read **Reusable analysis tasks** in `workflow_specs/report_workflow.md` when asked to save/repeat a successful analysis or a relevant task exists. Match task purpose, not just a default name. Reuse approved SQL and templates; do not redesign the analysis or copy last run's numbers/conclusions. `resolve` returns questions for missing parameters: ask before executing. Ambiguous task/period/filter means pause, never guess. Changed SQL, templates, cleaning, metrics or report profiles require renewed review. 1. **Resolve data and business scope** - Read `workflow_specs/project_data_context.md` and run `python scripts/project_data_context.py resolve --query "<request>"` before searching directories, assuming a local database, or asking for a connection that may already be configured. - Use a resolved source; refresh `needs_refresh`, ask when `ambiguous`, and register any newly used project file. The canonical index is the project's `.echart-skill/data_sources.json`, never a file inside this Skill. - Inspect schema with maintained CLIs; do not load large tables into context. - Run `python scripts/metrics_manager.py effective` before defining metrics, filters, governed entity sets, comparison scope, or business terminology. - Never invent fields or approximate a governed set with keyword matching. 2. **Assess data fitness** - Discover project cleaning via `python scripts/project_cleaning.py status`. Read `workflow_specs/data_cleaning_workflow.md` for registration/approval. Rules live in `<project>/config/data_cleaning/`, never in this Skill. `sql_runner.py` and `analysis_runner.py` automatically apply approved rules to registered local DuckDB tables before aggregation. Do not substitute a different runner or raw source to bypass a cleaning failure. - When asked to remember a cleaning rule, register it in the project manifest, preview its impact, and approve only the user-confirmed scope. Subsequent analysis reuses it without another long prompt. Unknown/new/changed rules require confirmation; no rules means unchanged data, not guessed cleaning. - Run from the user project (absolute Skill script paths), or set `ECHART_PROJECT_ROOT` explicitly. External sources must be imported/refreshed through the maintained import path and bound to a local table; never clean remote production tables in place. Verify snapshot freshness before analysis. - Check date coverage, incomplete periods, nulls, duplicates, grain, uniqueness, units, currency, timezone, status filters, and known exclusions. - Use `scripts/data_quality.py` or `scripts/data_contract.py` when relevant. 3. **Query through the audited execution path** - Generate reviewable SQL and execute it with `scripts/sql_runner.py`, `scripts/db_cli.py`, or `scripts/db_manager.py`. - Never write temporary database connection code, heredoc Python, `duckdb.connect`, `psycopg.connect`, `pymysql.connect`, `create_engine`, `.cursor()`, or `cur.execute()`. - Write query results with `--out` so query hash and lineage metadata exist. 4. **Plan the analytical expression** - For Dashboards, first read `workflow_specs/dashboard_workflow.md` and run `python scripts/project_dashboard.py resolve` from the user project. Load registered project experts, required methods, layout and chart preferences. Read all referenced expert files; missing/changed profiles never silently fall back. This registry is independent of report profiles. - For reports, first read `workflow_specs/report_workflow.md` and run `python scripts/project_report.py resolve` from the user project. Reuse its analysis obligations, section order, layout and chart preferences. Read each referenced project expert note completely. Explicit task overrides take precedence but must not silently change the saved default. - When asked to remember a report scheme, save it under the user's `config/reports/`, register it in `manifest.json`, and validate with `resolve`. Never save business methods or branding inside this Skill. Dashboard schemes and project experts similarly live under the user's `config/dashboards/` (expert Markdown may live elsewhere inside that project). Set the requested default once; later requests reuse it without re-asking. - Read [analysis expression quality](workflow_specs/analysis_expression_quality.md). - Write an analysis-plan JSON and run `python scripts/validate_analysis_plan.py <plan.json>`. - Use Message → Relation → View. Select views through `references/chart_capabilities.json` or `python scripts/chart_capabilities.py <view-request.json>`. - Distinguish the hidden audit/source table from a visible analytical companion table. 5. **Bind evidence instead of restating it** - Read `workflow_specs/artifact_evidence_contract.md`. - Create a draft artifact manifest that references actual query result files. - For compiled charts, pass `--evidence <draft.json>` to the builder; it binds and validates before publishing. Custom HTML uses `python scripts/artifact_manifest.py bind <output.html> <draft.json>`. - The binder computes query-result SHA-256, row count, date coverage, and binds query hashes, metric/scope fingerprints, comparisons, charts, and findings into the HTML. 6. **Compile charts and compose the layout** - Read `references/chart_guide.md`. For supported common charts, use `scripts/chart_builder.py` with explicit query-result field mappings. Use `--evidence` to require the full gate before replacing the output. Do not copy demo arrays or rewrite the maintained bootstrap. - For specialized views, retrieve one archived reference through `scripts/reference_assets.py get <name>` and verify its dependencies. Old demo replacement instructions are superseded by the chart guide. - Dashboard: read `workflow_specs/dashboard_workflow.md` and `workflow_specs/dashboard_runtime_quality.md`. Use `scripts/project_dashboard.py build <spec.json> --evidence <draft.json> --output <dashboard.html>` for supported views. It applies the project scheme, binds KPI values directly to query results, and runs full gates. - Report: use `scripts/project_report.py build <spec.json> --evidence <draft.json> --output <report.html>`. It applies the resolved profile and blocks missing methods/evidence, stale profiles and unexplained view overrides. Methods require actual audited queries or visible data gaps, not canned conclusions. No configured profile uses generic defaults. - Report/Dashboard specs require `statistical_scope`: source, date coverage, grain, metric formulas, grouping, filters/exclusions, cleaning, unit, currency, timezone and limitations. It is visible globally, per section and per chart; override where scope differs. Do not invent missing metadata or fill with boilerplate. Ask or disclose unknowns and avoid affected claims. - Use the project generators' responsive shells or a configured passive project HTML shell; validation is mandatory. The dashboard_light.html template remains a reference for separately verified custom dashboards. 7. **Run the complete delivery gate** - Run `python scripts/validate_delivery.py <output.html>`. - This combines static ECharts/runtime checks, governance checks, manifest reconciliation, and a real Playwright/Chromium render. - Any console error, page error, external request, missing ECharts instance, zero-size canvas/SVG, evidence mismatch, or invalid comparison blocks delivery. - Mark all custom chart roots `data-echart-chart`; retain compiler contracts. Every expected chart must initialize. Compiled series data and axes must match the specification, with desktop and mobile render checks. - Source-data controls must pass actual open/close clicks on desktop/mobile, not merely contain a handler name. Scope text must be visible. Label query tables as potentially aggregated/masked, not raw transaction records. Raw-detail drill-down needs separate audited, authorized, privacy-safe data. Legacy buttons must indicate expanded/collapsed state; place revealed data near its control or bring it into view. Off-screen expansion without feedback is not a usable interaction. Native details/summary is preferred. - `--allow-static-only` is a degraded exception only when browser execution is genuinely unavailable; disclose that reduced assurance. ## SQL execution contract Preferred examples: ```bash python scripts/schema_manager.py show <table> python scripts/sql_runner.py --db workspace.duckdb --file queries/<task>.sql \ --output json --out outputs/query_results/<task>.json python scripts/sql_runner.py --profile <profile> --file queries/<task>.sql \ --output json --out outputs/query_results/<task>.json ``` For one-off external connections, pass credentials only through approved environment-backed CLI parameters such as `--password-env` or `--dsn-env`. Project queries, connection profiles, outputs, logs, and generated packages are local state and must never be added to the reusable skill release. ## Comparison and metric correctness All YoY, QoQ, MoM, WoW, period, and cohort comparisons must declare: - current and baseline start/end; - complete or partial status; - latest complete period; - calendar type: calendar, fiscal, retail 4-4-5, or custom; - alignment rule and comparability; - visible current/baseline labels; - evidence query IDs and metric IDs; - identical current/baseline fingerprints for metric definition, entity scope, filters, unit, currency, and timezone. YTD-versus-full-year and partial-versus-complete comparisons are blocking failures. Fiscal and retail calendars align governed named periods rather than being forced onto calendar-month boundaries. An HTML comparison must contain both `analysis-comparison-contract` and `analysis-artifact-manifest`. The declared windows must match each other and the actual dates in the bound query result files. Before computing any change, validate both windows with `validate_comparison`. `analysis_runner.py period-compare` requires `--comparison-contract <json>` and checks daily coverage per group in the same SQL; failure produces no result file. The legacy category comparison command rejects recognized temporal labels. Complete calendar MoM/QoQ requires whole adjacent months/quarters; WoW requires adjacent seven-day windows. Partial windows require equal elapsed days and aligned starts. Never fix a failed check by changing `partial` to `complete`. Missing dates block comparison even when min/max dates look correct: bind daily coverage evidence for every day in both windows (see artifact evidence contract). Unknown/no-activity days are not interchangeable; never fabricate zero rows. Numeric YoY/MoM/etc. table rows, including hidden chart source tables, must carry `comparison_id`, `current_start/end`, `baseline_start/end` from query results; generators preserve these as `data-*` attributes and the gate reconciles each row with its registered contract. One valid page-level comparison does not cover other rows. For incomplete or unavailable baselines output null/“—” with a reason, not a growth number plus a disclaimer. Apply this to ratios as well as totals; remove dependent conclusions/actions when a comparison is invalid. Do not imply complete analytical correctness from browser or structural validation alone. ## Findings and analytical depth Every major finding must state What, baseline, Why status, Why, So what, next check, evidence references, and limitations. - `tested`: allowed only when the artifact manifest references an executed next check query. - `hypothesis`: a plausible explanation that still needs testing. - `unknown`: insufficient evidence; state the missing data. Correlation, ranking, trend, anomaly, and composition detectors produce descriptive candidates, not causal conclusions. Drill down through contribution, segment, volume × rate/price, anomaly/data-quality, and stability/sample-size checks when the data supports them. ## Visual and table contract - Prefer position and length encodings over angle, area, volume, and decorative effects. - A pie chart is limited to 2–3 positive categories and approximate share. - Use a visible companion table for exact lookup, high-density comparison, exceptions, risk/action lists, or four-plus measures. - Every chart still needs a default-hidden `查看数据` source table, chart-level statistical scope, data source, and evidence/query reference. - Include units, readable labels, semantic colors, responsive sizing, and a text/table fallback. Do not rely on color alone. - Do not invent a product, brand, industry label, or title that is absent from the request, governed scope, schema, and evidence. - Mixed bar/line charts with different units or magnitudes require separate y-axes and explicit `yAxisIndex: 0` / `yAxisIndex: 1` assignment. ## Standalone HTML and runtime contract - Inline ECharts and required local assets; no CDN, runtime loader, `fetch()` to external URLs, iframe/object/embed, self-navigation, or `file://` nesting. - Load libraries before chart bootstrap. Use literal `</script>` closing tags. - Serialize data with `json.dumps(..., ensure_ascii=False, default=str)`; never hand-write large JavaScript data objects or call `JSON.parse({...})`. - Use real responsive chart dimensions and resize handling. - Dashboard runtime rules cover map registration including accidental `chinaGeoJSON` references, PDF export compatibility including `color-mix()`, card/grid density, data-table controls, and export/download behavior. ## Routing references | Request | Read | |---|---| | Import or cleaning | `workflow_specs/data_cleaning_workflow.md` | | Locate database/file data | `workflow_specs/project_data_context.md` | | Chart selection | `workflow_specs/analysis_expression_quality.md`, `references/chart_capabilities.json` | | Dashboard | `workflow_specs/dashboard_workflow.md`, `workflow_specs/dashboard_runtime_quality.md` | | Report | `workflow_specs/report_workflow.md` | | Save/repeat tasks, parameterized SQL | `workflow_specs/report_workflow.md` → Reusable analysis tasks | | Domain analysis | `workflow_specs/expert_library/INDEX.md` | | Domain dashboard | `workflow_specs/dashboard_expert_library/INDEX.md` | | Individual commands or CLI detail | `commands/echart/*.md` | When adding a reusable dashboard expert, start from `workflow_specs/dashboard_expert_library/DASHBOARD_EXPERT_TEMPLATE.md`; never place a project-specific dashboard or query in the skill. ## Release hygiene Run: ```bash bash package.sh python scripts/validate_release_package.py dist/<package>.zip # For upload limits: four-file package with the same common-chart engine/gates python scripts/build_skill_package.py --mode portable --output dist/echart-portable.zip ``` The package uses an allowlist. Project SQL, database connection files, outputs, logs, caches, tests, and local indexes are forbidden release content. The portable package embeds its tools in runtime.zip, verified and expanded by bootstrap.py in the user project's .echart-runtime cache. Python and browser runtimes are still required; specialized historical demos/GL use the full package.