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.
Installs into .claude/skills of the current project.
Are you the author of Refine?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/bendrucker-refine)
---
name: issue:refine
description: 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.
---
# 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
1. Identify type and read the corresponding guide
2. Gather context from code and related issues
3. Draft refinement following the type-specific structure
4. Output for user approval before updating the issue
## Output Structure
Every issue opens with Summary and closes with Context. Type guides offer a menu of middle sections. Include only those that earn their place.
```markdown
## Summary
One to two sentences.
[Type-specific sections from guide (select, don't fill)]
## Context
### Related Code
Files that need changes or inform the work.
### Related Issues
Links to related issues, prior attempts, upstream work.
```
## Section Selection
Every section must tell the reader something they couldn't have guessed. Cut sections whose content is tautological ("tests must pass"), template residue ("no behavior change"), or obvious given the issue's size.
Minimum: Summary plus one type section plus Context. Grow only when content demands.
## Style
- **Direct** - Facts, not hedging
- **Specific** - Name the function, file, behavior
- **Concise** - Every sentence adds information
- **Earn the heading** - A section present only to match the template is filler
- **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`, or `mcp__claude_ai_Linear__get_issue`, `mcp__claude_ai_Linear__save_issue`
- GitHub: `mcp__github__get_issue`, `mcp__github__update_issue`
