Auto-diagnose Linear bug reports with Perplexity AI research

Build an agent workflow that auto-triages new Linear bug reports by doing a first-pass web investigation and posting a diagnostic comment, so the assigned engineer walks in with context instead of a blank issue.

Trigger: a Linear webhook on issue creation, filtered to issues that carry the 'bug' label (the label name should be configurable). Linear supports outbound webhooks for issue.create events, so use that rather than polling.

What the agent should do on each trigger:

1. Read the new Linear issue (title, description, labels, attachments) using Linear's Get Issue operation. Extract whatever the reporter actually included: the error message or exception class, the stack trace, the reproduction steps, the affected version or environment, and any vendor or library names. If the issue body has no concrete error string and no reproduction steps, stop here and do not comment. Vague reports get skipped rather than hallucinated answers.

2. Call Perplexity AI's Create Chat Completion operation with the sonar-reasoning-pro model. Reasoning is important here because the agent needs to correlate symptoms across multiple sources, so don't downgrade the model. In the prompt to Perplexity, paste the extracted error details and ask for matching GitHub issues, Stack Overflow threads, vendor changelogs and release notes, and CVE or security advisories that describe the same symptoms. Use Perplexity's domain filter feature to bias the search toward github.com, stackoverflow.com, and the documentation domains of any libraries or vendors named in the bug. Ask Perplexity to return citations.

3. From Perplexity's response, assemble a short diagnostic with three parts: two or three candidate root causes ranked by how well the symptoms match, links to anyone who has reported the same symptoms (with one-line summaries of what they hit), and any documented workarounds or fixes. Keep it tight: this is a head start, not a final verdict. Always include inline citation links from Perplexity's search_results so the engineer can verify.

4. Post the diagnostic back on the original Linear issue using Linear's Add Comment to Issue operation. Tag the triage owner at the top of the comment (the triage owner should be a configurable Linear user; resolve their user id with List Users if needed). Format the comment in Markdown with a clear 'Auto-triage diagnostic' header so it's obviously machine-written and engineers know what to expect.

Guardrails: never modify the original issue body, labels, assignee, or status — comments only. Never invent a root cause that isn't supported by a cited source. If Perplexity returns nothing useful, post a short 'no matching prior reports found' comment instead of fabricating leads. Keep the whole comment under roughly 400 words so it stays scannable in Linear.

Configuration the workflow should expose to the user: the Linear label that triggers triage (default 'bug'), the Linear user to tag as triage owner, and an optional list of trusted documentation domains to bias the Perplexity search toward.

Additional information

What does this prompt do?

Watches Linear for new issues tagged as bugs and pulls out the error message, stack trace, and reproduction steps.
Searches the public web for matching reports, vendor changelogs, advisories, and Stack Overflow threads using Perplexity AI.
Posts a clean first-pass diagnostic back on the Linear issue with two or three candidate root causes, links to anyone who hit the same symptoms, and any known workarounds.
Tags the triage owner in the comment so the right person sees it immediately, and skips vague reports that lack a concrete error string.

What do I need to use this?

A Linear workspace with permission to read issues and add comments.
A Perplexity AI account with API credits on file.
A name (or Linear user) for the triage owner you want tagged on each diagnostic.

How can I customize it?

Change which Linear label triggers the workflow (for example, only run on issues tagged 'p0-bug' or 'customer-blocking').
Adjust the research scope. Bias the search toward your own framework, language, or vendor docs by listing trusted domains.
Swap or rotate who gets tagged as triage owner, or skip tagging entirely on low-priority bugs.

Frequently asked questions

What happens if the bug report is too vague to research?

If the issue has no concrete error string, stack trace, or reproduction steps, the agent skips it instead of guessing. You will not get a noisy comment with hallucinated root causes.

Will the agent actually fix the bug?

No. It writes a first-pass diagnostic with candidate root causes and links to prior reports. A human engineer still owns the actual fix. Think of it as a head start, not a replacement.

Can I limit which Linear teams or projects this runs on?

Yes. The workflow runs on issues that carry a specific label, and you can scope further by team, project, or priority when you customize it.

How fresh are the sources Perplexity cites?

Perplexity searches the live web at the moment the bug is filed, so changelogs, advisories, and forum threads are current. Every cited link is included inline in the Linear comment so engineers can verify.

Does the workflow modify the original bug report?

No. It only adds a new comment. The original issue body, labels, assignee, and status are left untouched.