# Linear

> Intelligent work tracking. Automatically classifies issues, gathers codebase context, and creates well-formed Linear tickets. Triggers - linear, issue, track, bug, todo, fix, question, debt.

- Skill: `erikpr1994/linear` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add erikpr1994/linear`
- Raw SKILL.md: https://api.skillmd.com/api/skills/erikpr1994/linear/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: erikpr1994 (https://skillmd.com/u/erikpr1994)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/erikpr1994/linear

---


# 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:

| Signal | Classification |
|--------|----------------|
| "broken", "fails", "error", "crash", "doesn't work" | **Bug** |
| "should we", "what if", "which approach", "decide" | **Question** |
| "need to", "add", "implement", "create", "build" | **Feature** or **TODO** |
| "refactor", "clean up", "improve", "migrate", "deprecated" | **Tech Debt** |
| Multi-step work with phases | **Feature** (hierarchical) |
| Single action, quick fix | **TODO** (flat) |

### 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

```markdown
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:

| Type | Template File | Use When |
|------|---------------|----------|
| Bug | `templates/bug.md` | Something is broken or failing |
| TODO | `templates/todo.md` | Quick, standalone task |
| Question | `templates/question.md` | Decision or discussion needed |
| Tech Debt | `templates/tech-debt.md` | Improvement or refactoring |
| Feature | `templates/feature.md` | Multi-phase hierarchical work |

**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:

```markdown
## 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