/research-report

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:

• `brainstorm/synthesis.md` (and other brainstorm files)
• `brainstorm/weights.json` (scoring weights)
• `brainstorm/personas.md` (assigned expert personas)
• `brainstorm/debate_round2_gemini.md` (adversarial debate, if `--depth high` was used)
• `brainstorm/debate_round2_codex.md` (adversarial debate, if `--depth high` was used)
• `plan/research_plan.md`
• `plan/murder_board.md` (plan stress-testing results)
• `plan/mitigations.md` (murder board mitigations)
• `plan/phase_gate.md` (plan phase gate report)
• `src/` contents
• `src/phase_gate.md` (implementation phase gate report)
• `tests/` and test results
• `tests/phase_gate.md` (test phase gate report)
• `plots/` visualizations

3. **Read the plot manifest** (`plots/plot_manifest.json`):

• If the manifest exists, parse it as the primary source of plot information.
• 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:
• `description`, `section_hint`, `caption`, `markdown_snippet` (existing fields)
• `style`: array of style sheets used (e.g., `["science", "nature"]`)
• `dpi`: output resolution (e.g., `300`)
• `source_script`: path to the Python script that generated this plot
• `source_function`: function name within the script (if applicable)
• `generation_date`: ISO-8601 timestamp of plot generation
• If neither exists, note that no visualizations are available yet (they may be generated in the mini-loop).

4. **Plot health check**: For each plot listed in the manifest, verify:

• The PNG file exists and is non-empty (file size > 0)
• If any plot file is missing or corrupt, note it for re-generation in Step 2.

5. Read the report template from `${CLAUDE_PLUGIN_ROOT}/templates/report_template.md`. 6. 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`):

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

2. **Flag non-compliant plots**: If any plot fails validation: a. Write a regeneration script using the required style:

      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

3. **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` → Sect