Workflow for researching a Linear issue, gathering all relevant context, synthesizing key insights, and posting a structured summary back to the issue as a comment.
Use this workflow when: • an issue requires investigation, clarification, or context gathering • the goal is to understand the problem deeply before implementation • you are asked to research, analyze, or summarize an issue
Issue format example: L-114
Produce a high-quality research summary by: 1. collecting all relevant context 2. analyzing and organizing the information 3. extracting key insights and open questions 4. posting a structured summary to the Linear issue 5. creating a shared reference for the team to understand the issue and guide future work
Before doing any analysis: • Retrieve the issue: • title • description • status • Retrieve all comments • Identify any: • linked issues • referenced PRs • external context (docs, APIs, tools mentioned)
Goal: Build a complete picture of the issue from all available sources
If the issue is not self-contained: • Search the codebase for: • related modules • relevant functions • prior implementations • Identify: • similar past issues • existing patterns or constraints
Do NOT modify code at this stage.
Process the collected information: • Summarize the problem in your own words • Identify: • core objective • constraints • assumptions • Extract: • key technical points • relevant system behavior • Detect: • inconsistencies or unclear areas • missing information
Organize findings into a clear structure.
The output must include:
Rules: • Keep it concise but complete • Prefer bullet points over long paragraphs • Findings must distinguish between facts, inferences, and speculation
Add a comment to the issue containing: • the structured research summary • no raw logs or unprocessed data • clear formatting (markdown)
The comment should: • help others quickly understand the issue • serve as a shared reference for future work
If a prior research comment exists, update it instead of creating a new one
If information is incomplete: • explicitly list unknowns under Open Questions • do NOT invent missing details
If conflicting information exists: • highlight the conflict • do not resolve it silently
- Do NOT implement code in this workflow
- Do NOT open PRs
- Do NOT change issue status unless explicitly requested
- Focus only on understanding and communication
- If a research summary already exists: update or refine it instead of duplicating