Linear Issue Management

Iron Law: CONTEXT IS KING. Every issue must have enough context for anyone to understand and act on it.

How This Skill Works

This skill is autonomous. When invoked:

1. Classify - Determine issue type from context (don't ask the user)
2. Investigate - Use explore agent to gather codebase context
3. Create - Build a well-formed Linear issue with full context
4. Confirm - Show the user what will be created

The user should NOT need to specify "bug" or "todo" - the AI infers this.

Issue Classification

Automatically determine issue type from the request:

Classification Logic

Is something broken/failing?
├── YES → Bug
└── NO → Is it a decision/discussion?
    ├── YES → Question
    └── NO → Is it improvement to existing code?
        ├── YES → Tech Debt
        └── NO → Is it multi-phase work?
            ├── YES → Feature (hierarchical)
            └── NO → TODO (single issue)

Do NOT ask the user what type it is. Infer from context.

Context Gathering

Before creating any issue, investigate the codebase to add relevant context.

Step 1: Dispatch Explore Agent

Task: @Explore (subagent_type: "Explore")

Investigate context for: "{user's request}"

Find:
1. Relevant files that will be affected
2. Existing patterns in the codebase
3. Related code or similar implementations
4. Potential dependencies or blockers

Return:
- File paths with line numbers
- Code snippets showing current state
- Pattern observations

Step 2: Extract Context

From explore results, extract:

• Files involved: Exact paths to relevant files
• Current state: What exists now (for bugs/debt)
• Patterns: How similar things are done in the codebase
• Dependencies: What this work depends on or affects

Step 3: Enrich Issue

Add gathered context to the issue description automatically.

Issue Templates

Templates are stored in external files to reduce context size. Read the appropriate template when creating an issue:

To use: Read the template file for the classified issue type, then fill in the template with gathered context.

Hierarchical Feature Planning

For complex, multi-phase work, create a hierarchy. See templates/feature.md for full templates.

ENG-100: [Feature] {Feature Name}
├── ENG-101: [Phase 1] {Phase Name}
│   ├── ENG-102: {Atomic task}
│   └── ENG-103: {Atomic task}
├── ENG-104: [Phase 2] {Phase Name}
│   └── ...
└── ENG-105: [Phase N] Verification
    └── ...

Key principle: Every leaf task must be immediately executable with a single unit of work.

CRITICAL: Use parentId for Sub-Issues

# 1. Create root feature → returns { id: "uuid-100", identifier: "ENG-100" }
# 2. Create phases with parentId:
mcp__linear-server__create_issue(parentId: "uuid-100", ...)  → ENG-101
# 3. Create tasks with parentId:
mcp__linear-server__create_issue(parentId: "uuid-101", ...)  → ENG-102

DO NOT use relatedTo - that creates "related" not parent-child!

The Workflow

When the user mentions work that should be tracked:

1. Analyze Request

Read the user's message and determine:

• What type of issue is this? (Don't ask - infer)
• What area of the codebase is involved?
• Is this single-task or multi-phase?

2. Investigate Codebase

Dispatch explore agent:

Task: @Explore
Find context for: "{summary of request}"

Look for:
- Files that would be affected
- How similar things are implemented
- Patterns to follow
- Dependencies

3. Build Issue

Using the appropriate template:

• Fill in user's description
• Add auto-gathered context
• Include relevant code snippets
• Add file paths with line numbers
• Set appropriate labels and priority

4. Confirm with User

Show the proposed issue:

## Proposed Linear Issue

**Type:** {Bug/TODO/Question/Tech Debt/Feature}
**Title:** {title}

{Full issue body}

---

Create this issue? I can also adjust before creating.

5. Create in Linear

Use Linear MCP to create the issue:

• Create issue with full context
• For features: create hierarchy
• Return issue ID/URL

Workflow Example

User says: "The login form breaks when I use special characters"

Step 1 - Classify: Signals "breaks" → Bug

Step 2 - Investigate:

Task: @Explore - Find: login form, input validation, special character handling

Returns: src/components/LoginForm.tsx:45, src/utils/validation.ts:12, pattern using sanitizeInput()

Step 3 - Build: Read templates/bug.md, fill with gathered context

Step 4 - Confirm: Show proposed issue to user

Step 5 - Create: Use Linear MCP to create issue

See individual template files for full output examples.

Quick Reference

CLASSIFY     -> Infer type from context (never ask user)
INVESTIGATE  -> Use explore agent for codebase context
ENRICH       -> Add file paths, code snippets, patterns
CONFIRM      -> Show user before creating
CREATE       -> Use Linear MCP with full context

BUG          -> Something broken, needs fixing
TODO         -> Quick standalone task
QUESTION     -> Decision or discussion needed
TECH DEBT    -> Improvement for later
FEATURE      -> Multi-phase hierarchical work

Red Flags - STOP

• Creating issue without investigating codebase first
• Asking user "is this a bug or a TODO?"
• Issue without file paths or code context
• Vague descriptions that lack specificity
• Missing verification commands

Integration

Uses:

• Explore agent - Codebase investigation
• Linear MCP - Issue creation

Pairs with:

• tdd - Test-first for fixes
• session - Track Linear progress in sessions
• verification - Document verification results