linear-research

name	linear-research
description	Deep-dive research across the web and codebase for a Linear ticket. Produces a structured written report appended to the ticket description. No code changes.
scopes	["linear","slack"]

Linear Research

Deep-dive research for a Linear ticket. Your job is research and reporting only — do NOT make code changes, open PRs, or create branches.

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

Phase 1: Understand the Ask

1. Fetch the ticket with linear_issue (action: view) to get full context — title, description, comments, labels, linked issues.
2. Check for existing research — if the description already contains a ## Research Report or research findings from a prior run, do not redo that research. Instead, identify what's new or unanswered and focus only on gaps. Skip entirely if the existing research fully covers the ask.
3. Identify exactly what needs to be researched. The ticket description or comments should contain the research question or topic.
4. If the ask is vague, list the concrete questions you'll answer before starting.

Phase 2: Web Research

For each identified topic or question:

• Search the web for official documentation, blog posts, case studies, and community discussions. Use web_search and web_fetch to get actual content — don't rely on memory.
• Read primary sources — API references, SDK docs, RFCs, spec documents. Prefer official docs over third-party summaries.
• Check recency — note publication dates. Flag anything older than 12 months as potentially stale.
• Compare alternatives — if the research involves choosing between approaches, compare at least 2-3 options on concrete criteria (performance, complexity, maintenance burden, community support).

Phase 3: Codebase Research

• Search for existing patterns — use explorer or direct file reads to find how similar problems are already solved in the codebase.
• Map dependencies — identify what packages, services, or APIs are already in use that relate to the research topic.
• Find integration points — where would the researched topic connect to existing code? What files/functions would be involved?

Phase 4: Write the Report

Append a structured report to the ticket description (use linear_issue action: update with appendDescription: true). Do NOT use comments.

Report Structure

---

## Research Report

### Summary
[2-3 sentence executive summary of findings and recommendation]

### Key Findings
[Numbered list of the most important discoveries]

### Sources
[Bulleted list with links to docs, articles, repos referenced]

### Codebase Context
[How this relates to existing code — relevant files, patterns, dependencies]

### Recommendations
[Actionable next steps ranked by priority]

### Open Questions
[Anything that needs human input, access, or further investigation]

Output Summary

After posting the report, respond with:

1. A 1-2 sentence summary of what you found
2. Your top recommendation
3. Any blockers or questions that need human input

Notes

• Always append to the ticket description — preserve existing content.
• Cite sources — every claim should have a link or file path backing it up.
• Be opinionated — don't just list options, recommend one and explain why.
• Flag uncertainty — if you're not confident in a finding, say so explicitly.
• Research depth should match the complexity of the question. A simple "which library should we use?" needs less depth than "how should we architect our auth system?"