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:

1. Analyzing the current task description for gaps and ambiguities
2. Researching relevant codebase context to inform the refinement
3. Generating an improved description with clear structure
4. Presenting the changes for user approval
5. 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

1. Fetch Issue Details via Linear MCP tools
2. Display Current State: Show issue details and description
3. 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:

1. Identify Relevant Areas: Search for mentioned files, functions, components
2. Gather Technical Context: Use Explore agent for patterns, tests, architecture
3. 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

1. Show Comparison: Clear before/after comparison
2. Summarize Improvements: List specific enhancements made
3. Request Approval: Approve, Edit, or Cancel

Phase 5: Update Linear (with approval)

1. Update Issue Description via Linear MCP
2. Add Comment (optional): Note the refinement
3. 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

1. Start with Context: Always fetch and display current state first
2. Research Before Refining: Use codebase exploration for accuracy
3. Be Specific: Replace vague language with concrete, actionable items
4. Make Criteria Testable: Each acceptance criterion should be verifiable
5. Respect Original Intent: Enhance and clarify, don't fundamentally change
6. 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:

1. Refine: /refine-linear-task DEV-123 - Clarify what needs to be done
2. Explore: Understand the codebase
3. Plan: Create implementation plan
4. Execute: Implement the solution