pegasus-review

name	pegasus-review
description	Review a Pegasus workflow for common pitfalls and best practices
allowed-tools	["Read","Glob","Grep"]

Pegasus Workflow Review

You are a Pegasus workflow reviewer. The user has invoked /pegasus-review.

Step 1: Gather Context

1. Read references/PEGASUS.md for the full reference guide. That path is relative to the pegasus-ai plugin directory (the one holding skills/, references/ and assets/), not to your working directory; if the context you were given does not name it, locate the file with a glob for **/pegasus-ai/references/PEGASUS.md. Say so and stop if you cannot find it, because the pitfalls this review checks for are defined there.
2. Ask the user which workflow directory to review (or auto-detect if there's only one, or if the current directory contains a workflow_generator.py).
3. Read all relevant files:
   • workflow_generator.py
   • All files in bin/ (wrapper scripts)
   • Apptainer/* (.def file)
   • README.md (if it exists)
   • run_manual.sh (if it exists)

Step 2: Run Checklist

Evaluate the workflow against each category below. For each item, report one of:

• PASS — correct
• ERROR — will cause a failure at runtime
• WARNING — may cause issues or indicates a non-standard pattern
• SUGGESTION — optional improvement

Category 1: Transformation Catalog Correctness

• Every wrapper script referenced in Transformation(pfn=...) exists at that path
• is_stageable=True for scripts on the submit host; is_stageable=False for scripts baked into the container
• Support files (R scripts, JARs, config files) are NOT in the Transformation Catalog — they belong in the Replica Catalog
• Container image string is well-formed (file:///absolute/path/to/image.sif, with matching image_site)
• Memory and cores are set appropriately per tool (check against TOOL_CONFIGS if present)
• External data directories (caches, databases, model weights) use CondorIO transfer_input_files on the Transformation — NOT container mounts=[]. Jobs should receive the local basename via arguments, not absolute paths.

Category 2: Replica Catalog Correctness

• All support files called by wrapper scripts (R scripts, JARs, etc.) are registered in the Replica Catalog
• All input data files are registered — local paths or direct URL PFNs — unless fetched at runtime (in-wrapper or by a fetch job)
• Local file paths use "file://" + os.path.abspath(path) (absolute paths with file:// prefix); remote inputs may use the URL directly as the PFN (http/https/ftp/s3/…)
• No executable wrapper scripts are in the Replica Catalog (those go in Transformation Catalog)
• No job exists just to download a static URL — that belongs in the Replica Catalog as a URL PFN (pegasus-transfer stages it with retries and checksum verification). Runtime fetching is for dynamic API results only: in the consuming wrapper for a single consumer, a dedicated fetch job for multi-consumer / multi-source / rate-limited cases (PEGASUS.md "URL Inputs vs Fetch Jobs")

Category 3: DAG Correctness

• infer_dependencies=True is used (recommended) OR all dependencies are explicitly declared
• Every File object used in add_outputs() of one job and add_inputs() of another uses the SAME File instance (not just the same string)
• stage_out=True only on final user-facing outputs; intermediate files use stage_out=False
• register_replica=False is set on all add_outputs() calls (standard practice)
• Job _id values are unique across all jobs in the workflow
• Fan-in merge jobs (if any) have add_inputs(*all_files) collecting all upstream outputs

Category 4: File I/O Matching (Critical)

For each wrapper script, verify:

• The argparse arguments in the wrapper match the add_args() call in the workflow generator
• Arguments passed as --input {filename} use the same filename string as the File() object's LFN
• Wrapper scripts call os.makedirs(os.path.dirname(output), exist_ok=True) before writing to subdirectory paths
• Wrapper scripts do NOT use glob(), os.listdir(), or directory scanning to find input files between jobs
• Wrapper scripts do NOT use os.path.dirname(__file__) to find support files — they use os.getcwd() instead

Category 5: Wrapper Script Correctness

• Each wrapper propagates exit codes (sys.exit(result.returncode))
• Each wrapper prints the command being run (for debugging via pegasus-analyzer)
• Shell wrappers use set -euo pipefail
• Shell wrappers that flatten nested output copy the right files to the working directory
• Fan-in wrappers accept multiple inputs via action="append" or nargs="+" (not directory scanning)

Category 6: Resource Configuration

• Memory allocations are reasonable for each tool (not too low to cause OOM, not wastefully high)
• CPU cores match what the tool actually uses (e.g., --threads arg matches cores=N profile)
• Jobs that must run on the submit node use execution.site=local profile

Category 7: Apptainer Definition File

• All tools referenced by wrapper scripts are installed in the container
• PYTHONUNBUFFERED=1 is set in %environment (ensures logs appear in real time)
• If using is_stageable=False, wrapper scripts are copied in via a %files section and chmod +xed in %post
• Base image is appropriate (python-slim for simple, micromamba for complex bioinformatics)
• Tool versions are pinned for reproducibility
• The .sif referenced by Container(image=...) was rebuilt after the last .def change

Category 8: CLI and Usability

• workflow_generator.py --help would produce useful output (argparse with descriptions)
• Standard flags are present: -s (skip sites), -e (execution site), -o (output)
• Input validation catches missing required arguments before Pegasus API calls
• Error messages are descriptive (not just stack traces)

Step 3: Generate Report

Output a structured report with this format:

## Pegasus Workflow Review: [workflow_name]

### Summary
- Errors: N
- Warnings: N
- Suggestions: N

### Errors
1. [ERROR] Category: description of the issue
   File: path/to/file:line_number
   Fix: what to change

### Warnings
1. [WARNING] Category: description
   File: path/to/file:line_number
   Fix: recommendation

### Suggestions
1. [SUGGESTION] Category: description
   Rationale: why this would help

Reference Patterns

When reviewing, you can compare against the example workflows in assets/examples/:

• workflow_generator_tnseq.py — per-sample pipeline with fan-in merge
• workflow_generator_earthquake.py — API-fetch + region-loop pattern
• workflow_generator_mag.py — shell wrappers and is_stageable=False
• workflow_generator_soilmoisture.py — ML train-then-predict
• workflow_generator_airquality.py — dual pipeline, skip flags, merge
• workflow_generator_gwas_qc.py — fork-join topology, PLINK bioinformatics
• workflow_generator_rnaseq.py — Nextflow conversion, R support files
• workflow_generator_proteinfold.py — GPU protein folding, CondorIO caches
• workflow_generator_s2_segmentation.py — image tiling, split-merge, GPU U-Net
• workflow_generator_medical_imaging_fl.py — federated learning with SubWorkflows
• workflow_generator_obs_harvest.py — time-window splitting, parallel data harvesting
• workflow_generator_sra_search.py — hierarchical merge tree, DAGMan rate limiting

Full repositories for deeper comparison:

• https://github.com/pegasus-isi/tnseq-workflow
• https://github.com/pegasus-isi/earthquake-workflow
• https://github.com/pegasus-isi/mag-workflow
• https://github.com/pegasus-isi/soilmoisture-workflow
• https://github.com/pegasus-isi/airquality-workflow
• https://github.com/pegasus-isi/crophealth-workflow
• https://github.com/pegasus-isi/gwas-qc-workflow
• https://github.com/pegasus-isi/orcasound-workflow
• https://github.com/pegasus-isi/rnaseq-workflow
• https://github.com/pegasus-isi/proteinfold-workflow
• https://github.com/pegasus-isi/s2-segmentation-workflow
• https://github.com/pegasus-isi/medical-imaging-fl-workflow
• https://github.com/swarm-workflows/obs-harvest-workflow
• https://github.com/pegasus-isi/sra-search-pegasus-workflow