refine-issue

Refining issues with technical context and structured details. Use when expanding a brief bug, feature, or refactor description into a detailed issue suitable for developers and AI agents.

Stars 163

Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/refine-issue

SKILL.md

Issue Refinement

Expand brief issue descriptions into structured issues for developers and AI agents.

Issue Types

Type	When to Use	Guide
Bug	Something is broken	`bug.md`
Feature	New capability	`feature.md`
Refactor	Internal improvement, no behavior change	`refactor.md`

Workflow

Identify type and read the corresponding guide
Gather context from code and related issues
Draft refinement following the type-specific structure
Output for user approval before updating the issue

Output Structure

All issues share this skeleton. Type guides add sections in between.

markdown

## Summary

One to two sentences.

[Type-specific sections from guide]

## Context

### Related Code

Files that need changes or inform the work.

### Related Issues

Links to related issues, prior attempts, upstream work.

Style

Direct - Facts, not hedging
Specific - Name the function, file, behavior
Concise - Every sentence adds information
Link to code - Permalinks for GitHub (https://github.com/{owner}/{repo}/blob/{sha}/path#L10-L20), file paths elsewhere (path/to/file:10-20)

Issue Trackers

Fetch with get_issue, output refinement for review, update only after approval.

Linear: mcp__linear__get_issue, mcp__linear__update_issue
GitHub: mcp__github__get_issue, mcp__github__update_issue