Add To Backlog

Add issues to Linear Backlog from user input. Interprets free-form descriptions into well-structured issues.

Purpose

• Convert user's free-form ideas into structured Backlog issues
• Parse multiple items from a single input
• Reference conversation context or investigation findings
• Write problem-focused descriptions (what, not how)
• Include implementation hints for plan-backlog to use later

Input Modes

The skill supports three input modes based on $ARGUMENTS:

Mode 1: Direct Description

User provides task descriptions directly:

/add-to-backlog Add rate limiting to API routes, also need to handle image upload errors gracefully, and the barcode scanner fails on blurry images

Mode 2: From Conversation

User references the current conversation:

/add-to-backlog from conversation - add the three issues we discussed
/add-to-backlog add all the improvements mentioned above
/add-to-backlog track the bug we just found

Mode 3: From Investigation

User references findings from investigate skill:

/add-to-backlog from investigation findings
/add-to-backlog add the issues found by investigate

Mode 4: From Sentry

User references Sentry crash/error reports:

/add-to-backlog the Sentry issues we found
/add-to-backlog track the Sentry crash

When creating issues from Sentry findings, include the Sentry issue URL in the description under a **Sentry Issue:** section so downstream planning skills can track it.

Pre-flight

Verify Linear MCP: Call mcp__linear__list_teams. If unavailable, STOP and tell the user: "Linear MCP is not connected. Run /mcp to reconnect, then re-run this skill."

Discover team name: Read CLAUDE.md and look for LINEAR INTEGRATION section. Extract the team name from patterns like:

• "Team: 'ProjectName'"
• "Team: ProjectName"

If CLAUDE.md doesn't have a LINEAR INTEGRATION section, call mcp__linear__list_teams to discover the team name dynamically.

Store the discovered team name in a variable for use throughout the skill.

Workflow

1. Parse input - Understand what to add based on $ARGUMENTS
2. Identify items - Separate multiple items from the input
3. Check existing Backlog - Avoid duplicates
4. Draft issues - Write problem-focused descriptions
5. Create in Linear - Add to Backlog state

Issue Structure

Each issue should have:

Title

• Clear, concise problem statement
• Action-oriented: "Rate limiting missing on API routes", "Barcode scanner fails on blurry images"
• NO solution in title

Description

Structure:

**Problem:**
[What is wrong or missing - 1-2 sentences]

**Sentry Issue:** (include only if originating from Sentry)
[Sentry issue URL] — [event count] events, [user count] users, release [version]

**Context:**
[Where this occurs, affected files/areas - brief]

**Impact:**
[Why this matters - user impact, data quality, errors]

**Implementation Hints:** (optional)
[Suggestions for plan-backlog, patterns to follow, related code]

Labels

Map to Linear labels based on issue type:

Priority

Assess based on impact:

Parsing Input

Direct Descriptions

Look for natural separators:

• "also", "and also", "additionally"
• Numbered lists: "1.", "2.", etc.
• Bullet points: "-", "*"
• Commas followed by action verbs
• Complete sentences as separate items

Example:

"Add rate limiting, also handle upload errors, and fix the blurry barcode bug"

--> Three issues:

1. Rate limiting missing on API routes
2. Image upload error handling incomplete
3. Barcode scanner fails on blurry images

Conversation References

When user says "from conversation" or similar:

1. Review the conversation above
2. Identify discussed problems, improvements, or bugs
3. Extract actionable items

Investigation References

When user mentions investigation findings:

1. Look for investigation output in conversation
2. Extract issues, errors, or recommendations found
3. Convert findings into actionable issues

Duplicate Detection

Before creating, check existing Backlog:

1. Query mcp__linear__list_issues with team=[discovered team name], state=Backlog, includeArchived=false
2. Compare proposed issues against existing titles/descriptions
3. If similar issue exists:
   • Skip the duplicate automatically

Creating Issues

Use mcp__linear__create_issue for each issue (skip duplicates automatically):

team: [Discovered team name]
state: "Backlog"
title: "[Issue title]"
description: "**Problem:**\n[description]\n\n**Context:**\n[context]\n\n**Impact:**\n[impact]\n\n**Implementation Hints:**\n[hints]"
priority: [1|2|3|4]
labels: [Mapped label]

Writing Good Issues

DO:

• Focus on the problem, not the solution
• Include context about where/when the issue occurs
• Explain impact to help prioritization
• Add implementation hints for plan-backlog
• Reference related files or code if known

DON'T:

• Include step-by-step implementation
• Write the solution in the description
• Use vague language ("improve this", "fix the thing")
• Create issues without clear problem statement

Good Example:

**Problem:**
API routes have no rate limiting, allowing unlimited requests from any client.

**Context:**
Affects all routes under app/api/. Public endpoints like /api/scan and /api/food are most vulnerable.

**Impact:**
Service can be overwhelmed by automated requests, causing downtime for all users.

**Implementation Hints:**
- Consider upstash/ratelimit or next-rate-limit
- See existing middleware pattern in middleware.ts
- Should return 429 with Retry-After header

Bad Example:

Add rate limiting. Use upstash ratelimit library. Create a middleware that checks IP address and limits to 100 requests per minute. Return 429 status code.

Error Handling

Rules

• Problem-focused - Describe what's wrong, not how to fix
• Include hints - Help plan-backlog with implementation suggestions
• Check duplicates - Avoid cluttering backlog
• One problem per issue - Split combined issues

Termination

After creating issues, output:

Created X issues in Linear Backlog:

- PROJ-123: [Title] (Label, Priority)
- PROJ-124: [Title] (Label, Priority)
- PROJ-125: [Title] (Label, Priority)

Skipped:
- [Description] - duplicate of PROJ-12

Next steps:
- Review issues in Linear Backlog
- Use `plan-backlog` to create implementation plans
- Use `plan-backlog PROJ-123` to plan a specific issue

Do not ask follow-up questions. Do not offer to plan or implement.