analytics-design-tool-agnostic

name: Analytics Design (Tool-Agnostic) description: Analyst brain — NGHĨ, ĐỊNH NGHĨA, và THIẾT KẾ analytics artifacts. Không phụ thuộc vào bất kỳ BI tool nào.

Analytics Design Skill

Location: .skills/analytics-design/ — tool-agnostic analyst knowledge. Đây là "analyst brain" — sở hữu và tạo ra toàn bộ analytics artifacts trừ blueprints. Blueprints thuộc về .skills/metabase-automation/ (engineer brain).

Multi-tool architecture: Blueprint path dùng subfolder theo tool — blueprints/metabase/ cho Metabase, blueprints/evidence/ cho Evidence.dev (khi có). Mỗi playbook khai báo **Tool:** field để xác định tool target. Mapping: 1 playbook → 1 blueprint → 1 tool. Plan 260528-1325-tool-agnostic-design-spec đã defer — architecture hiện tại là Workflow C (no design-spec intermediate layer).

Overview

Skill này cung cấp knowledge framework cho các quyết định analytics & design:

• WHAT to measure (domain modeling, metric definitions)
• WHY this dashboard exists (audience, purpose, playbooks)
• HOW to communicate data (visualization selection, composition, visual language)

Skill này KHÔNG BIẾT gì về Metabase, Superset, Looker, hay bất kỳ BI tool cụ thể nào. Mọi output đều dùng standard vocabulary (xem VISUALIZATION_VOCABULARY.md).

Knowledge Documents

Đọc theo thứ tự phase đang thực hiện:

Quy tắc: Chỉ đọc document cần thiết cho phase hiện tại. KHÔNG đọc .skills/metabase-automation/* trong Phase 0-6 (trừ khi cần kiểm tra tool feasibility — xem Exception bên dưới).

Templates

Khi tạo domain file mới, template phải giữ nguyên block định nghĩa sau ngay dưới H1 title:

> **Domain Document định nghĩa cách một nhóm nghiệp vụ được hiểu và đo lường trong hệ thống analytics.**
> Tài liệu này xác định phạm vi domain, các câu hỏi phân tích nền tảng, các metric liên quan, cùng định nghĩa nghiệp vụ và logic tính toán chuẩn cho từng metric.
> Đây là nguồn tham chiếu chính thức cho business logic; dashboard, playbook, design spec và blueprint phải tham chiếu lại tài liệu này thay vì tự định nghĩa lại metric.

Mỗi context trong domain file dùng cấu trúc chuẩn: Context Overview table → Analytical Questions → Metrics. Trước phần metric, làm rõ category, câu hỏi phân tích nền tảng, metric liên quan, data đã sẵn sàng, data/cấu phần còn cần thêm, và insight/action mà từng câu hỏi kích hoạt. Trong phần metric, Business Definition phải giải thích sâu nghiệp vụ, logic tính toán, phạm vi/loại trừ, hiểu lầm thường gặp, và các lỗi report/query dễ mắc. Giữ cả Formula và Logic (SQL): Formula mô tả công thức business/math ngắn gọn; Logic (SQL) chứa SQL có thể tái sử dụng.

Khi tạo playbook file mới, template phải giữ nguyên block định nghĩa sau ngay dưới H1 title:

> **Tài liệu này mô tả mục đích và cách sử dụng dashboard/report từ góc nhìn người dùng nghiệp vụ.**
> Nó giải thích dashboard dành cho ai, dùng để trả lời câu hỏi nào, cần đọc theo luồng nào, dùng những metric nào từ domain documents, và khi thấy tín hiệu bất thường thì ai cần làm gì.
> Playbook không định nghĩa công thức tính metric; mọi logic nghiệp vụ phải được tham chiếu từ `domains/`.

Khi tạo design spec file mới, template phải giữ nguyên block định nghĩa sau ngay dưới ## Design Spec: ... title:

> **Tài liệu này là bản thiết kế tool-agnostic cho dashboard/report.**
> Nó chuyển playbook thành cấu trúc trình bày cụ thể: views, card roles, loại biểu đồ chuẩn, bộ lọc, thứ tự đọc, so sánh cần có, màu sắc/kích thước theo semantic tokens và các yêu cầu trải nghiệm phân tích.
> Design spec là hợp đồng giữa Analytics Design và bước triển khai BI; nó không phụ thuộc vào bất kỳ công cụ BI hay nền tảng triển khai cụ thể nào, nhưng được dùng làm input để tạo blueprint triển khai cho công cụ BI được chọn.

Artifact Ownership

Thứ tự tạo artifact (bắt buộc):

domain → playbook → [guide] → design spec → blueprint → deploy

Mỗi artifact downstream tham chiếu artifact upstream:

• Playbook tham chiếu domain ("xem domains/sales.md cho định nghĩa Net Revenue")
• Design spec tham chiếu playbook + domain
• Blueprint tham chiếu design spec + domain

Phase 0-6 Process

Phase 0 — Domain Modeling

Input: User request — xác định domain nào cần.

1. Kiểm tra domain đã tồn tại? → Quét docs/analytics-handbook/domains/
2. Nếu đã có → Đọc file, kiểm tra metrics cần thiết. Thiếu → cập nhật thêm.
3. Nếu chưa có → Tạo mới theo templates/domain_template.md, giữ nguyên block định nghĩa Domain Document ngay dưới H1 title.
4. Khi thêm/cập nhật context, luôn viết theo thứ tự Context Overview → Analytical Questions → Metrics.
5. Đọc DOMAIN_MODELING.md cho conventions và quy tắc.

Output: docs/analytics-handbook/domains/<domain>.md

Phase 1 — Playbook Creation

Input: Domain knowledge + user request (audience, mục đích).

1. Kiểm tra playbook đã tồn tại? → Quét docs/analytics-handbook/playbooks/
2. Nếu đã có → Đọc, cập nhật nếu audience/purpose thay đổi
3. Nếu chưa có → Tạo mới theo templates/playbook_template.md, giữ nguyên block định nghĩa Playbook ngay dưới H1 title.
4. Tool field BẮT BUỘC: Thêm **Tool:** metabase (hoặc evidence) vào block ## Overview. Tool xác định blueprint format và subfolder deploy path (blueprints/{tool}/). Default = metabase nếu ops/interactive; evidence nếu report/shareable/executive.
5. Blueprint field: Cập nhật path theo subfolder mới — ../blueprints/{tool}/{name}.md.
6. Action Triggers table là BẮT BUỘC. Mỗi metric chính phải có ít nhất 1 threshold + owner + action.
7. Reading Flow là BẮT BUỘC. Mô tả đường đi từ hero card → investigation → escalation.

Output: docs/analytics-handbook/playbooks/<name>.md

Phase 2 — Guide Creation (conditional)

Input: Domain + playbook — có concept phức tạp cần giải thích riêng không?

• Ví dụ cần guide: Health Score composite, revenue terminology, cohort analysis
• Nếu không có concept mới → Bỏ qua, chuyển sang Phase 3

Output: docs/analytics-handbook/guides/<topic>.md — hoặc bỏ qua.

Phase 3 — Design Brief

Input: User request + domain + playbook.

Xác định: Audience, Purpose, Hero Metric, Comparison Frame, Time Budget, Archetype. Xem COMPOSITION_PATTERNS.md cho Design Brief fields.

Phase 4 — Composition Design

Input: Metrics (Phase 0) + Brief (Phase 3). Đọc COMPOSITION_PATTERNS.md.

• 4a: Card Role Assignment (hero/supporting/trend/breakdown/detail/annotation)
• 4b: Narrative Flow (arc kể chuyện)
• 4c: Spatial Grouping (relative sizing)
• 4d: View Grouping (single vs multi-view)
• 4e: Constraints & Filter Design (business constraints + interactive filters)
• 4f: Companion Card Identification (text cards, comparisons)

Phase 5 — Visualization Selection

Input: Each card from Phase 4. Đọc VISUALIZATION_VOCABULARY.md.

Chọn viz type bằng standard vocabulary dựa trên: Card Role × Data Shape × Communication Goal.

Dùng decision tree trong VISUALIZATION_VOCABULARY.md. Anti-pattern check bắt buộc.

Phase 6 — Enrichment Check

Input: Card + viz type. Đọc COMPARATIVE_FRAMING.md + VISUAL_LANGUAGE.md.

• 6a: Comparative Framing — mọi KPI cần ≥1 so sánh
• 6b: Data Completeness cho viz type đã chọn
• 6c: Narrative Support — viết annotation content theo templates trong COMPOSITION_PATTERNS.md Section 8
• 6d: Action Map — điền bảng Action Map cho mỗi card có signal quan trọng (xem templates/design_spec_template.md)
• 6e: Dashboard Finish Checklist — chạy full checklist trong VISUAL_LANGUAGE.md Section 10 trước khi finalize

Output: Design Spec → lưu tại docs/analytics-handbook/designs/<name>.md, giữ nguyên block định nghĩa Design Spec ngay dưới ## Design Spec: ... title.

Fast-Track Rules

Không phải mọi dashboard đều cần 7 phases đầy đủ:

Full path (7 phases): Dashboard mới, domain mới, >5 cards, hoặc multi-view. Fast-track (3-5 phases): Domain + playbook sẵn có, ≤5 cards → skip Phase 0-2, collapse Phase 3-6. Khi nghi ngờ → dùng full path.

Iteration Workflows

Flow A — Thêm metric vào dashboard có sẵn: Phase 0 (update domain nếu cần) → Phase 4-6 (update design spec: thêm card, gán role/viz/color/size) → chuyển cho engineer Phase 7-10.

Flow B — Redesign dashboard cũ: Phase 3-6 (tạo MỚI hoặc update design spec, giữ metrics, redesign composition + viz) → chuyển cho engineer Phase 7-10.

Flow C — Hotfix blueprint trực tiếp (bypass design): Sửa trực tiếp blueprint (Phase 9 only) → Deploy → Đánh dấu design spec là STALE.

Failure Modes

Tool Selection (Phase 1 — khi tạo playbook)

Reference: docs/analytics-handbook/guides/tool-selection-guide.md — đọc khi cần reasoning đầy đủ.

3 tools deployed: metabase (bi.lan.fwg.vn), rill (rill.lan.fwg.vn), evidence (planned).

Chọn rill khi: User cần tự do explore ad-hoc, không biết câu hỏi trước, metrics đã định nghĩa nhưng layout chưa xác định. Rill dùng YAML blueprint (blueprints/rill/) và playbook structure riêng (playbooks/rill/).

Default: metabase. Chỉ chọn evidence khi đáp ứng đủ tất cả điều kiện sau:

✅ Không cần cross-filter (click chart → filter chart khác)
✅ Không cần email alert / subscription
✅ Cadence weekly hoặc monthly (không phải daily ops)
✅ Mart parquet nguồn < 250MB
✅ Format chính là report / document (không phải operational tool)

Archetype → Tool nhanh:

• Operational Cockpit → metabase
• Executive Pulse (weekly/monthly) → evidence
• Exploratory Tool / Metrics Explorer (ad-hoc) → rill
• Report Document (shareable) → evidence
• Reconciliation / Data Quality Monitor → metabase

Evidence + Data Loader (khi mart > 250MB nhưng muốn dùng Evidence): pre-aggregate server-side tại build time → output parquet < 50MB → bake vào static site. Xem tool-selection-guide.md §Evidence Data Loaders.

Tool Feasibility Exception

Trong Phase 5, nếu cần kiểm tra "BI tool có hỗ trợ viz type này không?":

• Metabase: scan cột Metabase Support trong VISUALIZATION_VOCABULARY.md — KHÔNG cần đọc full METABASE_VIZ_CATALOG.md.
• Evidence.dev: dùng ECharts-based components (AreaChart, LineChart, BarChart, ScatterPlot, FunnelChart, Heatmap, DataTable, BigValue). Tất cả standard viz types đều supported. Không có gauge hay progress-toward-goal native. Xem .skills/evidence-automation/SKILL.md cho full syntax + deploy.