Linear Issue Handler

Linear Issue Handler Skill

Overview

This skill provides a comprehensive workflow for managing Linear issues using the linearis CLI tool. It handles issue creation, status tracking, commenting, and file downloads with clear decision trees based on your preferences.

Foundation

Tools & Access

• Primary Tool: linearis CLI (accessed via Bash)
• Authentication: Uses ~/.linear_api_token file
• Reference Format: Issues use format ABC-<number> (e.g., RDS-2455)

Key Principle

Linear is the single source of truth for project management. All significant work should be reflected in the appropriate issue.

Decision Trees & Your Preferences

1. Updating Issue Descriptions

When to Update Directly (No Ask Needed):

• ✅ Changing task checkbox status (e.g., - [ ] → - [x])
• ✅ Updating status indicators (Pending → In Progress)
• ✅ Adding timestamps or minor factual updates
• ✅ Correcting obvious typos

When to Ask First (Before Updating):

• ❓ Rewriting section content or descriptions
• ❓ Reorganizing the issue structure
• ❓ Changing requirements or acceptance criteria
• ❓ Removing or significantly altering original intent

2. Reading Issue State Before Work

Always Read the Issue When:

• Starting work on a specific ticket you were assigned
• Picking up a ticket for the first time
• Unclear context from user instructions

Don't Need to Read When:

• User is giving you a direct, clear task ("Fix the bug in X file")
• Working on code without ticket reference
• Issue is just for documentation purposes

Example:

User: "Work on RDS-2455"
You: Read the issue first to understand current state, dependencies, blockers

3. Creating New Issues

Ask User First (Context-Dependent) For:

• Complex features or major changes
• Issues that might affect multiple teams
• Anything where project assignment is unclear
• Issues blocking other work

Create Directly For:

• Minor bugs discovered during work
• Small follow-up tasks clearly related to current work
• Documentation issues
• Obvious technical debt or code cleanup
• Use the parent ticket's project when creating sub-issues

Example - Ask First:

You: "This work requires architectural changes. Should I create an issue, or
would this be better handled in planning? Would you like this in PROJECT-X
or a different project?"

Example - Create Directly:

You: "I noticed a typo in the error message. Creating RDS-2500 as a follow-up."
User: (Reviews the new issue you created)

4. Updating Issue State

Always Ask Before:

• Changing state to "In Progress"
• Changing state to "Done" or marking complete
• Changing state to "Cancelled" or "Blocked"
• Any state change that affects others' work visibility

Why Ask: State changes affect workflow visibility for your team. Getting explicit approval prevents surprises.

Example:

You: "I've completed the work for RDS-2455. Should I mark it as 'Done',
or would you prefer to do that?"
User: "Yes, mark it done."
You: Updates state via linearis

Common Workflows

Workflow 1: Starting Work on an Assigned Issue

# You're told: "Work on RDS-2455"

# Step 1: Read the issue
linearis issues read RDS-2455

# Step 2: Review current state, check for embeds (screenshots, docs)
# If embeds present:
linearis embeds download

# Step 3: Check for blockers, dependencies, or sub-tasks
# Verify nothing has changed since assignment

# Step 4: Begin work, understanding full context
# -> This is especially important if you haven't seen the ticket before

Workflow 2: Reporting Progress During Work

For small progress updates (no decision needed):

# You're actively working, making progress on a task
# Add a comment to show what you've done

linearis comments create RDS-2455 --body "## Progress Update

- [x] Completed component refactoring
- [x] Added unit tests
- [ ] Integration tests (in progress)

Next: Testing with real data"

For major updates that need decision:

# You hit a blocker or need to change approach

linearis comments create RDS-2455 --body "## Blocker Encountered

Found that the current API doesn't support filtering by X.

Options:
1. Modify API endpoint (bigger change)
2. Filter client-side (less efficient)
3. Create new endpoint (longer timeline)

Need guidance on approach."

# Then wait for user input before proceeding

Workflow 3: Updating Task Status in Description

Scenario: You're making progress on a task list in the issue description.

# Issue description currently has:
# - [ ] Task 1: Implement component
# - [ ] Task 2: Add tests
# - [ ] Task 3: Documentation

# After completing Task 1, you can update directly:
linearis issues update RDS-2455 --description "
## Tasks
- [x] Task 1: Implement component ✅ Completed
- [ ] Task 2: Add tests
- [ ] Task 3: Documentation
"

# OR comment about the change:
linearis comments create RDS-2455 --body "✅ Completed: Task 1 - Implement component"

Best Practice: If the issue author will see the change, add a comment too so they get notified.

Workflow 4: Creating a New Issue

Step 1: Determine if you need to ask

• Is this a complex/major feature? → Ask first
• Is this a minor follow-up to current work? → Create directly
• Unsure? → Ask

Step 2: Gather information

Title: Brief, descriptive
Project: Usually parent ticket's project (or ask user)
Description: Context, why it's needed, any acceptance criteria

Step 3: Create using linearis

linearis issues create \
  --title "Brief description of issue" \
  --project RDS \
  --description "Detailed context and acceptance criteria"

# Example:
linearis issues create \
  --title "Fix typo in error message" \
  --project RDS \
  --description "The error message in validateInput() has a typo: 'occured' should be 'occurred'"

Step 4: Report back

You: "Created RDS-2500 as a follow-up. Here's the link: [Linear URL]"

Workflow 5: Creating a Sub-Issue

For issues that are part of a larger ticket:

# If RDS-2455 is parent, and you need to create RDS-2456 as a sub-task

# Use the parent's project (RDS in this case)
linearis issues create \
  --title "Sub-task: Implement specific part" \
  --project RDS \
  --parent RDS-2455 \
  --description "This is a sub-task of RDS-2455 focusing on..."

# Report:
You: "Created RDS-2456 as a sub-task of RDS-2455"

Workflow 6: Downloading Embedded Files

When an issue has attachments:

# Check what embeds are available
linearis issues read RDS-2455
# Look for "embeds" array with download URLs

# Download the files
linearis embeds download RDS-2455

# Files are saved locally for reference
# Use the content to inform your work

Workflow Examples in Context

Example 1: Mid-Project Discovery

You: Working on RDS-2455, find that the API is missing a field needed

Step 1: Read the issue (just to confirm scope)
linearis issues read RDS-2455

Step 2: Add a comment with finding
linearis comments create RDS-2455 --body "## Discovery: API Missing Field

The endpoint returns X but doesn't include Y. Current code expects Y.

Options:
1. Backend adds field (bigger scope)
2. I request it separately (more calls)

Which should I do?"

Step 3: Wait for guidance before proceeding

Example 2: Completing a Task List

Issue has:
- [ ] Build component
- [ ] Add tests
- [ ] Update docs

You finish building the component.

Option A - Direct update (for small checkboxes):
linearis comments create RDS-2455 --body "✅ Component build complete"

Option B - Update description:
// Update the issue description to mark checkbox done
// Then optionally comment for notification

Best: Do both for visibility

Example 3: Discovery of Follow-Up Work

You: "During RDS-2455, I notice several similar components could be refactored"

Decision tree:
- Is this major refactoring? → Ask user first
- Is this a small cleanup? → Create sub-issue directly

You: "Created RDS-2456 as a follow-up for component consolidation"

Then add comment to parent:
linearis comments create RDS-2455 --body "See RDS-2456 for related refactoring opportunity"

Tool Reference

Create a Comment

linearis comments create <issueId> --body "Comment text here"

• <issueId>: Can be UUID or ABC-123 format
• --body: The comment text (supports Markdown)

Read Issue Details

linearis issues read <issueId>

• Returns current issue state, description, embeds array
• Shows file URLs and expiration times

Download Embeds

linearis embeds download <issueId>

• Downloads files attached to issue
• Saves locally for reference

Create Issue

linearis issues create \
  --title "Title" \
  --project PROJECT \
  --description "Details"

Referencing Issues

In code/commit messages, always use format: ABC-123 Example: git commit -m "Fix bug described in RDS-2455"

Best Practices

1. Always Reference by Number

• Use RDS-2455 not "the issue about that thing"
• Helps others quickly find the context
• Makes it searchable

2. Prompt Status Updates

• If task status changes, update promptly
• Don't wait until the very end
• This keeps the team informed of progress

3. Comment for Significant Changes

• Small checkbox updates: Can just update description
• Major findings/blockers: Add a comment for notification
• When in doubt: Add a comment

4. Separate Code Review from Issue Tracking

• Issue comments: High-level progress, blockers, decisions
• Code review: Details in PR/MR comments
• Don't duplicate information

5. Ask Before State Changes

• Even if obvious work is done, ask before marking "Done"
• This prevents accidental state changes affecting others
• Builds confidence in the workflow

6. Link Related Issues

• When creating follow-ups: "Created ABC-200 for related work"
• When a ticket depends on another: "Blocked by ABC-199 until..."
• Comment with cross-references for context

7. Provide Context in New Issues

Include in description:

• Why is this needed?
• What should the outcome be?
• Any acceptance criteria?
• Links to related issues

Quick Decision Flowchart

Do you need to update something about an issue?
│
├─ Update description/checklist?
│  ├─ Just checking boxes or status? → Update freely (no ask)
│  └─ Rewriting content? → Ask first
│
├─ Add a comment/status report?
│  └─ Always OK (they're just notifications)
│
├─ Change issue state (In Progress/Done)?
│  └─ Always ask first (impacts team visibility)
│
├─ Create a new issue?
│  ├─ Complex/major? → Ask first
│  └─ Minor/obvious follow-up? → Create directly
│
└─ Download files from issue?
   └─ Use `linearis embeds download` to retrieve

When to Reach Out

If you're unsure about any of these scenarios:

• Issue creation complexity level
• Whether something needs a state change
• If a description rewrite is justified
• Anything blocking your work

→ Ask the user. Better to confirm than to assume.

Skill Version

• Last Updated: November 13, 2025
• Based on preferences: Linear issue handling workflow (context-dependent creation, ask-first state changes, free description checkbox updates)