SKILL.md

Linear Issue Management

Before using Linear workflows, search for linear MCP tools. If not found, treat as not installed.

PR Creation with Linear Issues

A PR that fixes a Linear issue has two separate jobs to do, and both matter:

**Fixes LOBE-xxx in the PR body** — Linear watches GitHub for these magic keywords and auto-links the PR and auto-closes the issue on merge. This is the machine-readable side.

A completion comment on the Linear issue — gives the reviewer/PM/teammate landing in Linear a human-readable summary of what changed and why, without forcing them to click through to GitHub and read a diff.

If you only do step 1, Linear watchers (often non-engineers) hit the issue and see no context. So pair PR creation with the Linear comment as part of the same task — finish both before considering the work done.

Workflow

Retrieve issue details before starting: mcp__linear-server__get_issue

Read images — issue descriptions often contain screenshots with critical context (mockups, error states, before/after). Use mcp__linear-server__extract_images so you actually see them; reading raw markdown alone misses what the reporter was looking at.

Check for sub-issues: mcp__linear-server__list_issues with parentId filter

Mark as In Progress at the moment you start planning or implementing — this signals to teammates the issue is owned, so they don't double-pick it up.

Update issue status when completing: mcp__linear-server__update_issue

Add completion comment (see [format below](#completion-comment-format))

Creating Issues

When creating issues with mcp__linear-server__create_issue, add the claude code label. Reason: the label is how the team filters/audits AI-generated issues; without it those issues vanish into the general backlog and the team loses visibility into AI contribution patterns.

Language

Match the issue language to the conversation that produced it — if you're discussing in 中文，write the issue in 中文；if discussing in English, write it in English. Reason: the issue is a continuation of the conversation, and forcing a language switch creates translation friction for the collaborator who started the thread.

Specifics:

中文 conversation → 中文 body; technical terms (file paths, identifiers, library names, commands, error messages) stay in English.

English conversation → English body.

Code blocks, file paths, and quoted strings always stay in their original form regardless of surrounding language.

This applies equally to updates — when editing an existing issue (description and titles), preserve the language of the conversation that triggered the edit; don't switch the issue language mid-refactor.

Creating Sub-issue Trees

When breaking a parent issue into a tree of sub-issues (e.g., task decomposition for LOBE-xxx), follow these rules — they work around real limitations of the Linear MCP tools.

1. Prefix titles with an ordering index

The Linear Sub-issues panel orders children by sortOrder, which defaults to newest-first (most recently created appears on top). Neither parallel nor serial creation produces the intended top-to-bottom reading order, and the MCP save_issue tool does **not expose a sortOrder parameter** — you can't set order at create time.

Workaround: encode execution order in the title itself:

[1]     [db]       add schema fields

[2]     [db]       new table + repository

[3]     [service]  business logic layer

[4]     [api]      REST endpoints

[4.1]   [sdk]      client SDK wrapper

[4.1.1] [app]      consumer integration

[4.1.2] [app]      UI surface

[4.2]   [ui]       dashboard page

Even when the panel shuffles, the reader can mentally reconstruct the dependency graph at a glance. Dotted numbering [n.m.k] should mirror the parent-child nesting so the index and the tree agree.

2. Nest sub-issues by logical parent-child, not flat under the root

Linear supports unlimited sub-issue depth. A flat list of 8+ siblings under one root is hard to scan. Group by main-subordinate logic:

Core service → its SDK → SDK consumers

Don't create a sibling when a child is more accurate

Use parentId: "LOBE-xxxx" at creation (or save_issue to move). Moving an issue's parent does not disturb its blockedBy relations.

3. Sub-issue creation order is dictated by blockedBy

blockedBy requires the blocker to exist first (you need its LOBE-id). So:

Topologically sort the DAG — leaves (no deps) first, roots last

Create issues with zero deps in the first wave

Create dependent issues only after collecting the blocker IDs from prior responses

blockedBy is append-only; passing it again does not overwrite — safe to re-run

4. Don't waste rounds trying to parallelize

MCP tool calls in a single message look parallel but execute sequentially on the server, and you still need blocker IDs from earlier responses. Just issue calls in dependency order; optimizing for parallelism gains nothing here.

5. Keep each sub-issue description self-contained

Each sub-issue should state:

Goal (1–2 lines)

Key files to touch

Concrete changes / acceptance criteria

Dependencies (link to blocker issues by LOBE-xxxx)

Validation steps

The implementer may open only the sub-issue, not the parent — don't rely on context that lives only in the parent description.

Completion Comment Format

Each completed issue gets a comment summarizing the work, so reviewers and future readers don't have to reconstruct it from the PR diff:

## Changes Summary

- **Feature**: Brief description of what was implemented

- **Files Changed**: List key files modified

- **PR**: #xxx or PR URL

### Key Changes

- Change 1

- Change 2

- ...

This gives team visibility, code-review context, and a paper trail for future reference.

PR Association

When creating PRs for Linear issues, include magic keywords in the PR body:

Fixes LOBE-123

Closes LOBE-123

Resolves LOBE-123

These trigger Linear's auto-link + auto-close on merge.

Per-Issue Completion Rule

When working on multiple issues, close out each one before starting the next — don't batch all the Linear updates to the end. Batching is where comments get forgotten and issues stay stuck in "In Progress" days after the PR shipped.

For each issue:

Complete implementation

Run bun run type-check

Run related tests

Create PR if needed

Update status to "In Review" (not "Done" — "Done" is for after the PR merges)

Add the completion comment

Move to the next issue

linear