tooluniverse-fastq-qc

# FASTQ Quality Control & Trimming Decisions

Run quality control on raw sequencing reads, interpret the report, and make
an evidence-based decision about whether to trim — using real local
command-line tools (FastQC, MultiQC, fastp, Cutadapt, seqkit).

## Honesty contract (read first)

This skill drives **real binaries**. It must never fabricate QC numbers.

1. **Preflight before anything.** Check whether the required tools are on
   PATH. If a required tool is missing, emit the install plan and STOP.
   Do not estimate, guess, or describe hypothetical QC results.
2. **Never auto-trim.** Trimming is a *decision*. QC-only is the default.
   Only trim after inspecting adapter content / per-base quality, and only
   when the user has confirmed `--mode trim`.
3. **Never overwrite raw FASTQs.** All outputs go to a separate `--workdir`.
   The input directory is read-only. Trimmed reads are written as NEW files.
4. **If you cannot run, say so.** "FastQC is not installed; here is the
   install plan" is the correct answer — not a made-up PASS/FAIL table.

## When to use vs. not

**Use this skill when the user wants to:**
- Run FastQC / fastp QC on one or more FASTQ (`.fastq`, `.fq`, `.gz`) files
- Interpret a FastQC report (per-base quality, adapter content, etc.)
- Decide whether adapter or quality trimming is needed before downstream work
- Summarize many samples into one MultiQC report
- Count reads, get length/GC stats, or subsample with seqkit
- Trim adapters/low-quality bases with fastp or Cutadapt (explicitly)

**Do NOT use this skill for (route elsewhere):**
- Differential expression / DEG / fold-change analysis -> `tooluniverse-rnaseq-deseq2`
- Read alignment, coverage depth, samtools, BWA -> `tooluniverse-sequence-analysis`
- Variant calling, VCF, VAF, mutation analysis -> `tooluniverse-variant-analysis`
- Single-cell / scRNA QC (per-cell metrics, scanpy) -> `tooluniverse-single-cell`

## Essential inputs to confirm

Before running, confirm with the user (ask if unstated):

1. **FASTQ paths** — exact path(s). One file = single-end; an R1+R2 pair =
   paired-end (e.g. `*_R1.fastq.gz` / `*_R2.fastq.gz`).
2. **QC-only or trim?** Default is QC-only. Only trim on explicit request.
3. **Known adapters / primers?** Standard Illumina adapters are auto-detected
   by fastp; amplicon/primer sequences usually need explicit Cutadapt removal.
4. **Organism** — only needed if a contamination / over-representation screen
   is requested (needs a reference; see Limitations).
5. **Output directory** — a `--workdir` SEPARATE from the input folder.
6. **Read provenance** — are these raw, already-trimmed, or UMI-tagged reads?
   Already-trimmed reads should NOT be trimmed again; UMIs must be handled
   before trimming or you corrupt the UMI.

## Preflight (do this first, every time)

The bundled script preflights for you, but the decision logic is:

```python
import shutil
for tool in ("fastqc", "fastp", "seqkit"):
    print(tool, shutil.which(tool) or "MISSING")
```

`command -v fastqc` / `shutil.which("fastqc")` returning nothing means the
tool is absent. If a **required** tool (FastQC for QC; FastQC+fastp for trim)
is missing, emit:

```
mamba install -c bioconda -c conda-forge fastqc fastp seqkit multiqc
#   or
conda install -c bioconda -c conda-forge fastqc fastp seqkit multiqc
```

and stop. Do not proceed to fabricate output.

## Tool roles

| Tool      | Role                                                            | Install (bioconda) |
|-----------|----------------------------------------------------------------|--------------------|
| FastQC    | Per-file raw read QC; produces the module PASS/WARN/FAIL report | `fastqc`           |
| MultiQC   | Aggregates many FastQC (and fastp) reports into one summary     | `multiqc`          |
| fastp     | All-in-one QC + adapter + quality trimming (fast, auto-detect)  | `fastp`            |
| Cutadapt  | Explicit, precise adapter/primer removal (amplicons, custom)    | `cutadapt`         |
| seqkit    | Read counts, length/GC stats, subsampling                      | `seqkit`           |

Rule of thumb: **FastQC to diagnose, fastp to fix general adapter/quality,
Cutadapt to fix a known primer/adapter precisely, seqkit to count/stat.**

## Bundled orchestration script

`scripts/run_fastq_qc.py` does the preflight + run-if-available + plan-if-missing
flow, with workspace isolation built in.

```bash
# QC only (default) — never modifies reads
python scripts/run_fastq_qc.py \
    --fastq reads/sample_R1.fastq.gz reads/sample_R2.fastq.gz \
    --workdir /tmp/fastq_qc_run

# QC + trim (explicit) — fastp writes NEW trimmed files into --workdir
python scripts/run_fastq_qc.py \
    --fastq reads/sample_R1.fastq.gz reads/sample_R2.fastq.gz \
    --workdir /tmp/fastq_qc_run \
    --mode trim
```

Behavior:
- **Preflights** FastQC (+ fastp in trim mode) and seqkit. If a required
  tool is missing it prints the install plan and exits 0 — no fabricated QC.
- Runs **FastQC** (always) + **seqkit stats** (if present) into `--workdir`.
- In `--mode trim`, runs **fastp** writing `*.trimmed.fastq.gz` into
  `--workdir/trimmed/` — raw inputs are never touched.
- **Refuses** to run if `--workdir` equals an input directory (overwrite guard).

For a project-level summary after FastQC, run MultiQC over the workdir:

```bash
multiqc /tmp/fastq_qc_run -o /tmp/fastq_qc_run/multiqc
```

## INTERPRETATION — FastQC module -> meaning -> action

This table is the core value-add. Map each FastQC module to what PASS/WARN/FAIL
means and what to actually do. (See `references/fastqc_interpretation.md` for the
long form with thresholds and worked cases.)

| FastQC module                | Typical PASS              | WARN / FAIL means                                              | Suggested action |
|------------------------------|---------------------------|----------------------------------------------------------------|------------------|
| Per base sequence quality    | All positions Q>