How SpecSource's AI Agent Sources Detailed Specifications

SpecSource researches Linear issues and produces detailed, context-rich specifications. This post walks through what actually happens during an agent run — the pipeline, the context sources, and the deduplication system.

The Trigger

Everything starts with a Linear issue. When a new issue is created in your Linear workspace — or on a schedule — SpecSource picks it up and begins its investigation. The goal: enrich that issue with a detailed specification containing everything an engineer (or AI coding agent) needs to start fixing the bug immediately.

Step 1: Read the Linear Issue

The agent starts by analyzing the Linear issue. It extracts:

• The issue title and description
• Labels, priority, and project context
• Any comments or linked issues
• The team and assignee context

This is the starting point, but a bare ticket isn't enough to write a good specification.

Step 2: Check Sentry for Related Errors

If Sentry is connected, the agent searches for errors related to the issue. It looks for matching error messages, stack traces, and affected endpoints. From Sentry it gathers:

• The exception type and stack trace with file paths and line numbers
• Error frequency — how many times it's occurred and how many users are affected
• Environment information and breadcrumbs
• Tags and context metadata

This error data adds critical technical detail to the issue.

Step 3: Gather Code Context from GitHub

Using the file paths from the stack trace, the agent queries your connected GitHub repository. It retrieves:

• The source code around the failing lines — not just the single line, but enough surrounding context to understand the function and its callers
• Recent commits that modified the affected files — if the file was changed in the last few deploys, those diffs are often the root cause
• Related files — imports, shared modules, and test files that cover the affected code

This step transforms a stack trace from "line 47 of checkout.ts threw a TypeError" into "here's the function, here's what it does, and here's what changed two days ago."

Step 4: Search Slack for Team Context

Production errors rarely happen in silence. Often someone has already noticed the issue, discussed it in Slack, or shared a workaround. The agent searches your connected Slack workspace for messages related to the error — matching on error messages, affected endpoints, or relevant keywords.

If a teammate posted "seeing weird 500s on the checkout endpoint" three hours ago with a thread of investigation, that context goes into the specification.

Step 5: Check Linear for Duplicates

This is one of the most important steps. Before writing a new specification, the agent checks whether the issue already exists in your Linear workspace.

Simple string matching doesn't work well here. The same root cause can manifest as different error messages, and different engineers describe the same problem in different ways. SpecSource uses embedding-based semantic matching to solve this.

Here's how it works:

1. The agent generates a vector embedding of the current error's context — a numerical representation that captures the semantic meaning of the issue
2. This embedding is compared against embeddings of existing Linear issues using cosine similarity
3. If a match exceeds the similarity threshold, the agent links to the existing issue instead of creating a duplicate
4. Near-matches are flagged as potentially related, giving the team visibility into issue clusters

This approach catches duplicates that keyword matching would miss. An error titled "NullPointerException in PaymentProcessor" and an existing issue called "Checkout fails when payment method is undefined" are semantically similar even though they share almost no words.

Step 6: Write the Specification

With all context gathered, the agent assembles the specification. A typical SpecSource specification includes:

• Issue summary: A clear description of what needs fixing
• Error details: Exception type, stack trace, and frequency from Sentry (if connected)
• Code context: The affected source code and recent changes
• Team context: Related Slack discussions, if any
• Related issues: Links to similar existing issues

The agent uses an LLM to synthesize all gathered context into a coherent, well-structured specification — not a raw dump of data, but a narrative that an engineer can read and understand in 30 seconds.

Step 7: Enrich the Linear Issue

The finished specification is written back to the original Linear issue, enriching it with all the gathered context. Labels and priority can be updated based on the agent's analysis.

The Full Loop in Practice

Here's a real scenario: A Linear issue is created — "Orders API returning 500s." The agent:

1. Reads the Linear issue — bare description, no investigation yet
2. Checks Sentry — finds a TypeError: Cannot read properties of undefined (reading 'id') happening 40 times/hour, affecting 12 users
3. Finds the code in src/services/orders.ts at line 83 — a function that assumes order.customer always exists
4. Discovers a commit from yesterday that changed the customer lookup query to be lazy-loaded
5. Finds a Slack message from an engineer saying "seeing some null reference errors after the deploy"
6. Checks for duplicate Linear issues — none found
7. Writes a specification: "Orders API fails when customer is not preloaded after lazy-loading change"

The Linear issue is enriched with the code, the breaking commit, the Sentry error data, the Slack thread, and a clear description. Total time: under 30 seconds.

Architecture Notes

The agent runs as a stateless function triggered by schedule or manually. Each run is independent — there's no long-running process to manage. GitHub, Sentry, and Slack integrations use OAuth tokens scoped to your organization. Linear integration uses OAuth or API keys.

The embedding store for deduplication is maintained per-workspace, with embeddings updated whenever Linear issues are created or modified. This keeps the duplicate detection accurate as your backlog evolves.

Try It

SpecSource's free plan includes 100 credits — enough to see the agent in action on your real issues. Connect Linear, Sentry, GitHub, and Slack, and the next issue you create will get a detailed specification instead of sitting bare in your backlog. See specsource.ai to get started.