Refine
AI-powered ticket refinement agent
Overview
Refine transforms vague tickets into development-ready specifications through multi-turn conversation. It reads your Linear issue, analyzes the connected codebase, examines attached images and Loom videos, and asks targeted clarifying questions until every ambiguity is resolved. Once satisfied, it produces a structured spec with acceptance criteria, risk assessment, dependencies, and a story point estimate.
Refine is opinionated by design. It challenges assumptions, proposes simpler alternatives, and flags over-engineering before a single line of code is written.
How to trigger
Assign or @mention Refine on any Linear issue. Refine operates through the Linear AgentSession API, appearing as a first-class agent in your Linear workspace. Once triggered, it begins analyzing the issue and posts its first clarifying question as a comment.
What it reads
- Issue title, description, and current status
- All comments and threaded replies on the issue
- Attached images (analyzed as visual context)
- Loom video URLs embedded in the description or comments (automatically transcribed and extracted for steps-to-reproduce and workflow context)
- Connected repository files — Refine reads
CLAUDE.md,README.md, and thedocs/folder of each project in your workspace
What it produces
Once all questions are answered and the issue is fully understood, Refine delivers a complete refinement summary:
- Clear acceptance criteria
- Steps to reproduce (for bugs, extracted from video transcripts when available)
- Identified risks and dependencies
- Documentation update reminders when relevant
- Story point estimate using the Fibonacci scale (1, 2, 3, 5, 8, 13) with a brief justification based on effort, complexity, uncertainty, and dependencies
| Points | Meaning |
|---|---|
| 1 SP | Simple task, minimal complexity (fix typo, change label) |
| 2 SP | Slightly complex with few unknowns (simple config change) |
| 3 SP | Moderate complexity with some dependencies (new API endpoint) |
| 5 SP | Complex task with multiple dependencies (feature with DB changes) |
| 8 SP | Very complex or high uncertainty — Refine may recommend breaking it down |
| 13 SP | Too large — must be split into smaller tasks before development |
Questioning strategy
Refine does not deliver the final spec until all ambiguities are resolved. It asks one question at a time and keeps asking until it has complete clarity on every aspect of the issue. There is no limit on the number of questions — thoroughness is more important than speed.
If Refine believes there is a better implementation or a simpler approach, it will challenge your assumptions and propose alternatives. This is intentional — it is designed to catch problems before they become code.
Configuration
Refine requires no per-agent configuration. It uses your workspace's Linear integration for issue access and your workspace's Anthropic API key for Claude. Each agent type (Refine, Build, Review) has its own Linear OAuth app credentials, which are configured at the platform level.
Status values
in_progressRefine is actively analyzing the issue and asking clarifying questions.
completedThe refinement spec has been delivered to the issue.
errorSomething went wrong during refinement.
Limitations
- Only works with Linear. Jira and other issue trackers are not supported.
- Video transcription requires Loom URLs specifically. Other video hosting platforms are not supported.
- Refine is a refinement-only agent. It cannot modify code, create merge requests, or make changes to your repository.