---
name: research-issue
description: Research a GitHub issue and provide a decision-ready analysis with implementation options, pros/cons, and a clear recommendation. Use when asked to research an issue, analyze a bug/feature, explore implementation approaches, or provide a summary for decision-making. Triggers on "research issue", "analyze issue", "what are the options for", or requests for pros/cons analysis of technical decisions.
argument-hint: <issue-url-or-number>
---

# Research Issue

Research a GitHub issue and deliver a concise, decision-ready summary.

## Workflow

1. **Fetch the issue** using `gh issue view $ARGUMENTS --comments` (includes the entire thread)
2. **Understand the context** - Read code files mentioned in the issue
3. **Explore the broader codebase** - Understand existing patterns, architecture, and conventions before proposing solutions
4. **Identify the core problem** - What exactly needs to be solved?
5. **Research options** - Explore 2-4 viable approaches
6. **Analyze trade-offs** - Use dimensions from [references/analysis-dimensions.md](references/analysis-dimensions.md)
7. **Form a recommendation** - Pick the best option with justification and confidence level

## Issue Type Analysis

Tailor the analysis based on issue type:

**Bug**: Focus on root cause, fix options, regression risk, and test coverage gaps

**Feature**: Focus on design patterns, API surface, extensibility, and consistency with existing features

**Refactor**: Focus on before/after complexity, migration path, and risk of behavioral changes

## Critical Principles

- **Simple over easy** - Prefer solutions that are conceptually simple and maintainable, even if they require more upfront effort. Avoid shortcuts that create technical debt.
- **Respect existing patterns** - Solutions should align with the codebase's established architecture, naming conventions, and idioms. Deviating from patterns requires strong justification.
- **Minimize surface area** - Prefer changes that affect fewer files and introduce fewer new concepts.

## Output Format

```markdown
## Problem
[1-2 sentences: What's broken/needed and why it matters]

## Codebase Context
[Key patterns, conventions, or architecture relevant to this issue]

## Options

### Option A: [Name]
- **Approach**: [How it works]
- **Pros**: [Benefits]
- **Cons**: [Drawbacks]
- **Effort**: Low/Medium/High
- **Files affected**: [List key files]

### Option B: [Name]
...

## Recommendation
**[Option X]** (Confidence: High/Medium/Low)

[Why this option wins. 1-2 sentences on why alternatives are worse.]

## Next Steps
1. [First action]
2. [Second action]
```

## Confidence Levels

- **High**: Clear winner, aligns with codebase patterns, low risk
- **Medium**: Good option but trade-offs are close, or requires assumptions
- **Low**: Multiple valid paths, needs more input or experimentation
