Synthesis Skill

After notebooks have been run, read the outputs, compare against literature, and draft the findings/interpretation sections of the project README.

Usage

/synthesize <project_id>

If no <project_id> argument is provided, detect from the current working directory (if inside projects/{id}/).

Workflow (Two-Pass Approach)

Pass 1: Read Data and Draft Findings

Step 1: Gather Project Context

Read these project files:

1. •projects/{project_id}/research_plan.md — the hypothesis, expected outcomes, analysis plan
2. •projects/{project_id}/README.md — current state of the project
3. •projects/{project_id}/references.md — existing literature references

If research_plan.md doesn't exist, read the README for research question and hypothesis context.

Step 2: Read Analysis Outputs

Scan the project for results:

1. •

   CSV files in projects/{project_id}/data/:

   • •Read each CSV and interpret: column names, row counts, distributions, key statistics
   • •Identify the main result variables (correlations, counts, p-values, effect sizes)
2. •

   Figures in projects/{project_id}/figures/:

   • •List available figures and their filenames (infer content from names)
3. •

   Notebook outputs in projects/{project_id}/notebooks/:

   • •If executed .ipynb files are present, read output cells for results
   • •Look for printed summaries, DataFrames, and statistical test outputs

Step 3: Draft Initial Findings

Based on the data, draft findings that address:

1. •Key results: What did the data show? (specific numbers, correlations, counts)
2. •Hypothesis outcome: Was H1 supported or H0 not rejected?
3. •Statistical significance: Report p-values, effect sizes, confidence intervals if available
4. •Unexpected patterns: Note any surprising results or anomalies

Step 4: Present Draft to User

Show the initial findings interpretation and ask:

• •"Does this interpretation look correct?"
• •"Are there results I missed or misinterpreted?"
• •"Any additional context to include?"

Wait for user feedback and revise if needed.

Pass 2: Literature Cross-Reference and Synthesis

Step 5: Search Literature for Context

Invoke /literature-review to search for papers that:

• •Tested similar hypotheses in related organisms
• •Used comparable methods or data
• •Reported results that align or conflict with the BERDL findings

Focus searches on:

• •The specific organisms/taxa analyzed in the project
• •The specific biological question (e.g., "pangenome openness environmental adaptation")
• •Key methods used (e.g., "partial correlation phylogenetic signal")

Step 6: Compare Findings Against Literature

For each key finding, assess:

Step 7: Produce Synthesis

Update projects/{project_id}/README.md with the following sections. Preserve existing sections (Research Question, Hypothesis, Approach, Data Sources, Authors) and fill in the findings sections:

## Key Findings

### {Finding 1 Title}
{Statistical result with specific numbers}

### {Finding 2 Title} (if applicable)
{Statistical result}

## Interpretation
{What the results mean biologically}

### Literature Context
- {Finding} aligns with Author et al. (Year) who found {similar result} in {organism}
- {Finding} contradicts Author et al. (Year) — possible explanation: {methodology difference}
- Novel contribution: {what BERDL data adds that wasn't known before}

### Limitations
- {Data coverage limitations}
- {Potential confounders}
- {Methodological caveats}

## Future Directions
1. {Suggested next step based on findings}
2. {Follow-up analysis addressing limitations}
3. {New questions raised by the results}

Also update these tables if data is available:

## Visualizations
| Figure | Description |
|--------|-------------|
| `{filename}.png` | {what the figure shows} |

## Data Files
| File | Description |
|------|-------------|
| `{filename}.csv` | {what the data contains} |

Step 8: Update References

Add any new papers found during synthesis to projects/{project_id}/references.md.

If the file doesn't exist, create it following the format from /literature-review.

Step 9: Trigger Pitfall Capture (if needed)

If unexpected data patterns were found during interpretation (missing data, anomalous distributions, coverage gaps), follow the pitfall-capture protocol.

Step 10: Suggest Next Steps

After completing the synthesis, tell the user:

"Findings drafted in projects/{project_id}/README.md. Next steps:

1. •Review the Key Findings and Interpretation sections
2. •Use /submit to run pre-submission checks and get an automated review
3. •Address any review feedback and re-submit"

Integration

• •Reads from: data/*.csv, figures/, notebooks/*.ipynb, research_plan.md, references.md
• •Calls: /literature-review (for literature comparison)
• •Produces: Updated README.md (Key Findings, Interpretation, Literature Context, Limitations, Future Directions)
• •Consumed by: /submit (reviewer assesses the findings)

Pitfall Detection

When you encounter errors, unexpected results, retry cycles, performance issues, or data surprises during this task, follow the pitfall-capture protocol. Read .claude/skills/pitfall-capture/SKILL.md and follow its instructions to determine whether the issue should be added to docs/pitfalls.md.