Changelog: Nextflow v25.10.5

.claude/skills/docs-state-assessment/SKILL.md

@@ -12,82 +12,82 @@ description: >
   priorities. This skill focuses on the state of the work — what exists, what's in flight, what's missing —
   not on personas, information architecture, or where content should live in the doc site.
 ---
- 
+
 # Docs State Assessment
- 
+
 Produce a structured gap analysis for a Seqera product area by pulling from four sources and cross-referencing them.
- 
+
 ## Why this skill exists
- 
+
 Documentation teams working across multiple product areas need to quickly answer: "What's the current state of docs for this project?" Doing this manually means opening GitHub, scanning PRs, checking Jira, reading the published docs, and browsing the repo — then holding all of that in your head while you figure out the deltas. This skill turns that into a repeatable process with a consistent output format.
- 
+
 ## The four data sources
- 
+
 Every assessment pulls from these four layers. Each one answers a different question:
- 
+
 | Source | Question it answers | How to access it |
 |--------|-------------------|------------------|
 | **Published docs** (docs.seqera.io) | What do customers see today? | `web_fetch` the product area's doc index page, then fetch each subpage |
 | **GitHub PRs** (open) | What's shipping soon that may need docs? | Browse the repo's open PRs via Claude in Chrome, or use `gh` CLI if available |
 | **Jira backlog** | What's planned that will create doc needs? | `searchJiraIssuesUsingJql` — filter out security issues and Done items |
 | **Internal repo docs** | What source material exists that isn't published? | Browse the repo's `docs/` directory (or equivalent) via Chrome or filesystem |
- 
+
 The power is in the cross-referencing. Any single source gives you a partial picture. The assessment finds the gaps between them.
- 
+
 ## Before you start
- 
+
 Gather these inputs from the user (or from conversation context):
- 
+
 1. **GitHub repo** — the repository to assess (e.g., `seqeralabs/portal`)
 2. **Jira project key** — the Jira project tracking work for this product (e.g., `SH`)
 3. **Published docs URL** — the root URL of the product's section on docs.seqera.io (e.g., `https://docs.seqera.io/platform-cloud/seqera-ai/`)
 4. **Jira Cloud ID** — typically the Atlassian site URL (e.g., `seqera.atlassian.net`)
 If the user doesn't provide all four, ask for what's missing. Often the repo and Jira project are enough — you can infer the docs URL from the product area name, and the Cloud ID from the Jira URL.
- 
+
 ## Practical notes on tooling
- 
+
 **Private repos**: If the GitHub repo is private, `web_fetch` will return 404. Use Claude in Chrome to browse the repo instead — navigate to the PRs page and read the page text. This is the most reliable approach for private Seqera repos.
- 
+
 **Large Jira result sets**: The SH project (Seqera AI) has thousands of issues. Always filter out security issues and Done/Canceled items in the JQL query. If results still exceed token limits, the output gets saved to a file — use `jq` or Python to extract just the fields you need (key, summary, status, issuetype, priority, assignee).
- 
+
 **Parallelize where possible**: Steps 1 (published docs) and 3 (Jira) don't depend on each other. Fetch them in parallel. Step 2 (PRs) requires browser navigation, so it runs sequentially. Step 4 (internal docs) can run in parallel with Step 2 if you have filesystem access to the repo.
- 
+
 ## The assessment process
- 
+
 Work through these steps in order. Each step builds on the previous one.
- 
+
 ### Step 1: Inventory the published docs
- 
+
 Fetch the product area's index page on docs.seqera.io. Extract:
 - The full page list from the sidebar navigation
 - For each page: title, URL, and a brief note on what it covers
 Then fetch 3-5 of the most substantive pages (not just the index) to understand the depth of coverage. You're looking for: how detailed are they? Do they cover setup, configuration, advanced usage, troubleshooting? Or are they surface-level overviews?
- 
+
 Record this as a table with columns: Page, Coverage depth (overview / moderate / detailed), Key topics covered.
- 
+
 ### Step 2: Scan the GitHub PRs
- 
+
 Navigate to the repo's open PRs page. Read through all pages (repos with active development often have 50-100+ open PRs). For each PR, note:
 - PR number and title
 - Scope prefix (feat, fix, docs, chore, etc.)
 - Status (Draft, Review required, Approved, Changes requested)
 - Priority labels if any (ship-this-week, next-sprint, backlog)
 Filter out noise: dependency bumps (renovate/dependabot), security patches, and pure CI/tooling changes rarely need docs. Focus on `feat()`, `fix()` that changes user-facing behavior, and `docs()` PRs.
- 
+
 Group the remaining PRs by theme — features that relate to each other often imply the same doc page or section. Common groupings: authentication, new commands/features, UI changes, API changes, performance/reliability.
- 
+
 ### Step 3: Query the Jira backlog
- 
+
 Search for non-security, non-Done issues:
- 
+
 ```
 project = <KEY> AND issuetype NOT IN ("Security Issue") AND status NOT IN (Done, Canceled) ORDER BY created DESC
 ```
- 
+
 Request fields: summary, status, issuetype, priority, assignee, labels, components.
- 
+
 If the result set is too large for context, it will be saved to a file. Extract the essentials with a script:
- 
+
 ```python
 import json, sys
 data = json.load(sys.stdin)
@@ -102,78 +102,78 @@ for item in data:
         assignee = (f.get('assignee') or {}).get('displayName', 'Unassigned')
         print(f'{key} | {itype} | {status} | {assignee} | {summary}')
 ```
- 
+
 From the results, extract:
 - **Epics** — these represent large initiatives, each potentially implying an entire doc set
 - **Stories/Tasks with doc implications** — new features, migrations, integrations
 - **In-progress items** — these are shipping soonest and need docs coordination
 - **Bugs that affect doc accuracy** — behavioral changes that make current docs wrong
 Skip: internal tooling tasks, eval/benchmark work, and items that are purely backend optimization with no user-facing change.
- 
+
 ### Step 4: Scan internal repo docs
- 
+
 Browse the repo's documentation directory (usually `docs/`, sometimes scattered across component READMEs). Inventory what exists:
 - Design specs / PRDs (contain source material for customer-facing docs)
 - Architecture docs (internal reference)
 - Setup/onboarding guides (internal dev audience)
 - Process docs (internal workflows)
 The key question: does the repo contain information that should be in the published docs but isn't? Design specs are the most common source of this gap — they describe features in detail for the engineering team but that information never makes it to customer-facing documentation.
- 
+
 ### Step 5: Cross-reference and produce the gap analysis
- 
+
 This is where the four sources come together. Produce four delta categories:
- 
+
 **1. Shipped but not documented** — Features or capabilities that exist in the product (merged to main, available to users) but have no corresponding published documentation. These are found by comparing internal repo docs and recent merged PRs against the published doc inventory. Severity: Critical or High.
- 
+
 **2. In flight — will need docs soon** — Open PRs that are approved, in review, or labeled as shipping soon. Cross-reference with any Jira items they link to. For each, note what published doc page needs updating or whether a new page is needed. Severity: varies by ship timeline.
- 
+
 **3. Planned — will create future doc needs** — Jira epics and stories in the backlog that will require documentation when they ship. These help the docs team plan capacity. Note estimated doc scope (new page, new section, update to existing page, entirely new doc set).
- 
+
 **4. Published docs that may be stale** — Existing published pages where open PRs or Jira items suggest the behavior is changing. For example, if there's an auth hardening PR shipping this week, the published authentication page is at risk of becoming inaccurate.
- 
+
 ## Output format
- 
+
 Produce a markdown document with this structure:
- 
+
 ```markdown
 # [Product Area]: Documentation State Assessment
 *Generated: [date]*
- 
+
 ## Published docs inventory
 [Table of what exists on docs.seqera.io with coverage depth]
- 
+
 ## Open PRs with doc implications
 [Grouped by theme, filtered to only doc-relevant PRs]
- 
+
 ## Jira backlog with doc implications
 [Epics, stories, and bugs that affect docs — separated by type]
- 
+
 ## Gap analysis
- 
+
 ### Shipped but not documented
 [Table: Feature | Source | Gap severity]
- 
+
 ### In flight — needs docs soon
 [Table: Feature | PR(s) | Jira | Doc action needed]
- 
+
 ### Planned — future doc needs
 [Table: Initiative | Jira | Doc impact estimate]
- 
+
 ### Published docs at risk of staleness
 [Table: Published page | Risk level | Source of drift]
- 
+
 ## Recommended priorities
 [Ordered list: what to do this week, next sprint, next quarter]
 ```
- 
+
 ## Important guidance
- 
+
 **Be specific about what's missing, not vague.** "Web UI docs are missing" is less useful than "The web UI has a sandbox file explorer (PR #872), an explain-failure action (PR #873), and a code selector (PR #835), but zero published documentation for any web UI feature."
- 
+
 **Severity matters.** A missing config reference page for an enterprise product is more urgent than a missing page about an exploration-labeled prototype. Use the PR labels and Jira statuses to gauge urgency.
- 
+
 **Don't boil the ocean.** If the repo has 200 open PRs, you don't need to analyze all of them. Focus on `feat()` and `fix()` scopes, skip renovate/dependabot, skip exploration-labeled items unless they're unusually significant. Call out how many you filtered and why.
- 
+
 **Cross-reference by keyword, not just by ticket number.** A Jira epic about "background agents" and a PR titled "add trigger-session endpoint for background AI sessions" are related even if the PR doesn't reference the Jira key. Connect them.
- 
+
 **The output is a working document, not a final report.** It should be useful in a planning session — scannable tables, clear severity ratings, and actionable next steps. Keep prose minimal; let the tables do the talking.

.claude/skills/feature-docs/SKILL.md

@@ -9,62 +9,62 @@ description: >
   for this feature" or "can you draft docs from these sources". Also use when the user provides a mix of
   Jira links, Google Doc links, GitHub PR links, or uploaded PDFs and wants documentation produced from them.
 ---
- 
+
 # Feature Docs
- 
+
 Turn feature sources into Seqera Platform documentation updates. This skill takes a mix of inputs — Jira epics, PRDs, design docs, GitHub PRs, and the current published docs — and produces structured documentation outputs: gap analyses, draft content, full drop-in replacement files, and change summaries.
- 
+
 ## Before you start
- 
+
 Read the `seqera-brand-guidelines` skill (SKILL.md) for Seqera product terminology and tone. The brand skill covers naming conventions (e.g., "Seqera Platform" not "Tower", "Nextflow" capitalization) and visual identity. This skill covers doc structure and content workflow.
- 
+
 Also read `references/docusaurus-conventions.md` in this skill's directory for Seqera-specific formatting patterns (admonitions, link references, frontmatter, heading hierarchy).
- 
+
 ## How the skill works
- 
+
 The workflow has five phases. Not every run needs all five — the user might just want a gap analysis, or they might want the full pipeline. Ask if unclear, but default to running all five phases and producing all outputs.
- 
+
 ### Phase 1: Gather and read all sources
- 
+
 The user will provide some combination of:
- 
+
 - **Jira epic or ticket URLs** — Use the Jira MCP tools (`searchJiraIssuesUsingJql`, `getJiraIssue`) to read the epic, its child issues, acceptance criteria, and status. Extract feature names, scope, and what's been completed.
 - **PRD / Design Doc** — These may be uploaded as PDFs, shared as Google Doc links (use the browser to read them), or pasted into the conversation. Extract requirements, acceptance criteria, API field names, behavioral specifications, and out-of-scope items.
 - **GitHub PRs** — Use the browser to read PR descriptions and diffs. Focus on what changed, what fields were added, and what the PR description says about user-facing behavior. Check both open and merged PRs under the epic.
 - **Published docs (URLs)** — Fetch the current live documentation. This is your baseline. If the URL points to a raw markdown file on GitHub, that's the actual source of truth for the doc structure.
 Read everything before writing anything. The value of this skill is in the cross-referencing — catching things that one source mentions but another doesn't.
- 
+
 **Practical tips for source gathering:**
 - Jira child issue queries can return huge results. If the response is too large, save it to a file and extract summaries programmatically.
 - Google Docs may need to be accessed via the browser's authenticated session. If `get_page_text` doesn't return the document body, try using `fetch()` with the `/export?format=txt` endpoint from within the page context.
 - GitHub PR pages can be very large. Use `document.querySelector('.markdown-body')?.innerText` via the JavaScript tool to extract just the PR description.
 - Some content may be blocked by browser content filters (especially text containing credentials or keys). Extract in smaller sections or use alternative methods.
 ### Phase 2: Gap analysis
- 
+
 Compare what the current docs say against what the sources say should be true. For each gap, document:
- 
+
 1. **What the current docs say** (quote the specific text)
 2. **What reality is now** (cite the source — which Jira ticket, which PR, which section of the PRD)
 3. **What needs to change** (specific, actionable — not vague)
 4. **Where in the doc** (section heading and approximate location)
 Organize gaps by severity: Critical (docs are actively wrong/misleading), Important (significant feature not documented), Minor (wording tweaks, label changes).
- 
+
 Also flag **open questions** — things where the sources disagree or are ambiguous, where you'd need engineering or product confirmation.
- 
+
 ### Phase 3: Draft content
- 
+
 For each gap, draft the replacement content. Write it in the voice and format of the existing doc — match heading levels, step numbering style, admonition usage, and link reference patterns. See `references/docusaurus-conventions.md` for the specific patterns.
- 
+
 Key principles:
 - **Preserve what works.** Don't rewrite sections that don't need changing. Surgically insert, replace, or remove content.
 - **Match the existing voice.** Seqera docs are instructional and direct. Steps use imperative mood ("Select...", "Enter..."). Explanatory text is concise but not terse.
 - **Use admonitions purposefully.** `:::note` for supplementary info, `:::info` for important context, `:::caution` for things that could cost money or break something, `:::tip` for best practices.
 - **API field names go in backticks.** E.g., `managedIdentityClientId`, `jobMaxWallClockTime`.
 - **Link references go at the bottom of the file.** Use descriptive names, not short abbreviations.
 ### Phase 4: Produce the output
- 
+
 Depending on what the user asked for (or defaulting to all of the below):
- 
+
 **Mode A: Gap analysis only**
 - A markdown file listing all gaps, organized by severity, with source citations and recommended changes.
 **Mode B: Gap analysis + draft content**
@@ -74,31 +74,31 @@ Depending on what the user asked for (or defaulting to all of the below):
 **Mode D: Change summary**
 - A structured changelog document organized section-by-section: what was added, removed, or changed, and why. Useful for doc review and for understanding the scope of changes at a glance.
 The default output when the user says "draft docs for this feature" or similar is **Mode C + Mode D** — a full replacement file plus a change summary.
- 
+
 All output files go in the outputs directory so the user can access them.
- 
+
 ### Phase 5: Cross-reference verification
- 
+
 After producing the output, verify it against every source. For each requirement or acceptance criterion in the PRD and design doc, check whether the updated docs reflect it. Produce a verification checklist:
- 
+
 - ✅ Requirement is fully reflected in the updated docs
 - ⚠️ Partially reflected or acceptable omission (explain why)
 - ❌ Missing — needs to be added
 Flag anything that needs engineering/product confirmation (e.g., "Design doc mentions field X but it's unclear if it's user-facing").
- 
+
 This phase catches things you missed in the initial pass. It's the most important quality gate.
- 
+
 ## Naming conventions for output files
- 
+
 Use descriptive names based on the doc being updated:
- 
+
 - `{page-name}-gap-analysis.md` — Gap analysis (Mode A/B)
 - `{page-name}-updated.md` — Full replacement (Mode C)
 - `{page-name}-change-summary.md` — Change summary (Mode D)
 For example: `azure-batch-gap-analysis.md`, `azure-batch-updated.md`, `azure-batch-change-summary.md`.
- 
+
 ## When things go wrong
- 
+
 - **Can't access a source**: Tell the user which source you couldn't read and why. Ask them to upload it as a PDF or paste the relevant content. Don't silently skip sources.
 - **Sources contradict each other**: Flag the contradiction explicitly in the gap analysis. Don't guess — list both versions and mark it as needing confirmation.
 - **Not sure if a feature is user-facing**: Include it in the gap analysis as an open question. Better to flag something unnecessary than to miss something important.