linear-refineSafety 95Repository ShareFavorite skill

Refine an existing Linear issue by fetching its current state, running it through the same refinement steps as /linear-create (interview, title crafting, metadata suggestions), and updating the issue with the approved changes.

Skill Invocation

This skill MUST be invoked with a Linear issue identifier as an argument:

/linear-refine

Example: /linear-refine ABC-123

If no identifier is provided, the agent MUST ask the user for one before proceeding.

Step 1: Fetch Issue Details

The agent MUST fetch the issue using the Linear MCP get_issue tool with includeRelations: true.

The agent MUST extract and present to the user:

• Issue identifier and title
• Full description (if any)
• Current status, priority, and assignee
• Team, project, labels, and milestone (if any)

If the issue description contains embedded images, the agent SHOULD use extract_images to view them for additional context.

If the issue cannot be found, the agent MUST inform the user and stop.

The agent MUST retain the issue's current field values for comparison in Step 6.

Step 2: Resolve Team and Project

The team is already known from the fetched issue. The agent MUST use it without prompting.

For project resolution, the agent MUST query Linear for available projects by calling list_projects.

• If the issue already has a project, the agent MUST present it as the recommended option
• If the issue has no project, the agent MUST determine the default project name from the current repository's root directory (same logic as /linear-create Step 1)

The agent MUST use AskUserQuestion to confirm the project, offering:

1. The current/default project as the recommended option (if it exists)
2. Other available projects
3. An option to skip project assignment

Step 3: Query Labels and Milestones

The agent MUST fetch metadata in parallel:

1. Call list_issue_labels (filtered by the issue's team)
2. If a project was selected, call list_milestones for that project

If no project was selected, the agent MUST skip milestone retrieval.

Step 4: Gather Additional Details

The agent MUST follow the interview process defined in /linear-create Step 5, with the following adaptation:

• The "input text" is the existing issue's title and description (not freeform user input)
• Questions SHOULD reference the existing issue content (e.g., "The current description mentions X — can you clarify Y?")
• If the existing description already has clear motivation, acceptance criteria, and constraints, the agent SHOULD weight the skip condition more heavily — the interview is most valuable when the existing description is vague or missing key sections

All other rules from /linear-create Step 5 apply: skip condition, classification, question limits, elicitation goals, and result storage.

Step 5: Craft Title and Suggest Metadata

The agent MUST follow the title, description, label, and milestone rules defined in /linear-create Step 6, with the following adaptations:

Title

The "input text" for title refinement is the existing issue's title. All other title rules from /linear-create Step 6 apply.

Description

• If the existing description already follows the structured template from /linear-create Step 6 (has clear motivation, acceptance criteria, and constraints sections) and Step 4 was skipped, the agent SHOULD leave the description unchanged
• If the existing description has useful content but lacks structure, the agent SHOULD restructure it into the template format from /linear-create Step 6, preserving the original content and supplementing it with any new details gathered in Step 4
• If the existing description is minimal or empty and Step 4 gathered additional details, the agent MUST generate a new description following /linear-create Step 6 rules

Label Suggestion

All rules from /linear-create Step 6 apply, with one addition:

• If the issue already has a label that is a strong match, the agent SHOULD retain it

Priority Suggestion

All rules from /linear-create Step 6 apply, with one addition:

• If the issue already has a priority set, the agent SHOULD retain it unless the interview revealed a severity change

Milestone Suggestion

All rules from /linear-create Step 6 apply, with one addition:

1. The issue's current milestone (if it has one and it is still valid) takes highest priority
2. Then the standard /linear-create milestone priority order applies

Step 6: Present Draft for Approval

The agent MUST present the refined issue draft to the user before updating it.

The draft MUST be formatted as a Markdown table with three columns showing current and proposed values:

### Linear Issue Refinement

| Field     | Current                            | Proposed                           |
|-----------|------------------------------------|------------------------------------|
| Title     | <current title>                    | <refined title>                    |
| Team      | <current team>                     | <same team>                        |
| Priority  | <current priority>                 | <suggested priority>               |
| Project   | <current project or "None">        | <selected project or "None">       |
| Label     | <current label or "None">          | <suggested label or "None">        |
| Milestone | <current milestone or "None">      | <suggested milestone or "None">    |

If a description change is proposed, the agent MUST render it as separate Markdown blocks immediately after the table:

Current Description:

(existing description or "None")

Proposed Description:

(refined description)

If the description is unchanged, the agent MUST omit the description blocks.

The agent MUST ask the user to approve, edit, or cancel:

• Approve — update the issue as drafted
• Edit — modify specific fields and re-present the draft
• Cancel — abort refinement

The agent MUST NOT update the issue without explicit user approval.

Step 7: Update Issue

After the user approves, the agent MUST update the issue using update_issue with the approved details.

The agent SHOULD only send fields that changed from the original issue. If no fields changed, the agent MUST inform the user that no changes were necessary and skip the update.

After successful update, the agent MUST display:

• The issue identifier (e.g., PROJ-123)
• A summary of what changed
• A confirmation message

If the update fails, the agent MUST display the error and offer to retry or cancel.