detective

Name: detective
Author: QinghongLin

146stars19forks

How to install detective?

qinghonglin/data2story-skill/detective

$npx -y skills add QinghongLin/data2story-skill --skill detective

Installs into the current project.

Summary

Research external context for a dataset — domain background, history, related studies, and why this data matters. Outputs detective.json (structured findings with det_xx IDs) before any analysis begins.

Files · 1

View on GitHub

SKILL.md

1	# Detective
2
3	Your job is context. Before anyone touches the numbers, you find out what world those numbers live in.
4
5	You are not analyzing the data. You are answering: what does a smart, curious reader need to know to make sense of this data? What happened in the real world that explains what's in this dataset?
6
7	## Setup
8
9	- `DATA_DIR` = first argument
10	- `PROJECT_DIR` = second argument
11	- Quickly read the data files in `DATA_DIR` to understand the topic (column names, a few rows) — do not analyze
12	- Output: `PROJECT_DIR/detective.json`
13
14	## Steps
15
16	### 1. Identify the Domain
17
18	From a quick scan of the data, determine:
19	- What subject area is this? (psychology, sports, ecology, economics, etc.)
20	- Who collected this data and why?
21	- What real-world phenomenon is being measured?
22
23	### 2. Research Background
24
25	Search for external context relevant to this dataset. Look for:
26
27	- Origin: Who created this data, when, and for what purpose? Link to the original study or source.
28	- Domain knowledge: What does the field already know about this topic? What are the established findings?
29	- Related work: Are there other studies, datasets, or analyses on the same topic? What did they find?
30	- Why it matters: What is the real-world significance? Why would a general reader care?
31	- Controversies or debates: Are there contested interpretations, known limitations, or ongoing debates in this area?
32
33	### 3. Identify Interpretive Hooks
34
35	Flag anything from your research that could:
36	- Provide surprising context for what the data shows
37	- Explain an anomaly the analyst might find
38	- Connect the data to something readers already know about
39	- Change how a finding should be interpreted
40
41	### 4. Collect Reference Media (a default step for visual/geographic/event/sports datasets)
42
43	Real-world media helps the Designer build a multimedia-rich page, so collecting it is a default part of your job, not optional, for visual, geographic, event-based, cultural, historical, product, animal, art, place, food, fashion, sports, and scientific datasets. Use the helper scripts in this skill's `scripts/` folder — `fetch_images.py`, `fetch_logos.py`, `fetch_flags.py` — to pull real Wikimedia/Commons photos, crests and flags, and record each in `reference_media` (prefer real photos over AI for concrete subjects). For music/sport/art/event datasets, also collect 3-8 embeddable `instances` (verified per [`references/instance_verification.json`](references/instance_verification.json)). Only for abstract, text-only, technical, privacy-sensitive, or purely statistical datasets may you collect little or none — and then record why, so the Designer knows the omission is intentional.
44
45	> ⚠ Wikidata P18/P154/etc. are sometimes mis-mapped, and `fetch_images.py` does NOT check the subject. Any real-subject image MUST be vision-confirmed (`vlm_view`) before it reaches the page — the Scout/Auditor gate Scouted media, and a Detective-sourced `ref_` image needs the same check.
46
47	While researching, actively hunt for real-world media:
48
49	- Photos: relevant real-world images (Creative Commons, public domain, or press photos with source attribution)
50	- Videos: YouTube clips, news footage, documentary segments — save the URL, not the file
51	- Data visualizations: existing charts or infographics from other analyses of this topic
52	- Maps / diagrams: geographic or structural visuals related to the domain
53	- Logos / icons: if the data involves specific organizations, teams, or brands
54
55	For each useful piece of media found:
56	- Download images to `PROJECT_DIR/assets/ref_*.{png,jpg}` (prefix with `ref_` to distinguish from generated assets)
57	- For videos: record the URL in the JSON (do not download large video files)
58	- Note the source and license for each item
59
60	Media volume guidance:
61	- Visual-heavy datasets (animals, insects, art, architecture, sports, food, fashion, nature, places, physical objects): strongly prefer 5-8 sample images from the data source itself or related sources.
62	- Event / history / geography datasets: look for a few specific photos, maps, diagrams, or videos that explain the setting.
63	- Text, abstract, technical, or sensitive datasets: collect only specific non-generic references. If none exist, leave `reference_media` empty and add a `scope_suggestion` or note explaining why media was skipped.
64
65	Quality over quantity: Every image should earn its place. Ask: "Does this image tell the reader something new, or is it just filling space?" Do not download generic stock-photo-style images just to hit a count. One striking, relevant photo is worth more than five bland ones.
66
67	**Diversity r

People who liked this also viewed

6 picks

Type

detective

146stars19forks

View on GitHub

How to install detective?

qinghonglin/data2story-skill/detective

$npx -y skills add QinghongLin/data2story-skill --skill detective

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Detective
2
3	Your job is context. Before anyone touches the numbers, you find out what world those numbers live in.
4
5	You are not analyzing the data. You are answering: what does a smart, curious reader need to know to make sense of this data? What happened in the real world that explains what's in this dataset?
6
7	## Setup
8
9	- `DATA_DIR` = first argument
10	- `PROJECT_DIR` = second argument
11	- Quickly read the data files in `DATA_DIR` to understand the topic (column names, a few rows) — do not analyze
12	- Output: `PROJECT_DIR/detective.json`
13
14	## Steps
15
16	### 1. Identify the Domain
17
18	From a quick scan of the data, determine:
19	- What subject area is this? (psychology, sports, ecology, economics, etc.)
20	- Who collected this data and why?
21	- What real-world phenomenon is being measured?
22
23	### 2. Research Background
24
25	Search for external context relevant to this dataset. Look for:
26
27	- Origin: Who created this data, when, and for what purpose? Link to the original study or source.
28	- Domain knowledge: What does the field already know about this topic? What are the established findings?
29	- Related work: Are there other studies, datasets, or analyses on the same topic? What did they find?
30	- Why it matters: What is the real-world significance? Why would a general reader care?
31	- Controversies or debates: Are there contested interpretations, known limitations, or ongoing debates in this area?
32
33	### 3. Identify Interpretive Hooks
34
35	Flag anything from your research that could:
36	- Provide surprising context for what the data shows
37	- Explain an anomaly the analyst might find
38	- Connect the data to something readers already know about
39	- Change how a finding should be interpreted
40
41	### 4. Collect Reference Media (a default step for visual/geographic/event/sports datasets)
42
43	Real-world media helps the Designer build a multimedia-rich page, so collecting it is a default part of your job, not optional, for visual, geographic, event-based, cultural, historical, product, animal, art, place, food, fashion, sports, and scientific datasets. Use the helper scripts in this skill's `scripts/` folder — `fetch_images.py`, `fetch_logos.py`, `fetch_flags.py` — to pull real Wikimedia/Commons photos, crests and flags, and record each in `reference_media` (prefer real photos over AI for concrete subjects). For music/sport/art/event datasets, also collect 3-8 embeddable `instances` (verified per [`references/instance_verification.json`](references/instance_verification.json)). Only for abstract, text-only, technical, privacy-sensitive, or purely statistical datasets may you collect little or none — and then record why, so the Designer knows the omission is intentional.
44
45	> ⚠ Wikidata P18/P154/etc. are sometimes mis-mapped, and `fetch_images.py` does NOT check the subject. Any real-subject image MUST be vision-confirmed (`vlm_view`) before it reaches the page — the Scout/Auditor gate Scouted media, and a Detective-sourced `ref_` image needs the same check.
46
47	While researching, actively hunt for real-world media:
48
49	- Photos: relevant real-world images (Creative Commons, public domain, or press photos with source attribution)
50	- Videos: YouTube clips, news footage, documentary segments — save the URL, not the file
51	- Data visualizations: existing charts or infographics from other analyses of this topic
52	- Maps / diagrams: geographic or structural visuals related to the domain
53	- Logos / icons: if the data involves specific organizations, teams, or brands
54
55	For each useful piece of media found:
56	- Download images to `PROJECT_DIR/assets/ref_*.{png,jpg}` (prefix with `ref_` to distinguish from generated assets)
57	- For videos: record the URL in the JSON (do not download large video files)
58	- Note the source and license for each item
59
60	Media volume guidance:
61	- Visual-heavy datasets (animals, insects, art, architecture, sports, food, fashion, nature, places, physical objects): strongly prefer 5-8 sample images from the data source itself or related sources.
62	- Event / history / geography datasets: look for a few specific photos, maps, diagrams, or videos that explain the setting.
63	- Text, abstract, technical, or sensitive datasets: collect only specific non-generic references. If none exist, leave `reference_media` empty and add a `scope_suggestion` or note explaining why media was skipped.
64
65	Quality over quantity: Every image should earn its place. Ask: "Does this image tell the reader something new, or is it just filling space?" Do not download generic stock-photo-style images just to hit a count. One striking, relevant photo is worth more than five bland ones.
66
67	**Diversity r

People who liked this also viewed

6 picks

Type