Kata Linear

Linear Ticket Lifecycle

This skill wraps the general /linear skill with structured start/next/end workflows. Always invoke the /linear skill for the actual MCP calls when using this skill.

Determining the Mode

Parse the user's request to determine which workflow to run:

If ambiguous, ask.

Identifying the Project

1. Check the current working directory's AGENTS.md for a Linear project reference.
2. If not found, call list_projects and ask the user which project to use.
3. Cache the project name for the remainder of the session and update AGENTS.md for future reference.

Mode: Next

Find the next actionable issue.

1. Query list_issues for the project with state Todo.
2. If results exist, present them. The first Todo issue is the recommended next pick.
3. If no Todo issues, resolve from blocking relations: a. Query list_issues for the project with state Backlog. b. For each Backlog issue, call get_issue with includeRelations: true. c. Find issues whose blockedBy entries are all Done (or have no blockers).
4. If multiple candidates, determine if they can be run concurrently in isolated worktrees in two ways: a. Re-check Linear tickets (scope + blockers); then b. Inspect the current code boundaries they would touch to see if there’s hidden coupling.
5. Present unblocked issues as candidates, including concurrency guidance/risks.
6. If the project has Linear documents (execution model, workflow contract), fetch them with list_documents and get_document to understand pillar/phase ordering.

Mode: Start

Step 1 — Validate the issue

1. Call get_issue for the requested issue with includeRelations: true.
2. Check every entry in blockedBy. For each blocker, confirm its status is Done.
3. If any blocker is not Done, stop and report which blockers remain open.

Step 2 — Move to In Progress

1. Call update_issue to set state to In Progress.

Step 3 — Load context

1. Read the issue description for references to specs, mocks, docs, or design files.
2. Read Linear documents (execution model, workflow contract) for project-specific guidance.
3. Read relevant spec files, mock images, or design references found in steps 1 and 2.
4. Check existing source code in the areas the issue will touch.

Step 4 — Create feature branch

1. Use the gitBranchName field from the issue response as the branch name.
2. Create the branch from the main branch.

Step 5 — Summarize

Present to the user:

• Issue title and acceptance criteria
• Blocker status (all clear)
• Context loaded (specs, mocks, relevant code)
• Branch name created
• Any project-specific workflow reminders from AGENTS.md (e.g., TDD mandate)

Mode: Complete

Step 1 — Gather evidence

Gather evidence:

• PR link or branch with changes
• Test results (unit and/or E2E)
• Screenshots/video or spec-state references demonstrating acceptance criteria

If a PR already exists on the current branch, detect it with gh pr view.

Step 2 — Validate completion gate

Check if the project's CLAUDE.md or Linear workflow contract defines a hard gate. Common gates:

• Referenced spec states/interactions are verified
• Evidence links are attached (tests, screenshots, or traceable PR notes)
• Gap analysis items are either closed or split into follow-up issues
• Acceptance criteria are all marked as verified in the issue checklist
• Definition of Done checklist is completed

If evidence is insufficient, list what's missing and stop.

Step 3 — Attach evidence to the issue & PR

1. Call create_comment on the issue with a structured evidence summary:

   ## Completion Evidence
   - PR: [link]
   - Tests: [pass/fail summary]
   - Acceptance coverage: [which criteria verified]
   - Screenshots/video: [if applicable]
   

2. Add the same summary as a comment on the PR.

Step 4 — Promote next in chain

1. Call get_issue with includeRelations: true on the completed issue.
2. For each issue in the blocks list: a. Call get_issue with includeRelations: true on that downstream issue. b. Check if ALL of its blockedBy entries are now Done. c. If yes, call update_issue to move it to Todo. d. Report which issue was promoted.

(Note: the current ticket will automatically move to Done when the PR is merged).

Step 5 — Summarize

Present:

• Issue marked Done with evidence link
• Which downstream issue(s) were promoted to Todo
• Suggested next action

Important Reminders

• Always pass includeRelations: true when calling get_issue to see blocking dependencies.
• Always reference the attached media as the source of truth for design specs and mocks.