results-interpreter

What this skill does

# Results Interpreter

Analyzes data files and interprets figures to generate structured notes and draft the Results section with proper statistical reporting.

## Critical Principle: No Silent Assumptions

**NEVER make assumptions about data without user confirmation.**

When encountering ambiguity, STOP and ask the user before proceeding. It is better to ask too many questions than to misinterpret data. The user's research depends on accurate interpretation.

### When to Pause and Ask

**ALWAYS ask the user when you encounter:**

1. **Unclear column meanings**
   - Column names are abbreviated or cryptic (e.g., "grp1", "val_a", "x1")
   - Units are not specified (is this mm, cm, seconds, days?)
   - Multiple possible interpretations exist

2. **Ambiguous group definitions**
   - What does "Group A" vs "Group B" represent?
   - Which group is the control/reference?
   - Are these treatment arms, time points, or subpopulations?

3. **Uncertain statistical context**
   - P-values without knowing which test was used
   - Effect sizes without knowing the direction expected
   - Multiple comparison situations unclear

4. **Data-scope mismatch**
   - Data doesn't match what scope.md described
   - Fewer/more variables than expected
   - Sample sizes don't align with expectations

5. **Figure interpretation uncertainty**
   - Axes labels are unclear or missing
   - Color coding isn't explained
   - Statistical annotations are ambiguous (*, **, ***)

6. **Missing context**
   - Primary vs secondary outcomes unclear
   - Exclusion criteria not evident from data
   - Time points or visit structure unknown

### How to Ask Clarifying Questions

Format questions clearly with context:

```
I need clarification before interpreting the data:

**File**: results.csv
**Issue**: Column "grp" contains values 0 and 1, but I'm unsure what these represent.

**Question**: What do the group values mean?
- 0 = [?]
- 1 = [?]
- Which is the reference/control group?

**Why this matters**: This determines how I report the direction of effects (e.g., "Group A was higher than Group B" vs the reverse).
```

### Log All Assumptions

If the user confirms an interpretation, document it in `notes/data-analysis.md`:

```markdown
## Clarifications Received

| Question | User Response | Date |
|----------|---------------|------|
| What does grp=0 mean? | Control group (no treatment) | [date] |
| Units for "time" column? | Days since enrollment | [date] |
```

## Prerequisites

- `scope.md` must exist
- `notes/code-analysis.md` should exist (provides context on what analyses were run)
- `notes/ethics-summary.md` may exist (provides expected sample size, endpoints for validation)
- `notes/ethics-scope-comparison.md` may exist (explains any scope differences)
- `data/` folder with CSV/Excel files
- `figures/` folder with PNG/JPG images

## Workflow

```
[Read scope.md, code-analysis.md, and notes/ethics-summary.md]
     │
     ▼
[Inventory Data Files] ─── List all CSVs and columns
     │
     ▼
[CHECKPOINT: Ask Clarifying Questions] ─── STOP if any ambiguity
     │                                       └── Document responses
     ▼
[Validate Against Ethics Docs] ─── Check sample size, endpoints match expectations
     │
     ▼
[Analyze Data Files] ─── Parse CSVs, extract statistics
     │
     ▼
[Interpret Figures] ─── View and describe each figure
     │
     ▼
[CHECKPOINT: Verify Interpretations] ─── Confirm with user
     │
     ▼
[Cross-Reference] ─── Match data to figures to findings
     │
     ▼
[Generate notes/data-analysis.md]
     │
     ▼
[STATISTICAL REVIEW] ─── Validate statistical reporting
     │                     └── agents/statistical-reviewer.md
     ▼
[Draft Results] ─── drafts/results.md (with statistical sign-off)
```

## Step 1: Read Context

From `scope.md`:
- Key findings (what results are expected)
- Research question (what to emphasize)

From `notes/code-analysis.md`:
- Statistical tests used (how to interpret p-values)
- Variables analyzed (what columns to look for)

## Step 2: Analyze Data Files

### 2a. Inventory Data Files

```bash
ls -la data/*.csv data/*.xlsx 2>/dev/null
```

### 2b. Initial Data Scan

For each data file, perform an initial scan WITHOUT interpretation:

```python
import pandas as pd
df = pd.read_csv('data/results.csv')
print("Shape:", df.shape)
print("Columns:", df.columns.tolist())
print("Sample values per column:")
for col in df.columns:
    print(f"  {col}: {df[col].unique()[:5]}")
```

---

## Step 3: CHECKPOINT — Clarifying Questions

**STOP HERE if there is ANY ambiguity.**

Before interpreting any data, present findings to the user and ask clarifying questions.

### Required Clarification Template

Present this to the user:

```markdown
## Data Clarification Needed

I've scanned your data files. Before interpreting, I need to confirm my understanding.

### Files Found

| File | Rows | Columns |
|------|------|---------|
| results.csv | 156 | 12 |
| demographics.csv | 156 | 8 |

### Questions About: results.csv

**Columns I understand:**
- `patient_id` — unique identifier
- `age` — patient age (years, I assume?)

**Columns I need clarification on:**

1. **Column: `grp`** (values: 0, 1)
   - What do these values represent?
   - Which is the control/reference group?

2. **Column: `outcome_val`**
   - What does this measure?
   - What are the units?
   - Is higher better or worse?

3. **Column: `p_val`**
   - Which statistical test produced these p-values?
   - Were these corrected for multiple comparisons?

### Questions About: Figures

1. **figure1.png** — appears to be a box plot
   - What groups are being compared?
   - What's on the y-axis?

### Questions About: Overall Analysis

1. Which finding is the PRIMARY outcome for this paper?
2. Are there any data points I should exclude (e.g., outliers, failed QC)?
3. Is there anything unusual about this dataset I should know?

**Please answer these questions before I proceed with interpretation.**
```

### Wait for User Response

Do NOT proceed until the user has answered ALL clarifying questions.

If the user says "just figure it out" or similar, respond:

> "I want to make sure I interpret your data correctly. Making assumptions could lead to errors in the manuscript that might be difficult to catch later. Could you please clarify [specific question]?"

### Document All Clarifications

After receiving answers, record them:

```markdown
## Clarifications Log

**File**: results.csv
**Date**: [timestamp]

| Item | Question | User Response |
|------|----------|---------------|
| grp column | What do 0 and 1 mean? | 0 = control, 1 = treatment |
| grp column | Which is reference? | 0 (control) is reference |
| outcome_val | What does it measure? | Tumor volume in mm³ |
| outcome_val | Higher = better/worse? | Lower is better (tumor shrinkage) |
| p_val | Which test? | Mann-Whitney U, not corrected |
| figure1.png | What's compared? | Treatment vs control tumor volume |
| Primary outcome | Which is primary? | Tumor volume change at week 8 |
```

---

## Step 3b: Validate Against Ethics Docs (If Ethics Docs Exist)

**Skip this step if `notes/ethics-summary.md` does not exist.**

After clarifying data questions, validate that the actual results align with ethics document expectations.

### Ethics Validation Checklist

```markdown
## Ethics Document Results Validation

**Ethics Document**: [from ethics-summary.md]
**Scope Comparison**: [from ethics-scope-comparison.md]

### Sample Size Check

| Aspect | Expected | Actual Data | Status |
|--------|----------|-------------|--------|
| Total N | [from ethics doc] | [from data] | ✓/✗ |
| Control group | [from ethics doc] | [from data] | ✓/✗ |
| Treatment group | [from ethics doc] | [from data] | ✓/✗ |

**If actual < expected**: Reference ethics-scope-comparison.md for explanation
**If actual > expected**: Unusual - ask user for clarification

### Endpoints Check

| Approved Endpoint | Present in Data? | Column Name | Notes |
|-------------------|---