linear-ticket

---

name: linear-ticket description: Refine rough engineering thoughts into structured Linear tickets with GitHub permalinks

What I do

Refine rough engineering thoughts into structured, actionable Linear tickets.

Important: Use Linear MCP

This skill creates ACTUAL Linear tickets using the Linear MCP server. Do not just write markdown files - use the create_issue tool from the user-Linear MCP server to create real tickets.

Before creating:

1. Use list_teams to find the appropriate team
2. Use list_projects to find the relevant project (if any)
3. Use create_issue with the formatted ticket content as the description

Process

1. Parse Intent - Identify core objective and constraints
2. Search Codebase - Find relevant files, patterns, existing implementations, related tests, reusable utilities
3. Get GitHub Permalinks - Run git remote get-url origin and git rev-parse HEAD to build permalinks
4. Structure & Output - Format as ticket below
5. Create in Linear - Use the Linear MCP create_issue tool to create the actual ticket
6. Flag Gaps - Call out ambiguities, edge cases, missing considerations, questions

GitHub Permalinks

All file and function references must be clickable GitHub permalinks. Don't use raw paths.

Format: [filename.ts](https://github.com/org/repo/blob/{commit_sha}/path/to/file.ts#L{line})

Examples:

• File: updateParams.ts
• Function: useMyHook
• Line range: EditHeader

To find line numbers, use grep: grep -n "export function useMyHook" path/to/file.ts

⚠️ Gotcha: Use paths relative to the git root, NOT the full filesystem path. Run git rev-parse --show-toplevel to find the git root. If the workspace is /Users/me/project/.conductor/cayenne/ and that's the git root, then vite/src/hooks/useMyHook.ts is correct, NOT .conductor/cayenne/vite/src/hooks/useMyHook.ts.

Ticket Format

Copy## Summary
[One line - what needs to be done]

## Context
[Why this is needed - 2-3 sentences max]

## Plan

### Phase 1: [Phase Name]

**Why**: [Explain WHY this phase is needed and point to relevant files in the codebase]

1. [Step with specific file/function]
2. [Step]

> **🎨 Design Challenge** (optional): [If there are design decisions to explore, add as a blockquote challenge within the phase - NOT as a separate phase]

---

### Phase 2: [Phase Name]

**Why**: [Context for this phase]

3. [Step]
4. [Step]

---

**Testing**
- [ ] [Test case]

**Questions**
- [ ] [Any clarifications needed before starting]

Note: Don't include a separate "Implementation Notes" section - all file/function references should be inlined with GitHub permalinks in the relevant phase.

Guidelines

• Be concise - No fluff. Every word earns its place.
• Use GitHub permalinks - All file/function references must be clickable links, not raw paths
• Don't assume - List unknowns as questions
• Follow patterns - Find how similar things are done, suggest reuse
• Think full lifecycle - Create, update, delete, error states
• Each phase needs a Why - Explain the reasoning and point to relevant codebase files
• No redundant phases - Consolidate similar work into single phases
• Design discussions are footnotes - Put design challenges as blockquotes within implementation phases, not as separate phases
• Inline references - Don't have a separate "Implementation Notes" section; link files/functions where they're mentioned