linear-ticket-create

Create Linear Ticket (Triage)

Take any incoming material — a WhatsApp/Slack snippet, an emailed client request, a bug description, a screenshot, a voice-note transcript, a half-formed idea — and turn it into a clear, actionable Linear ticket that lands in Triage for the team to prioritise.

The goal is a ticket a developer can pick up cold: the what, the why, where in the code it likely lives, and how to know it's done.

When to use

• User pastes client feedback / a chat snippet and says "make a ticket".
• User shares a screenshot of a bug or a UI change request.
• User describes a bug or feature verbally and wants it documented.
• Any time loose input needs to become a tracked, triage-ready Linear issue.

Sizing: one ticket = one PR

Each ticket is implemented by a single pull request, usually as one branch in a Graphite stack. Size tickets accordingly — a reviewer should be able to digest the resulting PR in one sitting, and the ticket should be shippable on its own (or as one clean layer of a stack).

Decide how to carve the input into tickets:

• Split into separate tickets when the asks are independent, touch different areas/files, could ship at different times, or would otherwise produce one sprawling PR. Aim for tickets that each map to a focused PR — roughly a few files / a self-contained change.
• Keep as one ticket when the changes touch the same code path, must ship atomically to stay correct, or are each too trivial to justify their own PR and review cycle.
• Don't over-split. "Decent size" means cohesive and reviewable, not micro-tickets for one-line edits that naturally belong together. Prefer the smallest set of tickets that each stand as a sensible PR.

When the input yields several stacked tickets, order them by dependency (the order the PRs will stack in Graphite) and link them with blocks / blockedBy on save_issue so the stack order is explicit. Give each ticket enough shared context to be picked up cold.

Workflow

Run step 1 once, decide the ticket breakdown, then run steps 3–8 per ticket.

1. Understand the request

• Read all supplied material: text, chat snippets, images (use the Read tool on image files).
• Identify the distinct asks — one message may contain several.
• Group them into PR-sized tickets per the Sizing section above: split independent asks into separate tickets, keep tightly-coupled changes together. State the proposed breakdown to the user (titles + one-line scope each) before creating, so they can steer the split.
• Note anything ambiguous. If a screenshot is referenced but not attached, say so; don't invent.

2. Gather codebase context (this is what makes the ticket valuable)

• Search the repo for the relevant code so the ticket points the developer to the right place:
  • grep/Glob for the literal wording, label, function, or symptom described.
  • Read the surrounding code to confirm the mechanism and capture file_path:line references.
• Pull out concrete facts the developer would otherwise have to rediscover (constants, the function that produces the text, related variants that share the code path, etc.).
• Do not implement the fix — just document enough that someone could.

3. Pick the team

• mcp__linear__list_teams to resolve the team. This workspace has a single team, Developer Hut (issue prefix DEV-). Pass team: "Developer Hut" when creating.

4. Check available labels and choose relevant ones

• Always call mcp__linear__list_issue_labels with team: "Developer Hut" before creating the issue. Labels change over time — never hardcode the list; read the current set each time.
• Match the input against the available labels and apply every label that genuinely fits. Prefer a type label, a size label, and any topical labels that apply.
• Current Developer Hut labels (verify with the live call — this is just a guide):
  • Type / nature: Bug, Feature, Improvement, Chore, Tests, Content changes, UI, Investigation, Proof Of Concept, Foundational.
  • Size / effort: Small, Medium, Large, Quick Win, High Complexity.
  • Priority / flow: Showstopper (prod-breaking), Support, Need client feedback (use when scope is unconfirmed and you've flagged an open question).
  • Product area: Jackpots, Spin Wheel (apply only if clearly relevant).
• Heuristics: copy/wording/PDF text change → Content changes; visual/layout → UI; defect → Bug; new capability → Feature; small/contained → Small/Quick Win; unconfirmed scope with an open question in the ticket → Need client feedback.
• If nothing fits cleanly, apply no label rather than forcing a wrong one. Do not invent new labels unless the user explicitly asks to create one.

5. Create the issue

Call mcp__linear__save_issue (no id → creates new). Provide:

• team: "Developer Hut"

• title: concise, action-oriented (what changes, where). Not a restatement of the symptom.

• priority: 1=Urgent, 2=High, 3=Medium, 4=Low. Default to 3 (Medium) unless the input signals urgency (client blocked, production bug → higher).

• labels: array of label names chosen in step 4 (e.g. ["Content changes", "Small"]).

• description: Markdown using literal newlines, not \n. Scope it to this ticket's single PR. Recommended structure:

  Source (channel + date, e.g. "Client request, WhatsApp, 29 May 2026").
  
  ## What
  
  The change this PR makes, quoting the client's exact wording in a blockquote when wording
  matters. (If this ticket bundles a couple of tightly-coupled sub-changes, list them here.)
  
  ## Implementation notes
  
  Where it lives in the code: `path/to/file.ts` (function, line refs) and any facts gathered.
  Flag related variants / open scope questions.
  
  ## Acceptance criteria
  
  - [ ] Verifiable outcome 1
  - [ ] Verifiable outcome 2
  

• For a stack, set blocks / blockedBy to encode the PR order, and reference the sibling ticket(s) by identifier in the description so the stack is navigable.

• Capture the returned identifier (e.g. DEV-541) and url for the next steps and the summary.

6. Attach images (if any were supplied)

Linear image upload is a 3-step signed-upload flow. Get the exact byte size first: stat -c '%s' <file> and the MIME via file --mime-type -b <file>.

1. mcp__linear__prepare_attachment_upload with issue, filename, contentType, size (exact bytes), and a descriptive title. Returns assetUrl + uploadRequest.

2. PUT the raw bytes to uploadRequest.url within 60 seconds. Send every header from uploadRequest.headers verbatim (casing included) or you get HTTP 403:

   curl -s -o /dev/null -w "%{http_code}" -X PUT --data-binary @<file> \
     -H "content-type: <mime>" \
     -H "cache-control: public, max-age=31536000" \
     -H "x-goog-content-length-range: <size>,<size>" \
     -H 'Content-Disposition: attachment; filename="<filename>"' \
     "<uploadRequest.url>"
   

   Expect 200. Do not transform or base64-encode the file.

3. mcp__linear__create_attachment_from_upload with issue, the assetUrl, and title.

7. Move to Triage

• mcp__linear__save_issue with id: <identifier> and state: "Triage".

8. Report back

• Give the user each ticket's identifier, title, and clickable url.
• For a stack, list the tickets in PR order and note how they're linked.
• Note any open questions you flagged and any referenced-but-missing attachments.

Principles

• One ticket = one PR — size every ticket to a single, cohesive, reviewable pull request (one Graphite stack layer). Split independent asks; keep coupled changes together; don't micro-split. Link stacked tickets with blocks/blockedBy in PR order.
• Quote the client verbatim where exact wording is the point (copy changes, error text).
• Always add code context — file_path:line references and gathered facts; never guess.
• Surface, don't fabricate — if something is referenced but absent, say so in the ticket.
• Label from the live list — always read current labels via list_issue_labels and apply what genuinely fits; never hardcode labels or invent new ones.
• Triage is the destination — created tickets go to Triage for the team to prioritise, not straight into a sprint, unless the user says otherwise.