Creating Linear Issues

Single-pass workflow: gather context, search existing issues, infer fields informed by what's already filed, create issue.

Workflow

1. CONTEXT  → Gather signals: args, conversation, directory, git branch
2. SEARCH   → list_issues broadly to find duplicates, related issues, and inform inference
3. TEAMS    → list_teams to get available teams (informed by search results)
4. INFER    → Determine title, description, team, priority, status, labels, project, links, relationships
5. CREATE   → create_issue with inferred fields + relationships
6. REPORT   → Display created issue summary

Step 1: CONTEXT

Gather all available signals:

• Args: Description provided after /linear-issue — primary signal
• Conversation: If no args, summarize current discussion as issue description
• Directory: Current working directory/package (e.g. packages/ai/ suggests AI-related team)
• Git branch: Branch name often encodes feature/bug context

Step 2: SEARCH

Search existing issues before anything else — what's already filed informs every downstream decision including team selection.

1. Call list_issues with keywords extracted from the context (args, conversation summary, branch name)
2. Search broadly across teams — no team filter yet, since search results may reveal the correct team
3. Collect results into three buckets:

Bucket	Criteria	Used for
Duplicates	Same intent and scope as new issue	Stop and warn user
Related	Same area, overlapping context	Relationship inference in Step 4
Informative	Same team/area but different scope	Team/priority/status inference in Step 4

If a strong duplicate is found (same intent and scope): STOP. Do not proceed to Step 4. Report the existing issue:

Possible duplicate found — did not create.
Existing: TEAM-99 "Add retry logic to extraction agent"
Status: In Progress  |  Assignee: @charles
URL: https://linear.app/...

Reply if you still want to create a new issue.

Step 3: TEAMS

Call list_teams → get all workspace teams

Use search results from Step 2 to guide matching — if related issues belong to a specific team, that's strong evidence for the correct team.

Step 4: INFER

Use context from Step 1, search results from Step 2, and team list from Step 3 to determine all fields.

Team

• Primary signal: which team do related/informative issues belong to?
• Secondary signal: directory/package name fuzzy-matched against team names from Step 3
• Fallback: broadest team

Priority

Signal	Priority
"ASAP", "urgent", "blocking", "broken", "critical", "P0", "production down"	1 (Urgent)
"soon", "important", "next few days", "high priority", "P1"	2 (High)
No urgency signal / default	3 (Normal)
"low priority", "nice to have", "when we get to it", "P3", "minor"	4 (Low)

Also consider: what priority are related issues set to? Match the neighborhood.

Status

Signal	Status
"needs discussion", "RFC", "should we", "not sure if", "explore", "maybe"	Backlog
Default / clear actionable task	Todo
"I'm working on", "currently", "in progress", "started"	In Progress

Title

Extract or generate a concise title in imperative form, under 80 characters.

Description

Format as markdown. Include:

• What the issue is about
• Context: branch name, relevant file/package, conversation summary
• Any acceptance criteria apparent from context

Labels

Infer labels from context and search results:

• From description: "bug"/"broken"/"error" → bug label, "feature"/"add"/"new" → feature label, "refactor"/"tech debt"/"cleanup" → tech-debt label
• From related issues: If related issues share a common label, apply it to the new issue too
• Call list_issue_labels with the inferred team to verify labels exist before applying. Only use labels that actually exist in the workspace.

Project

• If related issues from Step 3 belong to a project, add the new issue to the same project
• If the conversation or args explicitly mention a project name, use that
• Otherwise, leave unset

Links

Add traceability links back to the development context:

• If on a branch with an open PR, link to the PR URL
• If the conversation references a specific file or commit, link to it on GitHub
• Use links: [{url, title}] format

Relationships

Analyze related issues from Step 3:

Sub-issue (parentId) — New issue is a specific task within a broader existing issue. Example: "fix retry in extraction agent" is a sub-issue of "improve chapter generation reliability"

Parent — New issue encompasses existing smaller issues. After creating, call update_issue on each child to set their parentId.

Blocking / Blocked-by (blocks / blockedBy) — Use when:

• Explicit dependency language: "this blocks X", "can't do Y until this is done"
• Technical dependency: "migrate DB schema" blocks "add new column"

Related (relatedTo) — Same area, shared context, but neither blocks the other.

Step 5: CREATE

Call create_issue with:

Field	Value
title	Inferred title (imperative, <80 chars)
description	Markdown description with context
team	Matched team name
priority	Numeric: 1=Urgent, 2=High, 3=Normal, 4=Low
state	Status name: "Backlog", "Todo", "In Progress"
labels	Array of label names inferred from context
project	Project name (if related issues share a project)
links	Array of {url, title} linking to PR/branch/commit
parentId	Parent issue identifier (if sub-issue)
blocks	Array of issue identifiers this blocks
blockedBy	Array of issue identifiers blocking this
relatedTo	Array of related issue identifiers

If this issue is a parent of existing issues, after creation call update_issue on each child to set parentId.

Step 6: REPORT

Created: TEAM-123 "Add retry logic to chapter generation"
Team: Product  |  Priority: Normal  |  Status: Todo
Labels: bug, ai-pipeline  |  Project: Chapter Gen V2
Parent: TEAM-100 "Improve chapter generation reliability"
Related: TEAM-98 "Audit error handling in AI pipeline"
Links: PR #42 "feat: add retry logic"
URL: https://linear.app/...

Common Mistakes

Mistake	Fix
Inferring fields before searching existing issues	Always search first — existing issues inform team, priority, and relationships
Creating without checking duplicates	Step 3 catches duplicates before any inference work
Setting priority too high by default	Default is Normal (3), only escalate with clear urgency signals
Guessing team instead of looking up	Always call list_teams and match against actual teams
Searching only within one team	Search broadly first — related issues may be in a different team
Forgetting to set relationships	Check related bucket from Step 3 for parent/blocking/related
Using IDs instead of names for state	create_issue accepts state names directly ("Backlog", "Todo")
Skipping description context	Always include branch, directory, and conversation context
Creating parent without updating children	After creating a parent issue, call update_issue on children
Applying labels that don't exist	Call list_issue_labels to verify labels exist before using them
Ignoring project from related issues	If related issues share a project, add the new issue to it
Not linking back to PR/branch	Always check for an open PR with gh pr view and link it