Refine Issue Guide

Your agent for refining raw bug reports, feature requests, and issue descriptions into well-structured, actionable tickets that developers can pick up and implement without ambiguity.

When to Use This Agent

Choose Refine Issue Guide when:

• Converting vague bug reports into detailed, reproducible issue tickets
• Refining feature requests into stories with clear acceptance criteria
• Improving issue descriptions with missing context, reproduction steps, or scope
• Standardizing issue quality across a team or project
• Triaging and enriching issues before sprint planning

Consider alternatives when:

• You need to investigate and debug the issue — use a debug agent
• You need to implement the fix — use a developer agent
• You need to create Jira tickets from requirements — use an Atlassian agent

Quick Start

Copy
# .claude/agents/refine-issue.yml
name: Refine Issue Guide
model: claude-sonnet
tools:
  - Read
  - Glob
  - Grep
  - Bash
description: Issue refinement agent that transforms vague bug reports and feature requests into well-structured, actionable tickets

Example invocation:

claude "Refine this issue: 'Login is broken sometimes' — investigate the codebase for potential causes and create a proper bug report with reproduction steps, expected vs actual behavior, and affected components"

Core Concepts

Issue Refinement Template

Copy
## Bug Report: [Clear, specific title]

**Severity**: Critical / High / Medium / Low
**Component**: [Affected module or service]
**Reporter**: [Original reporter]

### Description
[1-2 sentence description of the problem]

### Steps to Reproduce
1. [Specific step]
2. [Specific step]
3. [Specific step]

### Expected Behavior
[What should happen]

### Actual Behavior
[What actually happens]

### Environment
- Browser/OS: [details]
- App version: [version]
- Relevant configuration: [settings]

### Investigation Notes
- [Potential root cause based on code analysis]
- [Related code files and functions]
- [Similar past issues, if any]

Refinement Quality Criteria

Criterion	Bad Example	Good Example
Title	"Login broken"	"SSO login fails with 500 error when SAML assertion contains special characters"
Steps	"Try to log in"	"1. Click SSO Login 2. Enter credentials 3. Click Submit — 500 error on redirect"
Scope	"Fix auth"	"Fix SAML assertion parsing in src/auth/saml.ts:42 to handle XML-encoded characters"

Configuration

Parameter	Description	Default
issue_type	Issue type focus (bug, feature, task, any)	any
investigation_depth	How deep to investigate (none, basic, thorough)	basic
template_format	Output template (github, jira, gitlab, markdown)	markdown
include_code_refs	Include code file references	true
auto_label	Suggest labels and priority	true

Best Practices

1. Investigate the codebase before refining. Search for the affected component, recent changes to relevant files, and related test coverage. Code-informed refinement produces issues with accurate file references and potential root cause hints.

2. Write titles that describe the problem, not the symptom. "Search returns no results" (symptom) vs "Elasticsearch index not refreshed after document creation causes stale search results" (problem). Good titles help developers understand the issue before opening it.

3. Include both reproduction steps and environment details. "It doesn't work" is unusable. "On Chrome 120, macOS Sonoma, when clicking Submit on the checkout form with an international address, the form shows a blank error message instead of the validation text" is actionable.

4. Link to related issues, PRs, and documentation. Context reduces investigation time. If a similar bug was fixed before, link to that PR. If the affected feature has documentation, link to it.

5. Suggest a severity level with justification. "Critical: blocks all SSO users from logging in (50% of user base)" helps product owners prioritize. Without severity context, all bugs feel equally important.

Common Issues

Refined issue still lacks root cause because the reporter can't reproduce it. For intermittent issues, add logging and monitoring suggestions to the ticket. "Unable to reproduce consistently — recommend adding structured logging to auth/saml.ts to capture the assertion payload when the error occurs."

Issue scope is too large for a single ticket. "Fix all authentication issues" should be split into individual tickets per bug. Each ticket should be completable in a single sprint by a single developer.

Issue becomes a design discussion instead of an actionable task. If an issue requires significant design decisions before implementation, split it into a "Spike: investigate approach for X" ticket and a "Implement X" ticket that depends on the spike.