nf-metro

End-to-end workflow for fixing GitHub issues on the nf-metro repo with diagnostic rigor. Use when the user references a GitHub issue (by number, URL, or description) and wants it fixed. Handles worktree setup, a reused persistent env (no per-issue env creation), diagnostic-first investigation, authoring-mistake-vs-engine-bug triage (never dodge an engine bug by doctoring the reproducer), invariant-test-first implementation, runtime validators, evidence-cited fix verification, /simplify pass, full-repo lint, visual review via render preview, narrow-the-fix iteration on regressions, cost discipline (targeted tests, CI render-diff over local gallery rebuilds, skip-ci on WIP), scope discipline that fixes adjacent fallout in-session via delegated subagents instead of deferring it to a child issue, standalone issue-body hygiene, additive-only PR hygiene (no force-push, no narrative comments), clean execution of an authorised admin-merge (preserve history, no CI re-run), origin verification after every push, and PR

Diagnose and un-stick GitHub Pages publishing for nf-metro when a PR render preview or the docs site isn't updating. Use when a `_pr/<N>/` preview 404s or shows stale content, the "render preview is ready" link doesn't work, the docs site didn't refresh after a merge, or you suspect a Pages build stalled. Trigger on phrases like "the preview isn't updating", "the render preview link is broken", "check the pages ci", "poke the pages build", "docs site is stale", "did my preview publish". Covers the legacy-builder stall (the usual culprit), the re-trigger fix, the pr-renders -> pr-render-publish -> build chain, the render content marker, and the CDN caching gotchas that make verification misleading.

End-to-end release workflow for nf-metro. Checks the bioconda recipe for missing deps and bumps its build number if needed, bumps version in pyproject.toml and __init__.py, drafts a docs/releases/<version>.md page from the git log since the last tag (with illustrations where relevant), wires it into mkdocs.yml nav and the releases index table, then opens a PR. After merge, reminds you to create the GitHub Release. Trigger on phrases like "cut a release", "release X.Y.Z", "prepare release", "bump version to X.Y.Z".

Run a routing gate-arm triage slice on nf-metro - give every un-exercised branch arm in a layout/routing module a verdict (reachable -> author a fixture, defensive, candidate-dead, or reachable-but-defective -> file a bug). Use when the user wants to triage routing gate arms, close coverage-matrix gaps, work a

Wire an nf-metro diagram into an nf-core (or any Nextflow) pipeline repo - the mechanical pipeline-side setup, not the authoring of the .mmd itself. Use whenever the user wants to add nf-metro tooling to a pipeline (assets/metro_map.mmd, docs/dev/metro_map.md, the rendered SVG/PNG/animated assets, README image swap, CHANGELOG entry), replace an existing workflow.png/svg with a metro map, mirror the nf-core/rnaseq setup on a new pipeline, or pin nf-metro to a named branch of a fork while waiting for upstream fixes to land. Trigger on phrases like "set up nf-metro on pipeline X", "wire the metro map into the repo", "replace workflow.png with a metro map", "ship the metro diagram in pipeline Y", "pin nf-metro to my fork branch while we wait for the fixes", "what assets do I need in docs/images for the metro map".

Local visual regression check for layout or rendering changes. Renders all gallery examples, pixel-diffs against main, and opens changed renders as BEFORE/AFTER pairs. In most cases the CI render preview on a PR is sufficient - use this skill only for pre-push confidence on risky changes or when the user explicitly asks for a local diff.

Spin up the Astro / Starlight documentation site locally for live preview, optionally for a specific nf-metro branch. Use when the user wants to run, serve, preview, or develop the docs site (website/) - phrases like "serve the docs", "spin up the site", "run the docs locally", "preview the website", "start the astro server", "preview the docs for branch X / this PR", or when iterating on docs content, theme/layout overrides, or the gallery/pipelines/playground pages and wanting to see changes in a browser. Wraps scripts/serve_docs.sh, which generates the git-ignored dynamic content (gallery, pipelines, playground manifest) before starting the dev server, and with --branch checks the branch out into an isolated worktree and installs its nf_metro so the renders reflect that branch.

Build a self-contained HTML triage page for failing/xfailing layout-invariant tests in nf-metro (test_label_x_anchored_to_station_marker_on_horizontal_runs, test_visual_stack_station_xs_share_column, test_row_trunk_marker_cy_consistent, test_no_kink_at_section_boundary, test_symfan_pairs_share_y, test_lines_dont_cross_non_consumer_markers, test_topological_siblings_share_y_or_symmetric, test_section_bbox_has_bottom_padding, test_off_track_inputs_above_consumer). Each row pairs the rendered fixture SVG with a red-bbox overlay on the offending element, a plain-English "Supposed issue" + "What to check" explanation, and bug / not-a-bug / ambiguous triage buttons whose state is saved in localStorage and exported as JSON. Use when the user asks to "triage layout invariants", "review xfails", "review failing layout tests", "build the triage page", or generally wants to triage the layout-invariant test suite by eye.

Stress-test the nf-metro layout engine by composing a brand-new, deliberately complex pipeline metro map, rendering it, and hunting for layout bugs the way a real never-seen-before pipeline would surface them. Use this whenever the user wants to fuzz / stress / probe the layout engine, find new layout bugs, check robustness against novelty, "throw a weird pipeline at it", generate a novel test render, or run an ad-hoc bug-hunting pass. Each run invents ONE novel topology (braiding structural axes that have not been combined before), renders it, runs the programmatic layout validator, and PRESENTS the render for you to eyeball the aesthetic bugs a validator can't see. Every candidate defect - whether the validator flagged it or you reported it by eye - is CONFIRMED against the laid-out geometry (exact coordinates, off-trunk drags, off-track gaps, inter-row gaps) and understood at the mechanism level before anything is filed; reports are never filed on eyeball alone. Confirmed bugs are FILED as GitHub issues (a

Drive code-level fixes to nf-metro when a real pipeline render exposes a layout bug that isn't a mmd mistake, without regressing pipelines that already ship metro maps. Use when working in nf-metro's src/ (layout engine, routing, parser) to fix kinks, station overlaps, breeze-past, asymmetric fans, bypass routing, or bbox overflow on a real pipeline diagram. Covers the savepoint tag pattern, the invariant-test-first-then-fix-then-runtime-validator loop, gallery regression vetting with build_gallery and build_render_diff, converting global fixes to conditional ones so other renders aren't pushed around, and the additive-commits-only PR chain workflow. For authoring the mmd content itself (deciding lines, stations, sections), see the `pipeline-metro-diagram` skill. For routine gallery regression testing of nf-metro, see `render-topologies`.

Per-PR vetting workflow for shepherding a stacked PR chain on nf-metro back into main - one PR at a time, gallery-diff against main, additive cleanups, no force-push, ready for human review. Use whenever the user is working through a chain of layout/refactor PRs on nf-metro and asks to "vet this PR before review", "walk through the chain", "check PR N for gallery regressions", "prepare PR for review", "do a vetting pass on PR N", "make this PR mergeable", or is otherwise driving stacked PRs toward main and needs each one cleaned up and CI-greened in turn. Covers worktree setup, reverting known-rejected commits, conflict reconciliation against main, the /simplify pass as a separate commit, render-and-diff against main, classifying every visual delta (improvement / neutral / detrimental), appending fix commits for detrimentals, sweeping narrative PR comments, rewriting PR descriptions to be standalone, triggering CI on the final commit, and the post-merge cleanup order (re-target children BEFORE deleting the me

Author the mmd content for a pipeline's metro map - turn the pipeline's workflow code into a faithful, readable metro diagram. Use whenever the user is iterating on a pipeline's .mmd to improve fidelity to the workflow code, visual clarity, or layout params. Trigger on phrases like "make a metro map for pipeline X", "iterate on the mmd for pipeline Z", "the metro map for funcscan doesn't match the workflow", or "this station shouldn't be on the rnaseq line". Covers studying the workflow to model lines/stations/branches, deciding line and section structure, `%%metro file:` and `%%metro off_track:` directives, the render-inspect-edit iteration loop, common pitfalls (breeze-past, fan asymmetry, section-boundary kinks), and the "is it mmd or nf-metro?" triage. When the diagnosis lands on nf-metro itself producing a bad layout for a correct mmd, hand off to the `nf-metro-layout-fix` skill. For the mechanical pipeline-repo setup (assets/, docs/dev/metro_map.md, render commands, README swap), see `pipeline-metro-set