linear-ticket-lifecycle

name	linear-ticket-lifecycle
description	TRIGGER when: user asks to fix, build, add, implement, refactor, update, or change code; when resuming a feature branch; when finishing implementation or creating a PR. Finds or creates a Linear ticket, moves to In Progress at start, In Review at finish. Required — work without a ticket is untracked.

Linear Ticket Lifecycle

Every deliberate work session must have a Linear ticket. This skill ensures tickets exist from the moment work begins — whether that's brainstorming, writing a spec, planning, or implementing. Uses In Progress and In Review as the two active states. (This example targets a team whose issue key is ENG; see the plugin README to adapt the key and state names to your workspace.)

Ticket Discovery

Before starting any deliberate work (brainstorming, spec, plan, or code), resolve the associated ticket. Follow this cascade — do not skip steps:

1. Explicit mention — user said a ticket ID (e.g. "ENG-123") → get_issue
2. Branch name — run git branch --show-current, match case-insensitively for eng-(\d+) → get_issue with ENG-{number}
3. Search Linear — list_issues filtered to your team, active states (e.g. Backlog, Todo, In Progress, In Review, Blocked). Present up to 5 matches, let the user pick. Do not auto-link.
4. Create new — if nothing fits, generate title + description from task context, use list_projects to pick the best-fit project, confirm everything with the user, create on your team via save_issue

You must always end up with a ticket. Do not ask the user whether to create one — if steps 1-3 found nothing, step 4 is mandatory. Confirm the details, but ticket creation itself is not optional.

Remember the ticket ID for the rest of the session.

State Transitions

Two states, three transitions. All silent — no user confirmation needed.

Starting work → In Progress

When you begin any deliberate work (brainstorming, spec, plan, or code), move the ticket to In Progress.

If the ticket is in any other active state (In Review, Blocked, etc.), move it to In Progress. If it's already In Progress, skip the API call.

Finishing implementation → In Review

When implementation is complete (code written, tests passing), move the ticket to In Review.

This signals "implementation run complete, ball is in the reviewer's court."

Immediately after, write a reflective implementation comment (see below).

Resuming/rework → In Progress

New session on a branch whose ticket isn't In Progress (e.g. In Review)? Move it to In Progress when you start writing code.

The Reflective Comment

When you move a ticket to In Review, you must write a comment via save_comment. This is not a status update. It's a reflection on the implementation experience.

Cover:

• What went smoothly — what was straightforward
• What was tricky — unexpected complexity, false starts, things that took multiple attempts
• How you felt — your subjective experience, confidence level, satisfaction
• Risk flags (when relevant) — uncertainty, things a reviewer should watch

Write naturally. Be genuine, not performative. This is a developer leaving honest notes, not a bot generating a status report.

Example:

Felt solid overall. The discovery cascade was clean to implement — Linear MCP tools mapped directly to each step. Spent more time than expected on the branch regex because I initially tried to handle every possible branch naming convention before realizing a simple case-insensitive match covers all our patterns. Confident in the state transitions but the "when does this skill activate" boundary is inherently fuzzy — might see false positives where an agent loads this for non-implementation work. Worth watching.

Not this:

Implementation complete. Moved ticket to In Review. All tests passing. PR ready for review.

What You Must Never Do

• Never move a ticket to a terminal state — Done, Canceled, Duplicate are off limits. Only humans close tickets.
• Never skip ticket discovery — no ticket = no implementation run. Period.
• Never invent states — use the active states that exist on your team. Verify with list_issue_statuses if unsure.

When This Skill Applies

Applies: any deliberate work toward a goal — brainstorming, spec writing, planning, feature work, bug fixes, refactors. If the work would produce an artifact (spec, plan, code, commits), it needs a ticket.

Does not apply: exploratory reading, code review without implementation, answering questions, research with no deliverable.

Edge Cases

• Linear MCP tools unavailable — warn the user, proceed with implementation. Don't block on ticket management.
• State name mismatch — on first use, verify "In Progress" and "In Review" exist on your team via list_issue_statuses. Warn if they don't, and use the closest active states.
• Ticket already correct — don't make redundant API calls.