// Use when creating a Linear issue from the current coding context, or when the user invokes /linear-issue. Infers team, priority, status, and relationships from conversation context, working directory, and git branch.
| name | linear-issue |
| description | Use when creating a Linear issue from the current coding context, or when the user invokes /linear-issue. Infers team, priority, status, and relationships from conversation context, working directory, and git branch. |
| metadata | {"internal":true} |
Single-pass workflow: gather context, search existing issues, infer fields informed by what's already filed, create issue.
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
Gather all available signals:
/linear-issue — primary signalpackages/ai/ suggests AI-related team)Search existing issues before anything else — what's already filed informs every downstream decision including team selection.
list_issues with keywords extracted from the context (args, conversation summary, branch name)| 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.
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.
Use context from Step 1, search results from Step 2, and team list from Step 3 to determine all fields.
| 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.
| 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 |
Extract or generate a concise title in imperative form, under 80 characters.
Format as markdown. Include:
Infer labels from context and search results:
list_issue_labels with the inferred team to verify labels exist before applying. Only use labels that actually exist in the workspace.Add traceability links back to the development context:
links: [{url, title}] formatAnalyze 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:
Related (relatedTo) — Same area, shared context, but neither blocks the other.
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.
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/...
| 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 |
Generate Stage chapters for the current local git branch and open them in a browser for review.
Use when building or reviewing UI components, pages, or layouts to ensure premium, intentional design that never looks vibe coded
Use when CI is failing on a branch and you need to diagnose failures from GitHub, fix them locally with iterative verification, and re-push clean commits.
Use when a pull request has unresolved review comments that need to be addressed, or when asked to fix PR feedback
Use when a PR is open and the user wants to autonomously monitor and fix PR review comments, CI failures, and rebase conflicts on a recurring loop, or when asked to babysit/iterate on a PR
Use when reviewing code changes against AGENTS.md implementation quality standards, or when asked to do an implementation quality review