---
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`](https://github.com/org/repo/blob/abc123/shared/api/updateParams.ts)
- Function: [`useMyHook`](https://github.com/org/repo/blob/abc123/vite/src/hooks/useMyHook.ts#L42)
- Line range: [`EditHeader`](https://github.com/org/repo/blob/abc123/vite/src/EditHeader.tsx#L47-L70)

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

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