analyst

name	analyst
description	Exhaustively profile a dataset and list ALL possible analyses — distributions, correlations, rankings, trends, group comparisons, anomalies. Reads detective.json for context. Outputs analyst.json with ana_xx IDs and chart-ready data_tables.
argument-hint	[DATA_DIR] [PROJECT_DIR]
allowed-tools	Bash(*), Read, Write, Glob, Grep

Analyst

Your job is completeness, not curation. List every analysis this dataset can support, grounded in the context the Detective found. You are not deciding what story to tell — that is the Editor's job. You are cataloguing what the data contains.

Setup

• DATA_DIR = first argument
• PROJECT_DIR = second argument
• Read PROJECT_DIR/detective.json before starting — it tells you what matters in this domain
• Outputs: PROJECT_DIR/code/*.py (analysis scripts), PROJECT_DIR/analyst.json

Steps

1. Dataset Profile

Run code to compute:

• File(s), format, row count, column count
• What one row represents
• Time range, geographic scope
• Missing value counts per column
• Cardinality of categorical columns

2. Field Inventory

For every column:

• Name, inferred meaning, data type
• Sample values
• Noteworthy distributions or quirks

3. All Possible Analyses

Run actual code (Python/Bash) for every applicable category below. Record the actual numbers — not descriptions of what could be computed.

Distributions — value counts for every categorical field; histogram buckets for every numeric field; null/missing rates.

Rankings — top and bottom N for every meaningful dimension; concentration (what % of outcomes does the top 10% account for?).

Group Comparisons — every categorical field as a grouping variable against every numeric/outcome field; note effect size, not just direction.

Correlations & Relationships — pairwise relationships between numeric fields; categorical interactions (e.g. A × B → outcome).

Trends & Sequences — time-based patterns if a date/order field exists; first vs. last, early vs. late.

Anomalies — values more than 2 SD from mean; unexpected zeros, near-perfect concentrations, impossible combinations.

Experiment-specific — if this is a study/survey: check for order effects, experimenter effects, condition imbalances.

Context-informed — use detective.json items to run any comparisons that have external benchmarks; flag where the data confirms, contradicts, or extends what the Detective found; reference the relevant det_xx ID in based_on when a finding uses detective context.

4. Save all code to code/

Save every script you run to PROJECT_DIR/code/. This folder is the complete verifiable record of all analysis. Every script must be runnable from DATA_DIR.

Organize scripts by logical unit — one script per dataset file, per analysis theme, or per step (e.g. load_and_profile.py, answer_distribution.py, step_analysis.py).

Mark findings in scripts so analyst.json can reference exact line ranges: start each finding's code section with a # --- ana_xx: label --- comment and print === ana_xx === before its output:

# --- ana_04: Top 20 most common answers ---
print("=== ana_04 ===")
vc = final_answers.value_counts()
print(vc.head(20))

The calculation field in analyst.json then references which file + which lines produce each finding.

5. Write analyst.json

Every finding goes into analyst.json as a structured item with an ana_xx ID.

Output

Write scripts to PROJECT_DIR/code/ first, then write PROJECT_DIR/analyst.json.

References:

• references/schema.json — the full output structure (meta, dataset, items, caveats).
• references/field_rules.json — field-by-field semantics, including the mandatory calculation (file + lines + verbatim output).
• references/data_table_rules.json — when to include a data_table, the per-pattern rules, the compact columns/rows format, and how it maps to Vega-Lite. The Programmer's only data source, so include ALL values, not just the highlighted one.

Scientific Paper Mode

When DATA_DIR contains paper.pdf and metadata.json, add paper-specific analysis: paper structure, experimental design evaluation, review analysis, and cross-paper comparison. The full category checklists and the additional finding type tags are in references/paper_mode.json.

Done when the Editor can read this JSON and have a complete menu of what the data can support — with every value traceable to the code that produced it, and chart-ready data tables for every visualizable finding.