Data Analysis Skill
AI-native structured data analysis: a universal 0+9 workflow + pluggable domain packs. This file is the entry point (domain detection + critical rules + pointers); detailed procedures are loaded on demand from references/ and the selected domain pack. This Skill remains domain-neutral—any domain knowledge resides in domains/<name>/, and this file does not reference any specific domain name.
How it works — 0+9 workflow
Step 0 domain detection is in this file; Steps 1–9, their procedures, what to load at each step, and what to produce are all in references/9-step-framework.md (the single authoritative per-step loading table). Always load it first when starting any analysis.
| Step | One-liner |
|---|---|
| 0 Domain Detect | Read resolver → route to domain pack (or generic) |
| 1 Profile | Agent writes a live profiling: columns → field roles, period/snapshot determination, compute data gap |
| 2 Signal Scan | Live signal scan (anomalies / significant changes / index vs baseline deviations) |
| 3 Clarify | Only ask when ambiguity or data limitations block the request (present the gap to the user here) |
| 4 Frame | Build a MECE issue tree using the domain framework.md |
| 5 Hypothesize | Falsifiable hypotheses, attached to domain levers |
| 6 Verify | Live pandas verification → verdicts.json |
| 7 Decompose | Live decomposition → drivers.json |
| 8 Synthesize | Pyramid output + domain insight extension; default two outputs in parallel: insight_deck.html (HTML deck) + insight_report.md (1:1 mirror), passed through the deck_audit third gate (Quick/follow-up may skip the deck) |
| 9 Follow-up | Extend the issue tree to answer subsequent questions |
Fully instruction-based, no pre-written scripts: The code for Steps 1/2/6/7 is written and executed live by the agent—but before writing, the agent must first read the real data and the selected domain's
data-spec/glossary/computation-reference, understand the data's own field names and period definitions, then generate code according to the instructions. No hardcoded field names or period terms (LY/TY/MAT are not universal). Field role mapping is an AI semantic judgment (readdata-spec §1.0).
Step 0 — Domain Detection (Entry Decision)
- Read
references/resolver.md(domain-neutral scoring mechanism) and enumerate alldomains/<slug>/triggers.md(each domain's trigger block). - Score each domain using "user phrasing / data columns (after Step 1) / project hint file
./.data-analysis-domain". - Route: ≥2 signals point to the same domain → silent route; ambiguous → let the user choose via
clarification-protocol.md; zero matches → generic mode and inform user. - Read the selected
domains/<slug>/README.md; other slots are loaded at the corresponding steps according to the 9-step loading table. - Record
outputs/analysis_state.json::domain_selected; reuse in subsequent turns without re-detection.
Critical rules (non-negotiable; details in references/anti-hallucination.md)
- LLM must NEVER compute numbers. Aggregation / shares / indices / decomposition → always agent writes and executes live pandas; no LLM-derived numbers in the output.
- Every number must reference a
verdict_idthat can be traced back tooutputs/verdicts.json. - Detect first, then clarify. Do not ask "what do you want to analyze?" before completing Steps 0–2; default to doing the analysis directly, and adjust afterward if needed.
- Persistent state. Read
outputs/analysis_state.jsonat the start of each turn, and update it before replying. - Coverage: no silent leaf drops. Every data-feasible leaf in the issue tree (Step 4) must be either answered or explicitly skipped (with a reason) in Step 6; "not enough time" is not a valid reason. Step 8 critic verifies coverage. See Step 6 coverage gate in
references/9-step-framework.md. - Default deliverable = deck + report, not inline conversation. Any structured data analysis request by default runs the full 0+9 workflow and produces
outputs/insight_deck.html+outputs/insight_report.md(written to disk, passed throughdeck_audit) — this is the default deliverable, not an "optional bonus." Dropping a few tables or text snippets in the conversation ≠ completing the analysis (that means Step 8 was not reached). A focused/specific analytical question (e.g., "look at the distribution of X" or "who was winning in this period?") is not a "lightweight request" — it still runs the full pipeline and outputs a deck. The only two exemptions: ① Step 9 follow-up (follow-up questions on a completed analysis); ② User explicitly asks for a "quick / brief / verbal answer." When exempted, the reply must explicitly state "this turn follows lightweight mode, no deck produced." See details inreferences/9-step-framework.mdStep 8 +references/insight-templates.md.
Domain packs
A pack = a set of generically named .md slots: triggers (Step 0 domain detection trigger block) · glossary · data-spec · framework · computation-reference · insight-extensions · context-notes · clarification-extensions · business-rules.md.
Slot protocol, who fills it, three content types, maintenance flow → references/domain-pack-protocol.md (single authoritative source). To generate/maintain a pack → domain-pack-builder skill.
Adding a new domain
Create domains/<new>/ and fill all required slots (including triggers.md trigger block). This Skill and other generic files remain unchanged—the resolver mechanism automatically enumerates the new pack's triggers.md.
v0.9 (2026-06-09 deck gate symmetrization): Upgraded HTML deck from a "default buried inside Step 8 slot file" to a framework-level hard exit condition—Step 8's loading table (Outputs column), Outputs section, Critic section, and Exit condition unified to "default two outputs in parallel: insight_deck.html + insight_report.md (1:1 mirror), passed through the deck_audit.py third gate (at the same level as data_integrity + coverage)"; quick/Step-9 follow-up may skip the deck but must explicitly state so. Fixed real-world gap: focused questions only wrote a .md report and considered Step 8 complete, with the deck silently missing (root cause: insight-templates.md + insight-extensions.md were not loaded, so the Outputs section now adds a hard reminder "read both slots first"). Maintained domain-neutrality at the generic level (deck/audit are generic concepts; design system / forbidden words / font sizes / logo-IDs are all read from the domain at runtime).
v0.8 (2026-05-30 robustness hardening): Added coverage gate (critical rule 5, no leaf silent drops); Step 2 data integrity checks (share sums / embedded aggregate rows); Step 7 decomposition granularity iron rule; multi-level header taming pattern; scripts unified under outputs/scripts/ + naming convention + schema fingerprint reuse (same schema data retransmitted does not rewrite loaders); Step 8 forces insight_report.md to disk. Also cleaned residual domain-specific traces from the generic layer (reset to domain-neutral). v0.7: Fully instruction-based (removed pre-written scripts). v0.6: Skill Creator normalization.