Create linear ticket

Linear Ticket Creator

This skill creates Linear tickets with configurable defaults using the Linear MCP tools. Tickets are typically created while working on in-progress uncommitted changes and are always tied to one or more PRs.

Default Configuration

All tickets created with this skill automatically include:

Field	Source
Team	config.yaml → linear.team
Assignee	config.yaml → linear.default_assignee
Status	config.yaml → linear.default_status
Priority	config.yaml → linear.default_priority

Automatic Labels

IMPORTANT: Always pass label IDs (not names) to the MCP tool. The create_issue tool silently drops label names it cannot resolve. Use the IDs from the Label Reference table below.

Labels are determined automatically based on context. Always include all three label types:

1. Platform Label (Required)

Determined by the repository being worked on. Map your repos to platform labels in config.yaml → linear.labels.platforms.

To detect the repo:

git remote get-url origin

Look up the repo name in your config to find the matching platform label ID.

2. Task Type Label (Required)

Infer from the nature of the change:

Change Type	Task Type Label
Fixing broken behavior, errors, crashes	Task Type → Bug
Adding new functionality, UI, features	Task Type → Feature
Optimizations, speed improvements, reducing load	Task Type → Performance

Inference heuristics:

• Bug: Commit messages with "fix", "bug", "broken", "error", "crash", "issue"
• Performance: Messages with "optimize", "performance", "speed", "slow", "memory", "cache"
• Feature: Everything else (new files, new functions, new UI components)

Title Convention

Keep titles:

• Short and simple - but explicit enough that most people understand the task
• Self-contained - should convey what's being done at a glance
• No prefixes - don't use fix:, feat:, etc. Labels handle categorization

Good examples:

• "Session timeout during file upload"
• "Add bulk device assignment to org settings"
• "Device list pagination breaks with 500+ devices"

Workflow

1. Gather Context and Detect Labels

# Detect repository for Platform label
git remote get-url origin

# Check current branch and uncommitted changes
git status
git diff --stat
git diff  # Review actual changes for Task Type inference
git log -1 --oneline  # Recent commit context

2. Build Comprehensive Description

Include relevant sections based on context. Only include sections that apply - omit empty or irrelevant sections.

## Summary
[High-level summary of what this change does and why]

## Root Cause
[What was the underlying cause? - ONLY for bug fixes, omit for features]

## Technical Details
[Implementation details - what files changed, what approach was taken, any architectural decisions]

## QA Steps

### Automated Coverage

- [ ] Unit tests added/updated: [Yes/No - list test files]
- [ ] Integration tests: [Yes/No]
- [ ] E2E tests: [Yes/No]

### Manual Testing Required

1. [Step-by-step verification steps]
2. [Expected outcomes]

### Regression Considerations

- [Areas that could be affected by this change]
- [Related features to verify still work]

## Feature Flag
[ONLY include if feature flagged]
- Flag name: `[flag_name]`

## Related Links
[ONLY include if links exist]
- TDD: [link]
- Loom: [link]
- Discord: [link]

3. Create the Ticket

Create the issue with all auto-detected labels:

mcp__plugin_linear_linear__create_issue:
  title: "[Short, explicit title]"
  team: "[from config.yaml → linear.team]"
  assignee: "[from config.yaml → linear.default_assignee]"
  labels:
    - "[platform label ID from config.yaml → linear.labels.platforms]"
    - "[task type label ID from config.yaml → linear.labels.task_types]"
  state: "[from config.yaml → linear.default_status]"
  priority: "[from config.yaml → linear.default_priority]"
  description: "[Description built from context above]"

4. Report Ticket and Recommend PR Commands

After creating the ticket, if there are unstaged/uncommitted changes, recommend commands to create a branch and PR.

Check for changes:

git status
git diff --stat

If changes exist, provide PR creation commands with gt (Graphite):

Branch Naming Convention

Format: {type}/{issue-identifier}-{slugified-title}

• feature/ - new user-visible functionality
• bugfix/ - fixing broken behavior
• chore/ - non-user-visible tasks (package updates, docs, version bumps)
• refactor/ - code changes with no functional changes

Example: bugfix/PROJ-456-session-timeout-during-file-upload

Graphite

# Create branch and commit in one step
gt create {type}/{issue-identifier}-{slugified-title} -m "{issue-identifier} {title}"

# Example:
gt create bugfix/PROJ-456-session-timeout-during-upload -m "PROJ-456 Session timeout causes logout during file upload"

5. Link PR to Issue

After the PR is created, update the issue with the PR link:

mcp__plugin_linear_linear__update_issue:
  id: "[issue-id-from-step-3]"
  links:
    - url: "https://github.com/{owner}/{repo}/pull/123"
      title: "PR #123: [PR title]"

Label Reference

Configure your label IDs in config.yaml. To find your label IDs:

# List all labels for your team using the Linear MCP tool:
mcp__plugin_linear_linear__list_issue_labels with team: "YourTeam"

Copy the IDs into your config.yaml under the appropriate category (linear.labels.platforms, linear.labels.task_types, etc.).

Context Gathering Checklist

Always include:

• Platform Label: Based on repo (git remote get-url origin) and config.yaml
• Task Type Label: Bug, Feature, or Performance (inferred from changes) and config.yaml
• Summary: What does this change accomplish at a high level?
• Technical Details: Implementation approach, files changed, patterns used
• Test Coverage: Are there automated tests? What's not covered?
• Manual QA: What must a human verify before release?
• Regression Risk: What else might this change affect?

Include when applicable:

• Root Cause: What was actually broken and why? (bugs only)
• Feature Flag: Is this behind a flag? Which one? (if flagged)
• Related Links: TDD docs, Loom recordings, Discord threads (if they exist)

Available Linear MCP Tools

Issue Management

• mcp__plugin_linear_linear__create_issue - Create new issues (primary tool)
• mcp__plugin_linear_linear__update_issue - Update existing issues (for linking PRs)
• mcp__plugin_linear_linear__get_issue - Get issue details by ID
• mcp__plugin_linear_linear__list_issues - List/search issues

Supporting Tools

• mcp__plugin_linear_linear__create_comment - Add comments to issues
• mcp__plugin_linear_linear__list_comments - List comments on an issue
• mcp__plugin_linear_linear__list_issue_labels - List available labels (for looking up Web Platform labels)
• mcp__plugin_linear_linear__list_projects - List projects
• mcp__plugin_linear_linear__list_cycles - List cycles for a team

Example Ticket

Repository: your-frontend-repo Labels: Platform → Web, Web Platform → Frontend, Task Type → Bug

Title: Session timeout causes logout during file upload

Description:

## Summary
Users were being unexpectedly logged out during large file uploads because the session timeout wasn't being extended during active uploads.

## Root Cause
The session keepalive ping was only sent on user interaction events (clicks, keypresses), but file uploads run in the background without triggering these events. Long uploads would exceed the 15-minute session timeout.

## Technical Details
- Added a heartbeat mechanism to the upload service that pings `/api/session/keepalive` every 5 minutes during active uploads
- Modified `src/services/upload.ts` and `src/api/session.ts`
- Used existing `SessionManager` pattern for consistency

## QA Steps

### Automated Coverage
- [x] Unit tests added: `upload.service.spec.ts`
- [x] Integration tests: `session-keepalive.integration.spec.ts`

### Manual Testing Required
1. Start a large file upload (>100MB recommended)
2. Wait 20+ minutes without interacting with the page
3. Verify upload completes successfully
4. Verify user remains logged in

### Regression Considerations
- Verify normal session timeout still works when idle (no uploads)
- Check session invalidation on explicit logout still immediate

## Feature Flag
- Flag name: `UPLOAD_SESSION_KEEPALIVE`

## Related Links
- Discord: https://discord.com/channels/.../thread-about-logout-bug