lumi-assistant

Use when the user needs authenticated Rucio data-management queries — DIDs, RSEs, replicas, metadata, replication rules — on collaboration-internal data, via EITHER the remote `rucio-*` MCP tools (rucio-atlas, rucio-cms, rucio-escape, rucio-fcc; per-user SSO, no local client needed) OR the Rucio v38+ CLI on lxplus, SWAN, or a CVMFS-staged client (`/cvmfs/sw.escape.eu/rucio/<version>/`). Read queries default to the MCP tools; `rucio download`/`upload` and rule writes require the CLI. CLI is ALWAYS noun-verb (`rucio rse list`, `rucio did show`, `rucio rule add`); NEVER the deprecated flat verbs (`list-rses`, `list-dids`, `add-rule`, `get-metadata`, `rule-info`) even though MCP tool names (`rucio_list_dids`) resemble them. Targets non-public datasets — for ATLAS Open Data DSIDs use `atlas-opendata` instead; for grid submission use PanDA, not Rucio directly. Disambiguator phrase: rucio v38 noun-verb.

Use when the user has an ATLAS DSID, `physics_short` name, or ATLAS Open Data release tag (`2024r-pp`, `2025r-evgen-13tev`) and needs file URLs, cross-sections, k-factors, filter efficiencies, sumOfWeights, or MC weight metadata. Backed by the `atlasopenmagic` MCP. Operates on ATLAS Open Data only — for collaboration-internal datasets use `rucio`; for non-ATLAS portal records identified by `recid` or DOI use `cern-opendata`; for configuring or running an event generator itself — Sherpa steering files → `sherpa-manual`, MadGraph `.mg5` scripts / cards → `madgraph` — use that skill; `atlas-opendata` only resolves metadata for already-produced samples, including Sherpa- (`Sh_…`) and MadGraph- (`MG_…` / `aMC…`) produced ones. Disambiguator phrase: atlasopenmagic DSID resolver.

Use when the user describes a goal at the CERN/HEP infrastructure level and wants to know WHICH services to stitch (e.g. "I want distributed analysis on Open Data and to train an ML model"). Returns a 2–4-service stack with steps and pointers to the matching execution skill (`rucio`, `reana-workflows`, `physlite-basics`, …). Bundles a service catalogue (`reference/catalog.yaml`), pre-cooked recipes (`reference/recipes.md`), and digests on GPU access, SWAN+HTCondor scale-out, and columnar frameworks. Does NOT cover physics methodology, single-tool command-level help, or running specific code (use the dedicated skill named by the recommendation). Disambiguator phrase: CERN service stack composer.

Use when the user wants a multi-reviewer critique of an analysis ARTIFACT — a notebook, an analysis-note PDF or text, or an analysis repo — judged for physics correctness, plot validity, and unmet commitments, ending in a single PASS / ITERATE / ESCALATE verdict. Defines the panel protocol: who reviews (the `reviewer-physics`, `reviewer-critical`, `reviewer-constructive` agents and the `plot-validator` skill), the A/B/C finding classes, panel composition per artifact type, the 3/5/10 iteration caps, the fresh-reviewer rule, and how the `arbiter` adjudicates. Does NOT gate a completion claim for a long-running compute step (that is `verification-before-completion`, the completion-evidence gate); does NOT extract numbers from one paper (that is `read-publication`); does NOT itself run the figure checks (that is `plot-validator`). Disambiguator phrase: A/B/C review-panel protocol.

Use to run the deterministic red-flag checks on an analysis FIGURE — a histogram PNG/PDF or its histogram/fit JSON — before a human or a reviewer agent opines on it. The shipped `scripts/plot_checks.py` checks the file exists and is non-empty, data/MC ratios sit inside a profile's band, no empty/negative bins, the fit has positive degrees of freedom (catches `chi2/ndf = 0/0`), goodness-of-fit is acceptable, and the MeV/GeV axis-unit trap; thresholds come from `reference/thresholds.md`, not the code. Then VIEW the rendered image (PDF → text via the AGENTS.md pdftotext/pypdf recipe). NOT the multi-reviewer protocol that decides PASS/ITERATE/ESCALATE (that is `analysis-review`); NOT the compute-step completion gate (that is `verification-before-completion`). Disambiguator phrase: programmatic plot red-flag checks.

Use when the user asks for a canonical Particle Data Group value — particle mass, lifetime, branching ratio, decay width, magnetic moment, mixing parameter, charge, spin, or any quoted "PDG average" constant. Backed by https://pdg.lbl.gov/ via WebFetch (HTML pdgLive pages and the PDG REST API where available). Always cites the PDG record URL and edition year. Does NOT cover ATLAS Monte Carlo metadata (use `atlas-opendata`), measured values from a specific paper (use `read-publication`), HEPData tabulated measurements (use `hepdata`), or conceptual physics explanations of why a particle has the value it does (use the `tutor` agent). Disambiguator phrase: PDG particle data group lookup.

Use when the user wants to submit, monitor, inspect, or kill HTCondor batch jobs at CERN — `condor_submit` against a `.sub` file, `condor_q` for status, `condor_history` for finished jobs, `condor_rm` to kill, `condor_status` for pool health — plus the `htcondor` / `htcondor2` Python bindings. Covers `+JobFlavour` wall-time picks, multi-CPU / GPU requests, automatic Kerberos / AFS / EOS credential handling on lxplus / aiadm submit hosts. Detect availability via `command -v condor_submit`. Does NOT cover REANA workflow runs (use `reana` for status / logs, `reana-workflows` for authoring), CERN batch documentation lookup (use `cern-docs` with `source=batch`), proof that a finished job actually produced the expected outputs (use `verification-before-completion`), or multi-service infra recommendations (use `infra-advisor`). Disambiguator phrase: HTCondor lxbatch CLI & Python submission.

Use when the user needs to read or write HepMC3 event records in Python — generator-level event graphs, vertices, particle production chains — with the `pyhepmc` package. Does NOT cover Les Houches Event files (use `pylhe`), detector-level ROOT ntuples (use `physlite-basics`), or 4-vector math on the particles (use `vector`). Disambiguator phrase: pyhepmc HepMC3 event records.

Use when the user needs to read or inspect Les Houches Event (LHE) files in Python — parsing generator-level events, event weights, particle records, run metadata — with the Scikit-HEP `pylhe` package. Does NOT cover HepMC3 event records (use `pyhepmc`), detector-level ROOT ntuples (use `physlite-basics`), or running a Monte Carlo generator. Disambiguator phrase: pylhe Les Houches Event reader.

Use when the user needs to run jet clustering in Python — anti-kt, kt, Cambridge/Aachen algorithms — from arrays of particle constituents (calorimeter towers, particle-flow objects, truth particles). Backed by the `fastjet` Python bindings. Does NOT cover reading pre-clustered jets from a file (use `physlite-basics` for PHYSLITE small-R jets), 4-vector arithmetic on existing jets (use `vector`), or jet energy calibration. Disambiguator phrase: fastjet Python jet clustering.

Use when the user needs to compute Lorentz-vector / 4-vector quantities in Python — invariant mass, transverse momentum, pseudorapidity, ΔR, rapidity, boosts — from arrays of particle kinematics. Backed by the Scikit-HEP `vector` library (works with NumPy and Awkward arrays). Does NOT cover reading the kinematics from a file (use `physlite-basics` for PHYSLITE branches), clustering jets from constituents (use `fastjet`), or open-ended analysis-code authoring (use the `analysis` agent). Disambiguator phrase: Scikit-HEP vector library 4-vector math.

Use BEFORE claiming any long-running CERN compute step finished — REANA workflow runs, HTCondor / lxbatch jobs, xrdcp / rucio download transfers, uproot iterate loops over many files, distributed Dask reductions, multi-stage REANA pipelines, ROOT macros that produce output files. Block the "done" claim until concrete evidence is shown: `reana-client status` output, condor `JobStatus`, exit code, output file size from `ls -la` / `xrdfs stat`, cutflow row counts, fit convergence. The body of the skill, vendored from obra/superpowers, gives the gate function and worked dialogues. Disambiguator phrase: completion-evidence gate.

Use when the user runs the FTS3 REST CLI (`fts-rest-whoami`, `fts-rest-server-status`, `fts-rest-transfer-submit`, `fts-rest-transfer-list`, `fts-rest-transfer-status`, `fts-rest-transfer-cancel`, `fts-rest-delete-submit`, `fts-rest-delegate`, `fts-rest-ban`) against an FTS3 endpoint such as `https://fts3-pilot.cern.ch:8446` and needs to submit, list, inspect, or cancel point-to-point transfer jobs between SRM / XRootD / HTTPS / S3 storage endpoints, or query the user's FTS identity / server status / delegated proxy. Assumes the FTS endpoint is reachable, a valid X509 proxy (`X509_USER_PROXY`) exists, and `fts-rest-whoami -s <endpoint>` succeeds. Does NOT cover Rucio-driven transfers (Rucio uses FTS3 internally — use `rucio` for rule-based replication), FTS3 docs / configuration / installation (use `cern-docs` with `source="fts"`), or grid job submission (use PanDA / DIRAC). Disambiguator phrase: fts-rest-transfer-submit hyphenated CLI.

Use when the user needs to OPEN an ATLAS DAOD_PHYSLITE file with `uproot` / `awkward`, list its branches, reconstruct calibrated objects (electrons, muons, photons, taus, small-R jets, large-R jets, MET, trigger decisions), or apply MC normalisation. Assumes a public HTTPS or XRootD URI such as `root://eospublic.cern.ch/...` from `atlas_get_urls` or `cod_list_files`. Does NOT cover the older flat 13 TeV reduced ntuples (use the matching tutorial via `atlas-notebooks`), CMS NanoAOD or MiniAOD, or sample discovery (use `atlas-opendata`). Disambiguator phrase: PHYSLITE branch reader.

Use when the user has an ALREADY-CREATED REANA workflow on a REANA cluster (https://reana.cern.ch or other deployment) and needs to inspect status, fetch logs, list workspaces, or download outputs with `reana-client`. Assumes `REANA_SERVER_URL` and `REANA_ACCESS_TOKEN` are set and `reana-client ping` succeeds. Does NOT cover authoring a new `reana.yaml` from scratch (use `reana-workflows`), generic Jupyter execution, or Rucio data movement. Disambiguator phrase: reana-client status triage.

Use when the user is AUTHORING a new `reana.yaml` from scratch — picking an engine (serial / cwl / yadage / snakemake), declaring inputs / workflow / outputs, parameterising steps, and walking the `validate → create → upload → start → download` cycle for the first time. Pairs with `reference/schema.md` for field-level details and `reference/engines.md` for engine templates. Does NOT cover triaging an already-running workflow on the cluster (use `reana`) or grid submission outside REANA. Disambiguator phrase: reana.yaml authoring cycle.

Use when the user has a CERN Open Data `recid`, DOI, or exact record title and needs portal-level metadata, file URIs, container images, or supplementary files across CMS, ATLAS, LHCb, ALICE, or OPERA. Backed by the `cernopendata` MCP at opendata.cern.ch (records, files, glossary). Does NOT cover ATLAS Monte Carlo metadata by DSID or `physics_short` (use `atlas-opendata`), collaboration-internal datasets (use `rucio`), or canonical CERN service / ATLAS-software documentation (use `cern-docs` for SWAN, HTCondor, Cloud, ML@CERN, Athena docs). Disambiguator phrase: opendata.cern.ch recid resolver.

Use when the user wants the numerical tables, ROOT files, or YAML data attached to a published HEP measurement, identified by HEPData submission ID (`ins1234567`, `123/v2`), INSPIRE record id, paper DOI, or paper title — typically because they want to re-fit, plot, or run systematics studies on the published measurement. Routes to https://www.hepdata.net/ via WebFetch and the HEPData REST API. Returns table URLs (YAML, ROOT, CSV) suitable for downstream `pyhf`, `pandas`, or `uproot`. Does NOT cover the paper's narrative or the headline measured value (use `read-publication`), PDG canonical constants (use `pdg-lookup`), or Open Data primary datasets (use `cern-opendata` or `atlas-opendata`). Disambiguator phrase: HEPData published-tables retrieval.

Use when the user gives you a PDF path, arXiv ID (`2401.12345` or `arXiv:2401.12345`), INSPIRE record id (`recid:1234567` or `inspire-hep:1234567`), DOI (`10.1103/...`), or HEP paper URL and wants extracted content — abstract, measured cross-section / branching ratio / mass, conditions, cuts, fit method. Routes to the right retrieval (`pdftotext` for local PDFs; INSPIRE + arXiv APIs via `WebFetch` for IDs and URLs). Always cites per AGENTS.md rule 5. Does NOT cover PDG canonical particle constants (use `pdg-lookup`), HEPData numerical tables for re-fitting (use `hepdata`), CERN service operator docs (use `cern-docs`), or Open Data dataset records (use `cern-opendata` or `atlas-opendata`). Disambiguator phrase: published-HEP-result extractor.

Use when the user names a specific ATLAS Open Data outreach notebook (e.g. `HZZAnalysis.ipynb`, `Find_the_Z`, `HyyAnalysis.ipynb`) or asks which runtime (Binder / Colab / SWAN / Docker image) to pick for one. Routes to the canonical path under `atlas-outreach-data-tools/notebooks-collection-opendata` and the matching docs section in `13TeV25Doc`. Does NOT cover Standard Model walkthroughs by physics process (use `sm-analyses`), DSID or cross-section lookups (use `atlas-opendata`), or fuzzy infrastructure goals (use `infra-advisor`). Disambiguator phrase: outreach notebook routing.

Use when the user names a Standard Model process and wants to "rediscover" it with the public ATLAS Open Data — Z→ll, H→ZZ→4l, H→γγ, H→μμ, H→bb, t-tbar, or WZ→3l+ν. Pairs the process to its docs section in `13TeV25Doc/StandardModel` and its notebook in `notebooks-collection-opendata/13-TeV-examples/uproot_python/`. Does NOT cover BSM searches, generic notebook indexing by filename (use `atlas-notebooks`), or analysis-code authoring (use `physlite-basics` or the `analysis` agent). Disambiguator phrase: SM walkthrough by process.

Use when the user asks how a CERN service or ATLAS / FTS framework operates and the answer should come from canonical operator documentation — HTCondor / lxbatch submission, SWAN session settings and HTCondor pool, CERN Cloud (OpenStack) flavors and quotas, ML@CERN training and serving, ATLAS Athena / ASG / Tier-0 / databases, ATLAS computing and grid production, FTS3 (File Transfer Service) configuration / installation / REST API / messaging / monitoring. Backed by the `cerndocs` MCP (`search_docs` for BM25 search, `fetch_doc` for one page) over 8 indexed sources: atlas-sft, atlas-computing, atlas-databases, batch, cloud, ml, swan, fts. Does NOT cover the `fts-rest-*` CLI itself (use `fts-rest`), Open Data dataset / recid / DOI lookup (use `cern-opendata` or `atlas-opendata`), live job-state inspection (use `reana` or shell tools), or multi-service infra recommendations (use `infra-advisor`). Disambiguator phrase: CERN docs BM25 multi-source.