Linear Task Refiner
Analyze and refine Linear task descriptions to improve clarity, completeness, and actionability through AI-assisted enhancement.
When to Activate
- User wants to refine a Linear task
- User mentions improving task descriptions
- User asks to make a task clearer or more actionable
- User wants to add acceptance criteria to a task
- User mentions Linear issue refinement
Overview
This skill takes a Linear issue identifier and refines its description by:
- Analyzing the current task description for gaps and ambiguities
- Researching relevant codebase context to inform the refinement
- Generating an improved description with clear structure
- Presenting the changes for user approval
- Updating the Linear issue (with user consent)
Inputs
Parse from request:
- issue_identifier: The Linear issue ID (e.g., "DEV-123", "dai-456")
- --focus: Optional focus for refinement (security, performance, testing, accessibility)
- --update: Auto-update after approval (default: false)
Quick Process
Phase 1: Fetch and Analyze Current Task
- Fetch Issue Details via Linear MCP tools
- Display Current State: Show issue details and description
- Analyze for Gaps: Evaluate against criteria:
- Clarity: Is the problem/goal clearly stated?
- Context: Is there sufficient background information?
- Scope: Are boundaries clearly defined?
- Acceptance Criteria: Are success conditions defined?
- Technical Details: Are implementation hints provided?
- Dependencies: Are related tasks/blockers mentioned?
Phase 2: Research Codebase Context
If the task relates to existing code:
- Identify Relevant Areas: Search for mentioned files, functions, components
- Gather Technical Context: Use Explore agent for patterns, tests, architecture
- Summarize Findings: Document relevant files, patterns, considerations
Phase 3: Generate Refined Description
Create comprehensive, well-structured description:
- Problem Statement: Clear, specific description of what and why
- Context: Background information, related decisions
- Scope: In-scope and out-of-scope items explicitly listed
- Acceptance Criteria: Specific, testable success conditions
- Technical Notes: Implementation hints, relevant patterns
- Dependencies: Related tasks, blockers
- References: Documentation, design docs, related issues
Phase 4: Present and Confirm
- Show Comparison: Clear before/after comparison
- Summarize Improvements: List specific enhancements made
- Request Approval: Approve, Edit, or Cancel
Phase 5: Update Linear (with approval)
- Update Issue Description via Linear MCP
- Add Comment (optional): Note the refinement
- Confirm Success: Provide issue URL
Focus Areas
--focus security
- Analyze for security implications
- Add security-related acceptance criteria
- Note potential vulnerabilities or risks
--focus performance
- Consider performance impact
- Add performance-related acceptance criteria
- Include benchmarks or targets
--focus testing
- Emphasize test requirements
- Add test-specific acceptance criteria
- Note edge cases to cover
--focus accessibility
- Consider a11y implications
- Add accessibility acceptance criteria
- Reference WCAG guidelines if applicable
Output Format
Return structured summary:
- Issue: Identifier and title
- Status: Updated / Not Updated
- Improvements Made: List of specific improvements
- Gap Analysis Summary: Before/after comparison table
- Next Steps: Review, assign, begin implementation
Best Practices
- Start with Context: Always fetch and display current state first
- Research Before Refining: Use codebase exploration for accuracy
- Be Specific: Replace vague language with concrete, actionable items
- Make Criteria Testable: Each acceptance criterion should be verifiable
- Respect Original Intent: Enhance and clarify, don't fundamentally change
- Note Assumptions: Explicitly note any assumptions made
Examples
"Refine Linear task DEV-123"
"Improve the description for DAI-456"
"Make task DEV-789 more actionable with acceptance criteria"
"Refine DEV-104 with focus on security"
Error Handling
- Issue Not Found: Verify identifier, access, and deletion status
- No Linear Access: Check MCP server config and API key
- Update Failed: Show error, offer manual copy option
Integration
Works well with implementation workflow:
- Refine:
/refine-linear-task DEV-123 - Clarify what needs to be done
- Explore: Understand the codebase
- Plan: Create implementation plan
- Execute: Implement the solution