---
name: gwas-run-html
description: >-
  Write or update an agent-authored HTML run summary (workflow, methods, results
  preview, embedded figures) after GWASLab execution. Use at the end of any run that
  produced outputs, or when the user asks for an HTML summary. Do not use GWASLab
  gwaslab report or mysumstats.report(). Do not use for preview-only inspection or
  router planning without execution.
gwaslab-id: gwas.run_html
type: atomic
domain: gwas
---

# Run HTML summary

## Purpose

Produce a **self-contained HTML file** documenting what ran, how, key numeric previews, and saved figures — without GWASLab's built-in report commands.

## When to Use

Use this skill when:

- A GWASLab stage (or multi-step sequence) finished and wrote outputs.
- The user asks for an HTML summary, run log, or shareable QC narrative.
- You are closing a session and need a durable artifact beside chat output.

Do not use this skill when:

- Only `preview-sumstats` ran and the user did not ask for HTML.
- The router planned steps but nothing executed yet.
- The user explicitly wants GWASLab's separate QC report subcommand — tell them that path is outside this skill pack default (agents still must not call `mysumstats.report()` unless they opt in outside skills).

## Inputs

Required:

- Run output directory (or infer from saved artifacts).
- List of skills executed and commands/API calls with kwargs.
- Paths to tables/plots written this run.

Optional:

- Existing `run_summary.html` to update (multi-step).
- `mysumstats` in memory for counts and small previews.

## Outputs

Produce:

- `{output_dir}/run_summary.html` per [run_html.md](../domain/run_html.md).
- Optional `{output_dir}/run_plots/` copies of figure files for stable relative links.

## Procedure

1. Load [run_html.md](../domain/run_html.md) and [output_and_export.md](../domain/output_and_export.md).
2. Choose `output_dir` (user path or common parent of artifacts).
3. If `run_summary.html` exists, read it and **merge** new workflow steps, methods, results, and figures — do not discard prior steps.
4. Fill all **required sections** from `run_html.md` with real values from this session (no placeholder lorem).
5. For **Results preview**, include variant counts and up to 25-row HTML tables from `mysumstats` or output TSVs.
6. For **Figures**, copy or link each plot into `run_plots/` and use relative `<img src="run_plots/...">`.
7. Apply [SAFETY_AND_LIMITS.md](../../SAFETY_AND_LIMITS.md) — new path, no silent overwrite of user HTML unless confirmed.
8. Tell the user the absolute path to `run_summary.html` in the chat report per [OUTPUT_STANDARDS.md](../../OUTPUT_STANDARDS.md).

## Validation

Check that:

- File exists and is valid HTML with Workflow, Methods, Results preview, and Figures sections.
- Methods match commands actually run (Python and/or CLI).
- Workflow lists every skill executed in order.
- Figure links work relative to the HTML file.
- No call to `mysumstats.report()` or `gwaslab report` was used to create this file.

## Handoff

- If HTML documents failures, hand off to `troubleshoot-gwaslab`.
- If the user needs more processing, hand off to the next pipeline skill from the router; re-run `run-html` after that stage completes.

## Failure Modes

- No output directory → ask user where to write `run_summary.html`.
- No figures produced → note under Figures; do not invoke GWASLab report.
- Huge tables → cap preview rows; link full TSV paths in Outputs section.