meaningful-linear-issues

Meaningful Linear issues

A good issue is not just a good description — that's the easy half. The half agents skip is the metadata that makes Linear actually work as a planning tool: estimates feed cycle velocity, labels feed breakdowns, milestones feed roadmaps, the project feeds everything. Those fields are optional in the API, so agents leave them blank and the user has to come back and ask again.

Flip the default: metadata is opt-OUT, not opt-in. Resolve and fill it before calling save_issue, in one pass — propose concrete values, don't omit.

Cardinal rule: never guess the project

The single worst failure is dropping an issue into the wrong/random project. Resolve the project in this order — stop at the first that's certain:

1. Context — the issue's repo/area maps to a known project; the user named it; a sibling issue you're relating to has one.
2. Confirm — call list_projects and match by name; if one clearly fits, state which and proceed.
3. Ask — if it's still ambiguous, ask the user which project rather than picking one. A missing project is recoverable; a wrong one quietly pollutes the wrong roadmap.

Never pass a project you inferred from vibes. Team is required too — usually unambiguous from the project, but resolve it the same way.

The one-pass workflow

1. Discover what's available (only what you don't already know): projects, the team's label taxonomy, milestones, the current cycle, assignable users.
2. Draft the issue with every applicable field filled (checklist below).
3. Create with one save_issue call. If anything was genuinely a judgment call (estimate, priority), state the values you chose so the user can correct one — that's still one pass, not "I left them blank, ask me again."

Create vs. backfill — mind the id

Same checklist, two save_issue modes — don't conflate them:

• Create (new issue): save_issue with no id. Fill everything below.
• Backfill (existing bare issue): save_issue WITH its id — update, don't create. Omitting the id here would make a duplicate. get_issue first if you need to see what's already set, then pass only the fields you're adding. labels replaces the whole set — include existing labels alongside the new ones. Relations (blocks / blockedBy / relatedTo) are append-only — adding one won't drop existing links (use removeBlocks / removeBlockedBy / removeRelatedTo to remove). Other fields you don't pass are left untouched.