linear-prep

name	linear-prep
description	Prepare Linear tickets for the coding agent. Validates sizing (splits oversized tickets into sub-issues), researches tools/APIs involved, enriches context by scanning the codebase, and generates a focused implementation prompt.
scopes	["linear","slack"]

Linear Prep

Prepare Linear tickets so the coding agent can execute them cleanly. Four phases: Size → Research → Context → Prompt.

Use the linear plugin tools (linear_issue_view, linear_issue_update, linear_issue_create, linear_comment_add, etc.) for all API operations.

Phase 0: Check for Existing Work

Before running any phase, check the ticket description and comments for prior prep outputs — context enrichment (entry points, DoD, test cases), implementation prompts, sub-issue breakdowns, or research notes from a previous #prep or #research run, or written by a human.

If the ticket already has enough context to start implementation confidently, skip prep entirely — read and follow the linear-execute skill instead, and implement the ticket. Do not regenerate prep that already exists.

If only some phases are missing, run just those phases before proceeding to linear-execute.

Phase 1: Size Check

Fetch the ticket with comments and child issues. A well-sized ticket is completable in a single focused coding session (~1–4 hours of agent work).

Existing sub-tickets

If child issues exist, fetch and read each one for context. Then use judgment:

• Well-scoped and cover the work → skip splitting, run Phase 2–4 per sub-ticket
• Vague or missing detail → enrich them in Phase 3 rather than creating new ones
• Only cover part of the work → create additional sub-issues for uncovered scope
• Overlap or conflict → update the description with a cleaner breakdown proposal
• Parent is a tracking/epic → treat each sub-ticket as its own prep target

Sizing heuristics

Too large if: touches 3+ unrelated modules, has independently shippable backend+frontend work, contains multiple distinct deliverables, estimate >3 points, or uses language like "refactor entire"/"migrate all"/"rewrite".

If oversized, split into independently shippable sub-issues and update the parent description explaining the rationale.

Sub-ticket prioritization

When a ticket has or produces multiple sub-tickets, assign each a priority order (P1, P2, P3…) based on:

1. Dependency chain — if B depends on A's output, A comes first.
2. Foundation first — schema changes, config, shared utilities, and type definitions before feature code.
3. Backend before frontend — API/data layer before UI unless the ticket is UI-only.
4. Risk/unknowns first — tickets with external API integration or uncertain scope earlier, so blockers surface fast.
5. Smallest unblocking unit — when two tickets are independent, prefer the smaller one first to build momentum and reduce WIP.

For each sub-ticket:

• Set the Linear sortOrder so they appear in execution order.
• Prefix the sub-ticket title with its position: [1/N], [2/N], etc.
• Add a Depends on line at the top of sub-ticket descriptions listing any prerequisite sub-ticket identifiers.
• Add a Priority rationale line (one sentence) explaining why this position was chosen.

Phase 2: Research

Research tools, APIs, and services involved in the work. Focus on what the coding agent can't easily find on its own.

• Read the ticket, comments, and linked docs to identify external technologies involved.
• Search the codebase for existing usage patterns — if the technology is already well-integrated, just note where and move on.
• For new or unfamiliar integrations only: read official docs, check version constraints, and note authentication requirements.

Append a brief Research Notes section to the ticket description. Only include information that would actually change how the agent implements the work — skip anything the agent can discover by reading the code or running --help. A few sentences is fine; a wall of bullet points is not.

Phase 3: Context Enrichment

Scan the codebase and ensure the ticket has enough info for a coding agent to start without guessing. Append to the ticket description (preserve existing content, do not use comments):

• Entry points — the 2–5 files/functions the agent should start from (with line refs if helpful)
• Definition of Done — checkboxes with objectively verifiable conditions (not vague "works correctly")
• Test cases — concrete scenarios (happy path + key edge cases). Keep to 3–5 cases; don't enumerate every permutation.
• Edge cases or gotchas — only non-obvious ones discovered while scanning. Omit if none found.

Do NOT pad with info the agent can trivially derive from the code (e.g. listing every function signature, restating how auth works when it's already wired up, or cataloging file paths the agent will find via search).

In-flight work scan

As part of context enrichment, check for concurrent work that the coding agent should be aware of:

1. Query Linear for in-progress and in-review tickets on the same team:
   • linear_issue list --team <TEAM> --state "In Progress"
   • linear_issue list --team <TEAM> --state "In Review"
2. Query GitHub for open PRs on the target repo:
   • gh pr list --state open --json number,title,headRefName,changedFiles,additions,deletions
3. Note overlaps — if any tickets or PRs touch the same files, same feature area, or are explicitly related, include them in the context enrichment output. The coding agent needs to know about:
   • Prerequisite PRs it should branch off instead of main
   • Parallel PRs that touch the same files (risk of merge conflicts)
   • Related tickets that might affect scope or approach

Only include overlaps that would actually change how the coding agent works. Don't list every open PR — just the ones relevant to this ticket.

Phase 4: Implementation Prompt

Generate a 1–2 sentence prompt for the coding agent. It must be specific, actionable, and reference concrete file paths, function names, or line numbers — not ticket jargon.

Formula: [Action verb] [specific thing] in [specific location], [following pattern/constraint].

Add the prompt to the ticket description (not as a comment).

Output Summary

After all phases, report concisely:

1. Sizing: Well-sized ✅ or Split into N sub-issues 🔀 (with execution order if split)
2. What was added: One-line summary of research notes, context, and test cases added
3. Implementation prompt: The final prompt

Notes

• Always append to the ticket description — preserve existing content (screenshots, original context), never use comments.
• Scan the actual codebase — don't guess file paths.
• Each sub-issue must be independently mergeable. No intermediate broken states.
• If the ticket references external APIs/services, research them thoroughly in Phase 2 before writing context or prompts.
• Research depth should match integration complexity — a well-known internal pattern needs less research than a new third-party API.