magi-researchers

Research Report Skill

Description

Generates a structured markdown research report from all previous phase outputs. Actively integrates existing plots, generates missing visualizations, and cross-verifies claim-evidence integrity. Requires at least some prior phase results to exist.

Usage

/research-report [path/to/output/dir]

Arguments

• $ARGUMENTS — Optional path to the research output directory. If not provided, uses the most recent outputs/*/ directory.

Instructions

Shared rules: Read ${CLAUDE_PLUGIN_ROOT}/shared/rules.md before starting. §MCP, §Claude-Only, §Visualization, §LaTeX apply to this skill.

Inline fallback (if shared rules unavailable): Gemini models: gemini-3.1-pro-preview → gemini-2.5-pro → Claude. Codex: gpt-5.4. All math in LaTeX only (no Unicode). scienceplots ['science','nature'], 300dpi PNG+PDF, Nature widths (3.5/7.2in). Subagents use Read tool.

Claude-Only Mode

See §Claude-Only in shared rules.

MCP Tool Rules

See §MCP, §Visualization in shared rules. Additionally:

• When to search: citation verification, related work context, factual accuracy checks

Step 0: Gather Materials & Health Check

1. Find the active research output directory.
2. Inventory available materials by checking for:
3. brainstorm/synthesis.md (and other brainstorm files)
4. brainstorm/weights.json (scoring weights)
5. brainstorm/personas.md (assigned expert personas)
6. brainstorm/debate_round2_gemini.md (adversarial debate, if --depth high was used)
7. brainstorm/debate_round2_codex.md (adversarial debate, if --depth high was used)
8. plan/research_plan.md
9. plan/murder_board.md (plan stress-testing results)
10. plan/mitigations.md (murder board mitigations)
11. plan/phase_gate.md (plan phase gate report)
12. src/ contents
13. src/phase_gate.md (implementation phase gate report)
14. tests/ and test results
15. tests/phase_gate.md (test phase gate report)
16. plots/ visualizations
17. Read the plot manifest (plots/plot_manifest.json):
18. If the manifest exists, parse it as the primary source of plot information.
19. If the manifest does NOT exist but plots/ contains files, create the manifest by inventorying all .png/.pdf files in plots/ and generating metadata for each:
20. description, section_hint, caption, markdown_snippet (existing fields)
21. style: array of style sheets used (e.g., ["science", "nature"])
22. dpi: output resolution (e.g., 300)
23. source_script: path to the Python script that generated this plot
24. source_function: function name within the script (if applicable)
25. generation_date: ISO-8601 timestamp of plot generation
26. If neither exists, note that no visualizations are available yet (they may be generated in the mini-loop).
27. Plot health check: For each plot listed in the manifest, verify:
28. The PNG file exists and is non-empty (file size > 0)
29. If any plot file is missing or corrupt, note it for re-generation in Step 2.
30. Read the report template from ${CLAUDE_PLUGIN_ROOT}/templates/report_template.md.
31. Determine the domain and load the relevant domain template from ${CLAUDE_PLUGIN_ROOT}/templates/domains/ for tone/style guidance.

Step 0.5: Plot Style Validation & Regeneration

Before assembling content, validate that all existing plots comply with the required style:

1. Scan existing plots: For each plot in plots/ (or referenced in plot_manifest.json):
2. Locate the generating script (check source_script in manifest, or search src/ and plots/ for Python files that produce each plot filename)
3. Verify the script imports scienceplots and calls plt.style.use(['science', 'nature'])
4. Verify no manual plt.rcParams overrides that conflict with scienceplots (e.g., font family, linewidth, figure.facecolor)
5. Verify figsize uses Nature column widths (single: 3.5 in, double: 7.2 in)
6. Verify output is saved at 300 dpi with both PNG and PDF formats

1. Flag non-compliant plots: If any plot fails validation:

a. Write a regeneration script using the required style: ``python import matplotlib.pyplot as plt import scienceplots plt.style.use(['science', 'nature']) # ... (reuse data loading from original script) ` b. Ensure all text in the script is ASCII or LaTeX-escaped (no Unicode π, ², etc.) c. Execute with uv run python {script_path} d. Verify the regenerated plots exist and are non-empty e. Update plots/plot_manifest.json` with style metadata

1. If no plots exist yet: Skip to Step 1 (plots will be generated in Step 3 if needed).

Step 1: Content Assembly & Plot Mapping

Read all available materials:

• brainstorm/synthesis.md — for Research Background and Brainstorming Summary sections
• brainstorm/weights.json — for Brainstorming Summary (scoring weights used)
• brainstorm/personas.md — for Brainstorming Summary (expert personas assigned)
• brainstorm/debate_round2_*.md — for Brainstorming Summary (debate resolution, if available)
• plan/research_plan.md — for Methodology section
• plan/murder_board.md — for Methodology section (Plan Stress Testing subsection)
• plan/mitigations.md — for Methodology section (mitigation strategies)
• plan/phase_gate.md — for Appendix F (Quality Assurance)
• All files in src/ — for Implementation section
• src/phase_gate.md — for Appendix F
• Test results and tests/ — for Testing section
• tests/phase_gate.md — for Appendix F
• plots/plot_manifest.json — for Results & Visualization section

Plot-to-Section Mapping: Using the section_hint field from the manifest, assign each plot to a report section:

• results → Section 5 (Results & Visualization)
• methodology → Section 3 (Methodology)
• validation → Section 5 or Section 6 (Testing)
• comparison → Section 5 (Results & Visualization)
• testing → Section 6 (Testing)

Step 2: Report Draft with Integrated Plots (Iteration 1)

Using the template structure from ${CLAUDE_PLUGIN_ROOT}/templates/report_template.md, generate the report:

Section 1 — Research Background:

• Problem statement and motivation
• Relevant prior work and context
• Research questions or hypotheses

Section 2 — Brainstorming Summary:

• Key ideas generated during brainstorming
• Expert Personas: Summarize the Gemini and Codex personas assigned and their influence on ideation (from personas.md)
• Scoring Weights: Show the weights used for direction ranking (from weights.json)
• Notable points from cross-check reviews
• Debate Resolution (if debate_round2_*.md exists): Summarize key disagreements and their resolutions
• Final chosen direction and rationale (with weighted score breakdown)

Section 3 — Methodology:

• Approach description from the research plan
• Key algorithms or techniques used
• Assumptions and their justifications
• Plan Stress Testing (if murder_board.md exists): Summarize the murder board's critical findings and the mitigations applied (from mitigations.md). This demonstrates that the methodology was adversarially tested before implementation.
• Embed any methodology-tagged plots here with their captions

Section 4 — Implementation:

• Architecture overview
• Key components and their roles
• Notable implementation decisions

Section 5 — Results & Visualization:

• Key findings and observations
• For each results/comparison-tagged plot from the manifest:
• Write a contextualizing paragraph with concrete quantitative observations (read from captions and source data if available)
• Embed the plot using the manifest's markdown_snippet
• Follow with interpretation of what the plot shows
• Do NOT use passive references like "see figure below" — actively discuss what the data shows with specific numbers

Anti-pattern: Do NOT list figures in a table at the end of th