n8n-community-pr-readiness-check

name n8n:community-pr-readiness-check description Checks if a community pull request is ready for human review. Verifies CLA signature, PR title format, description completeness, test coverage, and cubic-dev-ai issues, then triages to the right Linear team or recommends a close. Use when given a PR number or branch name to review, or when the user says /community-pr-readiness-check, or asks to check if a PR is ready for review. allowed-tools Bash(gh:*), Bash(git:*), Bash(node:*), Read, Glob, Grep compatibility {"requires":[{"mcp":"linear","description":"Required for reading and updating Linear tickets during triage"},{"cli":"gh","description":"Required for PR inspection and triage actions. Must be authenticated (gh auth login)"}]} Community PR Readiness Check Given a PR number or branch name, determine whether it is ready for human review and take the right follow-up action. Decision tree Bot author ( n8n-cat-bot / aikido-autofix ) → cleanup-only, no review. See "Internal automation PRs" below. Auto-rejection screen matches (typo-only / unsanctioned new node / low-value) → action path D — close with the matching template. All checks pass ( readyForReview === true ) → action path B — triage to team . One or more checks fail → action path A (if title is minor-fix only) then C — post comment . Step 1 — Resolve the PR If given a branch name, find the PR number first: gh pr view <branch> --repo n8n-io/n8n --json number --jq .number Step 2 — Fetch and pre-process gh pr view <number> --repo n8n-io/n8n \ --json number,title,body,author,headRefName,headRefOid,files,isDraft,state,labels Internal automation PRs (bot authors) If author.login is one of n8n's internal bots — n8n-cat-bot / app/n8n-cat-bot or aikido-autofix / app/aikido-autofix — skip the PR entirely and perform the cleanup actions below. Do not emit any JSON output. Relabel the PR (both bots): swap community → n8n team : gh pr edit <number> --repo n8n-io/n8n --remove-label community --add-label "n8n team" Update the linked Linear ticket (extract GHC-XXXX per step 5): n8n-cat-bot — cancel: use the available Linear MCP issue-update tool with state: "Canceled" , no labels. aikido-autofix — route to Dev Platform: use the available Linear MCP issue-update tool with team: "Developer Platform" , state: "Triage" , no labels. When reviewing a batch, omit the skipped PR from the output. For a single PR, emit a one-line note (e.g. Skipped & cleaned up #30591 (n8n-cat-bot): relabeled to n8n team, cancelled GHC-8398. ). Collision guard If triage:in-progress is already on the PR, another reviewer is mid-triage — bail out to avoid double-processing. Emit a one-line note (e.g. Skipped #30205: already has triage:in-progress ) and move on to the next PR. Do not run the checks, do not modify labels, do not touch Linear. If the user explicitly asks to re-process a PR that's stuck on triage:in-progress (e.g. a previous run crashed), they can clear the label manually and re-invoke. Otherwise — mark in-progress Strip any existing triage:* state label before adding triage:in-progress , so the single-state invariant holds even when re-reviewing a PR that was previously sent back with triage:needs-info or triage:tests-needed : gh pr edit <number> --repo n8n-io/n8n \ --remove-label "triage:pending" \ --remove-label "triage:needs-info" \ --remove-label "triage:tests-needed" \ --remove-label "triage:complete" \ --add-label "triage:in-progress" Only one of those triage:* labels will actually be present; --remove-label errors when a label is missing, so run each removal as its own call (or batch and ignore errors) and then do the add. A PR carries exactly one triage:<state> label at a time; the skill replaces triage:in-progress with a terminal state before exit (see reference/label-flow.md ). Also fetch (in parallel) # cubic-dev-ai PR review comments (for check E) gh api --paginate "repos/n8n-io/n8n/pulls/<number>/comments" \ --jq '.[] | select(.user.login == "cubic-dev-ai[bot]") | {body: .body, path: .path}' # n8n-assistant issue comments (for the Linear ticket reference) gh api --paginate "repos/n8n-io/n8n/issues/<number>/comments" \ --jq '[.[] | select(.user.login == "n8n-assistant[bot]" or .user.login == "n8n-assistant") | .body] | join("\n")' Step 2.5 — Auto-rejection screen Per CONTRIBUTING.md , three PR patterns should be closed outright rather than reviewed: Typo-only PR — diff is entirely spelling/grammar fixes with no logic or tests. New-node PR — adds a brand-new node, unless the n8n team has explicitly agreed to take it. Low-value / automated PR — diff is entirely whitespace/formatting/reordering, an unexplained mass rename or dependency bump, badge/comment-only tweaks, or a bulk scripted submission, with no functional change or rationale. Screen conservatively. If any matches, set checks.AutoReject and skip directly to action D . Full rules and how to verify each pattern: see reference/checks.md . Step 3 — Run the readiness checks Run when AutoReject is null . Full rules for each in reference/checks.md : A. CLA — cla-signed label present. B. Title — matches the conventional-commit regex. Authoritative rules in .github/pull_request_title_conventions.md . C. Description — every section heading and checklist item from .github/pull_request_template.md is present in the PR body. The template is read at check time, so changes to it propagate automatically. D. Tests — source logic changes have matching test files (a fix needs a regression test covering the bug). Skip for docs/ci/chore/build PRs. E. cubic-dev-ai — no unresolved comments (resolved = "Addressed in commit" marker). F. Linked issue or forum discussion — fix PRs link a GitHub issue; feat / refactor / perf PRs link an issue or community.n8n.io topic. Skip for docs/ci/chore/build/test . G. Size — sum of per-file additions in files (skipping lockfiles/generated) ≤ 1000 and one logical change; sets Oversized . Step 4 — Identify the responsible team Run node .github/scripts/owners.mjs against the changed file list and map the winning GitHub team to a Linear team. Full mapping table, sub-agent fallback procedure, and label rules: see reference/teams.md . Step 5 — Extract the Linear ticket n8n-assistant leaves a comment on every community PR containing This PR has been added to our internal tracker as "GHC-XXXX" . Search the concatenated n8n-assistant comment body for \bGHC-\d+\b , take the first match. If no n8n-assistant comment exists (older PRs that predate the automation), linearTicket is null . Step 5b — Find related issue tickets and detect duplicates The PR body often says Fixes #NNNN / Closes #NNNN / Resolves #NNNN (or links to https://github.com/n8n-io/n8n/issues/NNNN ). Each of those issues usually has its own GHC ticket (or has already been triaged to a team). When a PR references an issue, that issue ticket becomes the source of truth: the action paths link the PR onto it and (when ready) cancel the PR's own review ticket. Surface the related tickets and any duplicate PRs here so the action paths can act on them. Related issue tickets Extract every issue number from the PR body matching \b(?:fix(?:es)?|close[sd]?|resolve[sd]?)\s+#?(\d+)\b (case-insensitive) or URLs matching github\.com/n8n-io/n8n/issues/(\d+) . Deduplicate. For each issue number, search Linear with the available Linear MCP issue-search tool (query github.com/n8n-io/n8n/issues/<num> , limit 50) and filter the result to issues whose description contains the exact URL https://github.com/n8n-io/n8n/issues/<num> . The n8n-assistant bot embeds that URL in the description of every community-issue ticket it creates, so the match is reliable. Use the default limit of 50 (not a smaller value): the query is a substring search ordered by updatedAt , so issues/<num> also matches longer issue numbers (e.g. searching 123 matches 1234 ) and the exact ticket can sit anywhere in the result set — a tight limit would silently drop it. If 50 results come back full, paginate with cursor until the exact match is found or results are exhausted. Collect the matching ticket IDs (e.g. GHC-1234 , or wherever they've been routed since — NODE-5678 , CAT-3338 ). Include cancelled/duplicate tickets too — the link is still useful for traceability. Emit the result as relatedIssueTickets in the JSON. If no Fixes/Closes/Resolves references exist, return relatedIssueTickets: [] . The linking action itself lives in step 7 (see "Linking a PR to its issue ticket"). Duplicate PRs When a PR references an issue, another contributor may already have an open PR for the same issue. Gather candidate duplicates from three signals — any hit means the action path should ask whether to close this PR (path D, duplicate template). Run for each referenced issue number: # Other open PRs mentioning the same issue gh pr list --repo n8n-io/n8n --state open \ --search "#<num> in:body" --json number,title,author # PRs cross-referenced / linked on the GitHub issue itself gh api --paginate "repos/n8n-io/n8n/issues/<num>/timeline" \ --jq '[.[] | select(.event=="cross-referenced") | .source.issue | select(.pull_request) | {number, title}]' Also inspect the matched Linear issue ticket (from the search above) for an already-attached PR link in its links /attachments. Exclude the PR under review from every signal, deduplicate by PR number, and emit the result as duplicatePRs in the JSON ( [] when none). Step 6 — Output JSON { "readyForReview" : < true if all passing checks allow merge , false otherwise> , "messageForUser" : "<Short message to the contributor listing what they need to address. 'N/A' if ready.>" , "team" : "<Linear team name (from reference/teams.md), or 'Engineering' as fallback>" , "linearTicket" : "<GHC-XXXX or null>" , "relatedIssueTickets" : [ < "GHC-1234" | "NODE-5678" | ...> ] , "duplicatePRs" : [ < { "number" : <int> , "title" : "<string>" } , ...> ] , "checks" : { "AutoReject" : < "typo-only" | "new-node" | "low-value" | null > , "CLA" : <bool> , "Title" : <bool> , "Description" : <bool> , "TestsNeeded" : <bool> , "TestsIncluded" : <bool> , "CubicIssues" : < true if unresolved cubic issues exist , false otherwise> , "LinkedIssueOrDiscussion" : < true if the § 1 issue/forum link is present or the type is skipped> , "Oversized" : < true if the filtered per-file additions sum > 1000 and the work is separable> } } readyForReview is true only when: AutoReject is null ; CLA , Title , Description , and LinkedIssueOrDiscussion are all true ; CubicIssues and Oversized are both false ; and either TestsNeeded is false or TestsIncluded is true . If AutoReject is set, readyForReview is always false . Emit the JSON first, then take the appropriate action path below. Step 7 — Action paths Ask the user for each prompt (presented as the listed options). Sub-agents called for analysis only should stop after step 6 and let the caller drive step 7. Linking a PR to its issue ticket Invoked from B and C whenever relatedIssueTickets is non-empty. The referenced issue ticket becomes the source of truth; the PR is attached to it via Linear's link feature. For each ticket in relatedIssueTickets , call the Linear MCP issue-update tool: id = <issue ticket> links = [{ url: "https://github.com/n8n-io/n8n/pull/<pr>", title: "Community PR #<pr>" }] # append-only — existing links are preserved Then post a comment (Linear MCP comment tool, issueId = <issue ticket> ) whose wording depends on whether the PR is ready: ready + assign (path B): "The linked community PR # may resolve this issue." not ready (path C): "A community PR (# ) is in progress that may resolve this, but it is still being triaged." State and ticket-closure handling differ by path and are described in B and C below. A — Minor title fix A title issue is minor if it can be repaired by a deterministic transformation: Leading or trailing whitespace. First letter of the summary in the wrong case. Trailing period. Mixed case revert: requiring lowercase (no change needed, just flag). If the only failing check is Title (or Title + CubicIssues ) and the issue is minor, propose the fix and ask Apply proposed / Edit before applying / Skip . Apply with: gh pr edit <number> --repo n8n-io/n8n --title "<new title>" Then re-evaluate Title (now passes) and continue to B or C . Non-minor title problems (wrong/missing type, no colon, hyphenated scope) need contributor input — skip A and go to C . B — Triage to team ( readyForReview === true ) Duplicate guard first. If duplicatePRs is non-empty, surface them (number + title) and ask whether to close this PR as a duplicate. On Yes , go to D (duplicate template). On No , continue with B below. Destination state: Review for NODES, Triage for every other team — keyed off the PR's resolved owner team . Label composition: see reference/teams.md . If relatedIssueTickets is non-empty — the issue ticket is the source of truth. Ask: "PR is ready for review. Link it onto issue ticket(s) <relatedIssueTickets> , move them to , and cancel the PR's own ticket <linearTicket> ?" Options: Yes, link and triage / No, leave as-is . On Yes : Run "Linking a PR to its issue ticket" (ready variant) for each related ticket. Move each related issue ticket's state via the Linear MCP issue-update tool ( id = <issue ticket> , state = <destination> ) — Review for NODES, Triage otherwise. Cancel the PR's own review ticket: Linear MCP issue-update with id = linearTicket , state = "Canceled" (skip if linearTicket is null ). Apply the GitHub PR labels (only if the Linear updates succeeded), so reviewers still find the PR: gh pr edit <number> --repo n8n-io/n8n \ --remove-label "triage:in-progress" \ --remove-label "status:pending-assignment" \ --add-label "team:<slug>" \ --add-label "status:team-assigned" \ --add-label "triage:complete" Otherwise (no related issue ticket) — classic path, unchanged. Ask: "PR is ready for review. Assign Linear ticket <linearTicket> to team <team> and move to ?" Options: Yes, assign and triage / No, leave as-is . On Yes : # 1. Linear — call the available Linear MCP issue-update tool with: # id = linearTicket # team = <team> # state = <destination> # labels = <computed labels> # 2. GitHub (only if Linear succeeded) — see reference/label-flow.md gh pr edit <number> --repo n8n-io/n8n \