reviewstage 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.
- Call
list_issueswith keywords extracted from the context (args, conversation summary, branch name) - Search broadly across teams — no team filter yet, since search results may reveal the correct team
- 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_labelswith 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 |