/data-analysis

name: data-analysis
description: "Decision-first data analysis with statistical rigor gates."
user-invocable: false
allowed-tools:
  - Read
  - Write
  - Bash
  - Grep
  - Glob
  - Edit
  - Task
context: fork
routing:
  triggers:
    - analyze data
    - data analysis
    - CSV
    - dataset
    - metrics
    - trend
    - cohort
    - A/B test
    - statistical
    - distribution
    - correlation
    - KPI
    - funnel
    - experiment results
    - "data insights"
    - "statistical analysis"
    - "CSV analysis"
    - "explore dataset"
  not_for: "building REST/GraphQL API endpoints (use nodejs-api-engineer agent) — this skill analyzes data, builds KPI dashboards, and runs statistical queries"
  pairs_with:
    - workflow
    - codebase-overview
  complexity: medium
  category: analysis

Data Analysis Skill

Every analysis begins with the decision being supported, works backward to the evidence required, and only then touches the data. This prevents the common failure mode where analysis produces impressive summaries that answer the wrong question. **Analysis without a decision is just arithmetic.**

---

Reference Loading Table

| Signal | Load These Files | Why | |---|---|---| | extended pattern catalog: methodology, statistical, communication, process fixes | `preferred-patterns.md` | Loads detailed guidance from `preferred-patterns.md`. | | writing analysis scripts: tool detection and metric computation code | `compute-examples.md` | Loads detailed guidance from `compute-examples.md`. | | errors, error handling | `error-handling.md` | Loads detailed guidance from `error-handling.md`. | | writing analysis-report.md per analysis type (A/B, trend, distribution) | `output-templates.md` | Loads detailed guidance from `output-templates.md`. | | applying Phase 4 statistical gates: adequacy, fairness, correction, significance | `rigor-gates.md` | Loads detailed guidance from `rigor-gates.md`. | | end-to-end phase walkthroughs on realistic inputs | `worked-examples.md` | Loads detailed guidance from `worked-examples.md`. |

Instructions

Phase 1: FRAME (Frame the decision before touching data)

**Goal**: Establish what decision this analysis supports and what evidence would change it.

Starting with data before establishing the decision context is the single most common analytical failure. The analyst finds interesting patterns and presents them, but the decision-maker cannot act because the patterns do not map to their options. Complete framing even when the user says they "just want numbers" -- numbers without decision context are not actionable.

**Step 1: Identify the decision**

• What specific decision does this analysis support?
• Who is the decision-maker?
• What are their options? (Option A vs. Option B vs. do nothing)
• What is the current default action if no analysis is performed?

If the user does not articulate a decision, ask: "What will you do differently based on this analysis?" If the answer is "nothing" or "I just want to see the data," switch to Exploratory Mode and label all output as exploratory. Exploratory Mode still applies rigor gates but makes no causal claims.

**Step 2: Define evidence requirements**

• What evidence would favor Option A over Option B?
• What is the minimum evidence threshold for changing the default action?
• Are there deal-breakers? (e.g., "If churn exceeds 5%, we switch vendors regardless of cost")

**Step 3: Save the frame artifact**

Save `analysis-frame.md` using the template from `references/output-templates.md` (Phase Artifact Templates § analysis-frame.md).

**GATE**: Decision identified, options enumerated, evidence requirements written to file. If the user cannot articulate a decision, explicitly switch to Exploratory Mode and document this in the frame. Proceed only when gate passes.

---

Phase 2: DEFINE (Lock metrics before loading data)

**Goal**: Define exactly what will be measured, how, and over what population. Write definitions to file before any data is loaded.

Defining metrics after seeing data enables (consciously or not) choosing definitions that produce favorable results. Locking definitions first makes the analysis auditable. Verify every metric definition is exact -- a slight change in numerator or denominator can flip a conclusion.

**Step 1: Define metrics**

For each metric:

• **Name**: Clear, unambiguous label
• **Formula**: Exact computation (numerator/denominator for rates, aggregation method for summaries)
• **Population**: Who/what is included and excluded
• **Time window**: Start date, end date, granularity (daily/weekly/monthly)
• **Segments**: How data will be sliced (by region, cohort, plan tier, etc.)

**Step 2: Define comparison groups** (if applicable)

For each comparison:

• **Group A**: Definition and selection criteria
• **Group B**: Definition and selection criteria
• **Fairness check**: Are groups drawn from the same population and time window?

**Step 3: Define success criteria**

• What threshold constitutes a meaningful result?
• What is the minimum sample size per segment?
• Is this a one-tailed or two-tailed question?

**Step 4: Save definitions artifact**

Save `metric-definitions.md` using the template from `references/output-templates.md` (Phase Artifact Templates § metric-definitions.md).

**GATE**: All metrics defined with formulas and populations. Definitions saved to file. If this is a comparison analysis, fairness checks documented. Proceed only when gate passes.

**Immutability rule**: Once Phase 3 begins, these definitions are locked. If the data reveals that a definition is unworkable, return to Phase 2, update the definition, and document the change and its reason in the artifact. Document every adjustment -- silent definition changes are p-hacking by another name.

---

Phase 3: EXTRACT (Load data. Assess quality. No interpretation.)

**Goal**: Load the data, profile its quality, and determine whether it is adequate for the planned analysis. Keep interpr