# GEO Biomarker HTML Report Workflow

## 1. Inputs to inspect first

Check these before touching code:

- user-level and project-level `CLAUDE.md` / `claude.md`;
- the current project tree;
- any local source report such as `.webarchive`, `.html`, `.pdf`, `.md`;
- current templates, tests, output folders, and run scripts.

If the user gave a local PDF, prefer `pdf2md "<pdf_path>"` before asking them to convert anything manually.

## 2. Default assumptions

Use these unless the user overrides them:

- presentation: light academic / Nature-supplement / research-first;
- execution: real pipeline, not mock data;
- reproducibility: explicit branch declaration for processed-expression vs raw-count inputs;
- external context (for example ClinicalTrials.gov) is supplemental and non-blocking.

## 3. Required framing before analysis

Always state which of these buckets each section belongs to:

- directly derived from the dataset;
- derived from standard transformations of the dataset;
- external enrichment.

Never pretend processed FPKM/TPM matrices are raw counts. If the source is processed expression, use a documented processed-expression comparison branch.

## 4. Minimal project shape

Prefer this layout:

- `config/<dataset>.yaml`
- `pipeline/`
- `templates/<style>/report.html.j2`
- `tests/`
- `run_demo.py` or equivalent top-level command
- `outputs/<dataset>_<timestamp>/`

Typical final artifacts:

- `report.html`
- `report_zh.html` when Chinese同步版 is requested or configured as default
- `report.md`
- `report_zh.md` when bilingual delivery is enabled
- `report_context.json`
- `report_context_zh.json` when bilingual delivery is enabled
- `manifest.json`
- `run.log`
- `analysis_code/` containing the runnable analysis snapshot
- `figures/*.png`
- `figures/pdf/*.pdf`
- `tables/*.tsv`
- `data/*`
- figure files
- tables / intermediate outputs

## 5. Execution pattern

1. Inspect existing code and prior outputs.
2. Save a concise design doc if the work meaningfully changes scope or presentation.
3. Save an implementation plan for multi-step work.
4. Add or update tests first.
5. Implement the smallest change that makes the tests pass.
6. Run full verification.
7. Generate the real report.
8. Export the delivery bundle additions inside the same run directory: code snapshot + PDF figures.
9. Surface final file paths and caveats.

When bilingual delivery is needed, the analysis should still run only once. Reuse the same figures, tables, and manifest-backed statistics, then render two reading layers:

- English: `report.html`
- Chinese: `report_zh.html`

## 6. Command pattern

Typical full verification:

```bash
cd <project>
pytest -q
python run_demo.py --dataset <gse_id> --style nature-soft-accent
```

If the project maintains convenience links, also verify:

```bash
ls -l outputs/latest outputs/latest_report.html
```

If bilingual output is expected, also verify:

```bash
ls -l <output_dir>/report.html <output_dir>/report_zh.html
```

For a complete delivery bundle, also verify:

```bash
ls -l <output_dir>/analysis_code
ls -l <output_dir>/figures/pdf
```

## 7. HTML polish checklist

For long supplement-style reports:

- sidebar labels wrap without overflowing into the main text;
- active section is visibly highlighted;
- keyboard focus is clearly visible on nav links;
- section anchors have `scroll-margin-top`;
- generated timestamp lives in a muted meta/footer block, not the main reading flow.
- Chinese HTML should translate section titles, explanatory copy, and metadata labels without re-running the analysis.

## 8. Delivery bundle contract

The standard deliverable is the whole run directory. At minimum it should expose:

- readable outputs: `report.html`, optionally `report_zh.html`;
- provenance outputs: `manifest.json`, `run.log`, report contexts;
- scientific outputs: tables, data, PNG figures, PDF figures;
- reproducibility outputs: `analysis_code/` with `run_demo.py`, `config/`, `pipeline/`, `templates/`, and usually `tests/`.

The user should not need to search the project root for code or figures after the run finishes.

## 9. Common pitfalls from the GSE78220 demo

- GSE78220 GEO supplementary expression is processed FPKM, so do **not** run DESeq2 on it.
- Keep strict cohort logic explicit when filtering on-treatment or duplicate biopsies.
- If FDR is globally weak, volcano plots still need a clear candidate-color layer for interpretability.
- Trial/evidence enrichment should never block report generation.
- Final report claims must match fresh verification output, not assumptions.
- If `report_zh.html` exists, ensure it is synchronized to the same run directory and not copied from an older output.
- Do not leave analysis code only in the project root; the delivery bundle must contain its own runnable snapshot.
- Do not export PDF figures into some separate ad hoc folder; keep them under the same run directory, typically `figures/pdf/`.

## 10. Packaging the workflow as a skill

When the user asks to turn the workflow itself into a skill:

1. create the real skill directory under `~/.claude/skills/<skill-name>/`;
2. keep the SKILL description trigger-focused, not process-heavy;
3. move detailed checklists into `references/` if they are long;
4. create a symlink at `~/.codex/skills/<skill-name>`;
5. if `~/.claude` is a git repo and no secrets are present, commit only the relevant new skill files and push.
