Results Interpreter

Uncertain statistical context

• P-values without knowing which test was used
• Effect sizes without knowing the direction expected
• Multiple comparison situations unclear

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:

## 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

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

2b. Initial Data Scan

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

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:

## 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:

## 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

## 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 |
|-------------------|------------------|-------------|-------|
| [primary endpoint] | ✓/✗ | [column] | |
| [secondary endpoint 1] | ✓/✗ | [column] | |
| [secondary endpoint 2] | ✓/✗ | [column] | |

**Missing endpoints**: Check ethics-scope-comparison.md - may be intentionally out of scope
**Extra endpoints**: Exploratory analyses - note as such in Results

If Significant Discrepancies

If you find discrepancies NOT explained by notes/ethics-scope-comparison.md:

I found a discrepancy between expected and actual data:

**Expected Sample Size**: N = 500
**Actual Data**: N = 312

This wasn't documented in the scope comparison.
Could you explain this difference? (e.g., enrollment ongoing, exclusions, data subset)

Document all validations in notes/data-analysis.md.

Step 4: Analyze Data Files (Post-Clarification)

Only proceed after Steps 3 and 3b are complete.

4a. Parse Each Data File

For each CSV:

import pandas as pd
df = pd.read_csv('data/results.csv')
print(df.shape)
print(df.columns.tolist())
print(df.describe())
print(df.head())

4b. Identify Result Types

Scan columns for statistical output patterns:

4c. Extract Key Statistics

For each data file, extract:

Demographics/Baseline (if present):

• Sample sizes per group
• Age, sex distributions
• Key baseline characteristics

Primary Outcomes:

• Main comparison statistics
• Effect sizes
• P-values and CIs

Secondary Outcomes:

• Supporting statistics
• Subgroup analyses

Step 5: Interpret Figures

5a. View Each Figure

ls figures/*.png figures/*.jpg figures/*.svg

For each figure, examine the image and identify:

5b. Figure Type Recognition

5c. Match Figures to Data

Cross-reference figures with data files:

• Which CSV produced which figure?
• Do the statistics match?
• Any discrepancies to flag?

Step 6: CHECKPOINT — Verify Interpretations

Before finalizing, present your interpretation to the user for verification.

Interpretation Summary for User Review

## Please Verify My Interpretation

Before I write the Results section, please confirm these interpretations are correct:

### Primary Finding

I interpret the primary finding as:
> "[Treatment group] showed [direction] [outcome] compared to [control]
> ([statistic] vs [statistic], p = [value])"

**Is this correct?** [Yes / No / Needs adjustment]

### Secondary Findings

1. [Secondary finding interpretation]
2. [Secondary finding interpretation]

**Are these correct?** [Yes / No / Needs adjustment]

### Figure Interpretations

| Figure | My Interpretation | Correct? |
|--------|-------------------|----------|
| Figure 1 | Shows [description] | [ ] |
| Figure 2 | Shows [description] | [ ] |

### Sample Sizes

- Total analyzed: [n]
- Group A: [n]
- Group B: [n]
- Excluded: [n]

**Do these match your expectations?** [Yes / No]

### Anything I Missed?

Is there anything important about these results that I haven't captured?

If User Identifies Errors

If the user corrects any interpretation:

1. Thank them for the correction
2. Update the clarifications log
3. Re-analyze the affected data
4. Present revised interpretation for confirmation

Step 7: Generate Data Analysis Notes

Create notes/data-analysis.md:

# Data Analysis Notes

**Analyzed**: [timestamp]

## Data Files Processed

| File | Rows | Columns | Contents |
|------|------|---------|----------|
| results.csv | 156 | 12 | Main statistical results |
| demographics.csv | 156 | 8 | Patient characteristics |

## Study Population

- **Total enrolled**: [n]
- **Excluded**: [n] ([reasons])
- **Final cohort**: [n]

### Demographics

| Characteristic | Overall (n=X) | Group A (n=X) | Group B (n=X) | p-value |
|----------------|---------------|---------------|---------------|---------|
| Age, mean ± SD | XX ± XX | XX ± XX | XX ± XX | X.XXX |
| Male, n (%) | XX (XX%) | XX (XX%) | XX (XX%) | X.XXX |

## Primary Outcome

**Finding**: [description]

| Metric | Group A | Group B | Difference | p-value |
|--------|---------|---------|------------|---------|
| [outcome] | XX ± XX | XX ± XX | XX (95% CI: XX–XX) | X.XXX |

**Interpretation**: [what this means]

## Secondary Outcomes

### [Outcome 2]
[Statistics and interpretation]

### [Outcome 3]
[Statistics and interpretation]

## Figures

### Figure 1: [Title]
- **File**: figures/figure1.png
- **Type**: [box plot, ROC curve, etc.]
- **Shows**: [description]
- **Key observation**: [main takeaway]

### Figure 2: [Title]
- **File**: figures/figure2.png
- **Type**: [type]
- **Shows**: [description]
- **Key observation**: [takeaway]

## Statistical Summary

| Analysis | Test | Statistic | p-value | Interpretation |
|----------|------|-----------|---------|----------------|
| Primary | t-test | t = X.XX | 0.XXX | Significant/NS |
| Secondary | Mann-Whitney | U = XXX | 0.XXX | Significant/NS |

## Consistency Check

- [x] Demographics match reported sample size
- [x] Statistics align with scope.md key findings
- [x] Figures match data file values
- [ ] [Any discrepancies noted]

---

## Clarifications Log

| Date | Item | Question | User Response |
|------|------|----------|---------------|
| [date] | grp column | What do 0 and 1 mean? | 0 = control, 1 = treatment |
| [date] | outcome_val | Units? | mm³ |
| [date] | Primary outcome | Which is primary? | Tumor volume at week 8 |

---

## Assumptions Made

**None** — All interpretations were confirmed with user before proceeding.

(If any assumptions were made with user's consent, document them here with justification)

Step 8: Statistical Review

Before drafting Results, invoke the statistical reviewer agent for statistical review.

Read agents/statistical-reviewer.md and execute Phase 3 (Results Section Review):

1. Verify statistical reporting — Check all statistics are formatted correctly
2. Validate p-values — Ensure proper formatting (p = 0.043, not p = .043)
3. Check effect sizes — Confirm effect sizes reported with CIs
4. Cross-check with Methods — Verify Results matches Methods description
5. Flag common errors — Identify interpretation issues

Statistical Reviewer Results Checkpoint

## Statistical Reporting Review

| Statistic | Format OK? | Value Plausible? | CI Included? |
|-----------|------------|------------------|--------------|
| Primary outcome | ✓/✗ | ✓/✗ | ✓/✗ |
| Secondary outcomes | ✓/✗ | ✓/✗ | ✓/✗ |
| P-values | ✓/✗ | N/A | N/A |

**Issues Found**:
- [ ] None
- [ ] [List any issues]

**Statistical Sign-Off**: [ ] Approved for Results drafting

Do NOT proceed to Results draft until statistical reviewer approves.

If issues identified:

1. Correct statistical formatting
2. Add missing effect sizes or CIs
3. Flag interpretation concerns for user

Step 9: Draft Results Section

Only proceed after user has verified interpretations in Step 6 AND statistical reviewer sign-off in Step 8.

Create drafts/results.md:

# Results

## Study Population

[First paragraph ALWAYS describes the cohort]

A total of [n] patients were included in the analysis. [Exclusions if any]. The final cohort consisted of [n] patients (mean age XX ± XX years, XX% male). Baseline characteristics are summarized in Table 1.

## Primary Outcome

[Main finding with full statistics]

[Outcome] was significantly [higher/lower] in [Group A] compared to [Group B] (XX ± XX vs XX ± XX, p = X.XXX; Figure 1). The mean difference was XX (95% CI: XX–XX).

## Secondary Outcomes

### [Outcome 2]

[Description with statistics]

### [Outcome 3]

[Description with statistics]

## Model Performance (if applicable)

The [model type] achieved an AUC of X.XX (95% CI: X.XX–X.XX) for [classification task] (Figure X). At the optimal threshold, sensitivity was XX% and specificity was XX%.

## Subgroup Analyses (if applicable)

[Subgroup findings]

---

## Figure Legends

**Figure 1.** [Title]. [Description of what is shown]. [Statistical annotation explanation if needed]. Abbreviations: [list].

**Figure 2.** [Title]. [Description].

## Tables

**Table 1.** Baseline characteristics of the study population.

| Characteristic | Overall (n=X) | Group A (n=X) | Group B (n=X) | p-value |
|----------------|---------------|---------------|---------------|---------|
| Age, years | | | | |
| Male sex, n (%) | | | | |

---

## Results Checklist

- [ ] Study population described first
- [ ] Primary outcome reported with full statistics
- [ ] All p-values formatted correctly (p = 0.XXX or p < 0.001)
- [ ] Confidence intervals included for key findings
- [ ] All figures referenced in text
- [ ] All tables referenced in text
- [ ] No interpretation (saved for Discussion)

Statistical Reporting Guidelines

P-values

• p = 0.043 (not p = .043)
• p < 0.001 (not p = 0.000)
• p = 0.12 (report exact, even if NS)

Confidence Intervals

• 95% CI: 1.23–4.56 (en-dash, not hyphen)
• Include for all key effect sizes

Descriptive Statistics

• Normal: mean ± SD
• Non-normal: median (IQR) or median (Q1–Q3)
• Categorical: n (%)

Decimal Places

• Percentages: 1 decimal (62.5%)
• P-values: 3 decimals or < 0.001
• Correlations: 2 decimals (r = 0.45)
• AUC: 2 decimals (0.87)

Output

Save to:

• notes/data-analysis.md - Detailed analysis (includes clarifications log)
• drafts/results.md - Results section draft (with statistical reviewer approval)

Return to parent skill with summary:

• Data files analyzed: [n]
• Figures interpreted: [n]
• Primary finding confirmed: [yes/no]
• Statistical reviewer status: [approved / revisions needed]
• Statistical issues: [list if any]
• Results word count: [n]