n8n-create-issue

# Create Issue Create a Linear ticket or GitHub issue for: **$ARGUMENTS** Write all titles and descriptions in ASD-STE100 Simplified Technical English: use short sentences, the active voice, and one instruction for each sentence. ## Determine Target Decide where the issue should be created based on user input: - If the user says "Linear", "ticket", or provides a team key (e.g., AI, NODE, N8N) → **Linear** - If the user says "GitHub", "GH issue", or "open source" → **GitHub** - If ambiguous, **ask the user** which platform they want --- ## Linear Tickets ### Prerequisites Verify the Linear MCP is connected before proceeding. ### Style Guide #### Title - **Sentence case** — capitalize only the first word (e.g., "Add webhook verification to Trello trigger") - **Descriptive** — a reader should understand the scope without opening the ticket - **5–15 words** — long enough to be specific, short enough to scan - **Imperative mood for features/enhancements** — "Add ...", "Support ...", "Improve ..." - **Bug titles** — prefix with `Bug -` followed by a description of the symptom (e.g., "Bug - Pin data not updating after workflow edit") - **No ticket IDs in titles** — the identifier (AI-1234) is assigned automatically - **No trailing punctuation** #### Description Structure the description using markdown headers. Use the appropriate template: **For bugs:** ```markdown ## Description [Clear explanation of the problem] ## Expected [What should happen] ## Actual [What happens instead] ## Attachments [Screenshots, videos, or screen recordings that illustrate the problem] ## Steps to reproduce 1. [Step-by-step reproduction] ## Additional context - n8n version: [version] - Database: [SQLite/PostgreSQL] - Hosting: [cloud/self-hosted] ``` **For features / enhancements:** ```markdown ## Goal [What this adds and why: the user problem it solves] ## Background [Current state and the gap, plus the technical context needed to plan the work: relevant constraints, prior findings, and links to any related investigation.] ## Scope [Concrete list of what changes. Name the files or areas to create or modify and any existing pattern to follow.] ## Acceptance criteria [Testable outcomes, including automated tests.] ## Out of scope [What this explicitly does not cover] ``` **For tech debt:** ```markdown ## Summary [What technical improvement is needed] ## Current state [What the code/system looks like today and why it's problematic] ## Proposed improvement [What the improved state should look like] ## Motivation [Why this matters — maintainability, performance, developer experience, etc.] ## Scope [What is included / excluded from this work] ``` **For spikes / investigations:** ```markdown ## Goal [What question(s) are we trying to answer] ## Context [Why this investigation is needed now] ## Questions 1. [Specific question to resolve] ## Expected output [What deliverable is expected: RFC, PoC, decision document, path matrix, etc.] ## Acceptance criteria [How we know the spike is done: each question answered, deliverable produced] ``` #### Attachments (Screenshots / Videos) If the user provides screenshots, videos, or screen recordings: - **URLs** — embed directly in the description using markdown image syntax (``) - **File paths** — if the user provides a local file path, ask them to upload it to a hosting service (e.g., GitHub, Imgur) or use the available Linear MCP attachment tool to attach it to the Linear ticket after creation - **Pasted images in conversation** — describe what the image shows in the ticket description and note that a screenshot was provided. You cannot upload binary data directly. Always mention in the description when visual evidence was provided, even if it cannot be directly embedded. #### Priority | Value | Level | When to use | |-------|----------|-------------| | 4 | Low | Nice-to-have, no user impact | | 3 | Normal | Default — standard planned work | | 2 | High | Blocks other work or affects users significantly | | 1 | Urgent | Production-breaking, security vulnerability, data loss | | 0 | None | Not yet assessed | **Guardrails:** - **Default to Normal (3)** unless the user explicitly states otherwise - **Never set Urgent (1)** unless the user explicitly says "urgent", "P0", "production down", or "security vulnerability" - **Never set None (0)** — always make a priority assessment. If unsure, use Normal (3) #### Status **Guardrails:** - **Never create issues in Triage status** — Triage is for externally-reported issues that enter through automated pipelines (GitHub sync, support escalation). Agent-created tickets have known context and should skip triage - **Default to Backlog** — use this when the issue is acknowledged but not yet planned for a sprint - **Use Todo** only when the user indicates the work is planned for the current cycle or should be picked up soon - **Never set In Progress, Review, or Done** at creation time #### Team - **Try to fetch up-to-date team areas of responsibility from Notion** using the available Notion MCP search tool (search for "areas of responsibility" or similar). Use the fetched data to determine the best team for the issue. - **If Notion MCP is unavailable or the lookup fails**, fall back to these common teams: `Engineering` (N8N), `AI`, `NODES`, `Identity & Access` (IAM), `Catalysts` (CAT), `Lifecycle & Governance` (LIGO), `Cloud Platform`, `Docs` (DOC) - **Always ask the user which team** if not obvious from context or the Notion lookup - If the issue is node-specific, it likely belongs to `NODES` - If it involves AI/LangChain nodes, it likely belongs to `AI` #### Labels Apply labels from these groups as appropriate: **Type (pick one):** - `bug` — something is broken - `feature` — net-new capability - `enhancement` — improvement to existing functionality - `tech debt` — internal quality improvement - `spike` — time-boxed investigation - `doc` — documentation-only change **Area (pick if applicable):** - `frontend`, `backend`, `performance`, `testing`, `infra`, `DX`, `Security-Team` **Source (pick if applicable):** - `Internal` — created by team members - `GitHub` — originated from a GitHub issue - `Sentry` — originated from error monitoring - `Zammad` — originated from support **Bucket (pick if applicable):** - Use the relevant feature-area bucket (e.g., `Credentials`, `Canvas/Node`, `RBAC`, `LangChain nodes`, `Form Trigger`, etc.) **Guardrails:** - **Always apply a type label** — every ticket needs at least a type - **Do not apply triage-state labels** (`Triage: Pending`, `Triage: Complete`, etc.) — these are managed by triage automation - **Do not apply release labels** (`n8n@1.36.0`, etc.) — these are managed by release automation - **Do not apply `docs-automation` labels** — these are managed by docs automation #### Estimates Only set an estimate if the user provides one or explicitly asks for one. Use t-shirt sizes: | Size | Value | Approximate effort | |------|-------|--------------------| | XS | 1 | ≤ 1 hour | | S | 2 | ≤ 1 day | | M | 3 | 2–3 days | | L | 4 | 3–5 days | | XL | 5 | ≥ 6 days | ### Creating the Ticket 1. **Gather required fields** — if any are missing, ask the user: - Title - Team - Description (draft one from the user's input using the templates above) 2. **Present a preview** before creating — show the user: - Title - Team - Status - Priority - Labels - Description (abbreviated if long) 3. **Wait for user confirmation** — do not create until the user approves 4. **Create the ticket** using the available Linear MCP issue-creation tool: ``` title: <title> team: <team name> description: <markdown description> priority: <priority number> state: <status name> labels: [<label names>] ``` 5. **Report back** with the issue identifier and URL ### Things to Never Do (Linear) - Never create issues in **Triage** status - Never set **Urgent** priority without explicit user instruction - Never apply **triage-state**, **release**, or **docs-automation** labels - Never set **assignee** unless the user explicitly asks - Never set a **cycle** or **milestone** unless the user explicitly asks - Never create **duplicate issues** — if the user describes something that sounds like it may exist, search first with the available Linear MCP issue-search tool --- ## GitHub Issues ### Prerequisites Verify `gh` CLI is authenticated: `gh auth status` ### Important Context The n8n GitHub issue tracker (`n8n-io/n8n`) is **bug-only**. Feature requests and questions are redirected to the [community forum](https://community.n8n.io). Blank issues are disabled — the bug template must be used. ### Style Guide #### Title - **Sentence case** — same as Linear - **Descriptive of the symptom** — what is broken, not what you want - **No prefixes required** — do not add "Bug:" or "Bug Report:" (the template handles categorization) - **No trailing punctuation** #### Body GitHub issues **must** follow the bug report template structure: ```markdown ### Bug Description [Clear explanation of the bug] ### Steps to Reproduce 1. [Step 1] 2. [Step 2] 3. [Step 3] ### Expected Behavior [What should happen] ### Debug Info [If available — output from Help > About n8n > Copy debug information] ### Operating System [e.g., macOS 14.2, Ubuntu 22.04] ### n8n Version [e.g., 1.72.1] ### Node.js Version [e.g., 20.11.0] ### Database SQLite / PostgreSQL ### Execution Mode main / queue ### Hosting n8n cloud / self hosted ``` **Guardrails:** - **Always include reproduction steps** — issues without them get closed as `closed:incomplete-template` - **Include debug info if available** — this is critical for triage - **Never file feature requests as GitHub issues** — redirect the user to the community forum or suggest creating a Linear ticket instead #### Labels Do **not** manually apply labels when creating GitHub issues. The triage automation handles labeling: - `triage:pending` is auto-applied - `status:in-linear` is auto-applied when synced ### Creating the Issue 1. **Verify it's a bug** — if the user describes a feature request, inform them that GitHub issues are bug-only and suggest alternatives (Linear ticket or community forum) 2. **Draft the issue** using the template above, filling in fields from the user's input 3. **Present a preview** before creating — show the user: - Title - Body (abbreviated if long) - Repository (default: `n8n-io/n8n`) 4. **Wait for user confirmation** 5. **Create the issue** using `gh`: ```bash gh issue create --repo n8n-io/n8n --title "<title>" --body "$(cat <<'EOF' <body content> EOF )" ``` 6. **Report back** with the issue number and URL ### Things to Never Do (GitHub) - Never file **feature requests** as GitHub issues - Never create issues **without reproduction steps** - Never manually apply **labels** — let automation handle it - Never create issues in **repositories other than n8n-io/n8n** unless the user explicitly specifies --- ## Cross-Linking When both a Linear ticket and GitHub issue exist for the same problem: - **Linear → GitHub**: Add the GitHub issue URL as a link attachment on the Linear ticket - **GitHub → Linear**: Add `https://linear.app/n8n/issue/<TICKET-ID>` in the GitHub issue body If the user creates one and mentions the other exists, offer to add the cross-link.