# Issue Analysis: [Issue Title]

**Issue:** #[number] | **Type:** [bug/feature/refactor/docs/performance]
**URL:** [GitHub issue link]
**Status:** Ready to implement / Needs clarification
**Date:** [Analysis date]

---

## Summary

[2-3 sentence summary of what needs to be done and why]

---

## Requirements

### Core Requirements

[Based on issue type, fill in relevant section below]

#### For Bug Fixes

**Current Behavior:**
[What actually happens - be specific]

**Expected Behavior:**
[What should happen - reference docs/specs if available]

**Reproduction Steps:**
1. [Step 1]
2. [Step 2]
3. [Observe: ...]

**Environment:**
- Version: [version]
- Platform: [OS/browser/etc]
- Configuration: [relevant settings]

**Root Cause (Hypothesis):**
[Your initial theory of what's causing this]

**Affected Users:**
[Who hits this? How often? Severity: Critical/High/Medium/Low]

#### For Features

**User Story:**
As a [user type], I want [capability] so that [benefit].

**Functional Requirements:**
1. [Requirement 1 - must have]
2. [Requirement 2 - must have]
3. [Requirement 3 - nice to have]

**User Interface:**
- **Input:** [What user provides]
- **Output:** [What user sees/gets]
- **Interaction flow:** [Step-by-step user journey]

**Non-Functional Requirements:**
- Performance: [any constraints]
- Compatibility: [versions, platforms]
- Accessibility: [considerations]

#### For Refactoring

**Current Problems:**
1. [Problem 1: e.g., duplicated code across X files]
2. [Problem 2: e.g., poor separation of concerns]
3. [Problem 3: e.g., difficult to test]

**Desired Outcome:**
[What the code should look like after refactoring]

**Constraints:**
- [ ] No behavior changes
- [ ] All existing tests must pass
- [ ] No API changes (if library)
- [ ] [Other constraints]

### Edge Cases & Implicit Requirements

**Boundary Conditions:**
- [ ] Empty input: [how to handle]
- [ ] Large data: [limits, pagination]
- [ ] Special characters: [escaping, validation]
- [ ] Null/undefined: [default behavior]

**Error Handling:**
- [ ] Network failure: [retry logic, user feedback]
- [ ] Invalid input: [validation, error messages]
- [ ] Permissions: [who can do what]
- [ ] Resource exhaustion: [limits, throttling]

**Integration Concerns:**
- **Depends on:** [list dependencies]
- **Affects:** [list affected components]
- **Breaking change:** Yes ⚠️ / No ✅
- **Backwards compatibility:** [considerations]

**Non-Functional:**
- **Performance:** [requirements or concerns]
- **Security:** [validations needed]
- **Accessibility:** [ARIA, keyboard nav, etc]
- **Mobile/Responsive:** [considerations]

---

## Scope Definition

### In Scope (Minimal)
1. [Must-have item 1]
2. [Must-have item 2]
3. [Must-have item 3]

### In Scope (If Time Permits)
1. [Nice-to-have item 1]
2. [Nice-to-have item 2]

### Out of Scope
1. [Item to defer - with reason]
2. [Item to defer - with reason]

### Dependencies
- **Blocked by:** [list blocking issues]
- **Blocks:** [list issues waiting on this]

### Estimated Complexity
🟢 Simple (< 4 hours)
🟡 Moderate (1-2 days)
🔴 Complex (3+ days)

**Complexity Factors:**
- [Factor 1: e.g., need to learn new API]
- [Factor 2: e.g., touching critical code path]
- [Factor 3: e.g., requires significant testing]

---

## Acceptance Criteria

### Functional
- [ ] [Action] results in [observable outcome]
- [ ] [Condition] produces [expected result]
- [ ] [Feature] works with [existing feature]
- [ ] [Edge case] handled appropriately

### Quality
- [ ] All new code has tests (coverage > X%)
- [ ] No new linting errors
- [ ] No new type errors
- [ ] Documentation updated
- [ ] Existing tests pass

### Edge Cases
- [ ] [Edge case 1] handled correctly
- [ ] [Edge case 2] shows appropriate error
- [ ] [Edge case 3] returns expected default

### Integration
- [ ] Works on [platform 1]
- [ ] Compatible with [version X]
- [ ] No breaking changes (or documented)
- [ ] Integrates with [related feature]

---

## Implementation Notes

### Affected Components
- [Component 1: description of involvement]
- [Component 2: description of involvement]
- [Component 3: description of involvement]

### Key Considerations
- [Consideration 1: important factor to keep in mind]
- [Consideration 2: architectural constraint]
- [Consideration 3: performance implication]

### Potential Challenges
- **[Challenge 1]:** [description]
  - Mitigation: [how to address]
- **[Challenge 2]:** [description]
  - Mitigation: [how to address]

### Similar Patterns in Codebase
- [Similar feature/pattern 1] @ [file:line]
- [Similar feature/pattern 2] @ [file:line]

---

## Open Questions

[Questions to ask maintainer before implementation]

1. **[Specific aspect]**
   - Current understanding: [what you think]
   - Question: [what's unclear]
   - Options: [potential approaches A, B, C]
   - Preference: [your recommendation and why]

2. **[Edge case handling]**
   - Scenario: [describe edge case]
   - Question: Should this [A] or [B]?
   - Precedent: [similar handling elsewhere, if found]

---

## Next Steps

✅ Analysis complete - Ready for **Phase 3: Codebase Exploration**

**Before coding, explore:**
1. [Specific file/component to understand]
2. [Test patterns to learn]
3. [Similar features to reference]

**Or if clarification needed:**
❓ Post questions to issue thread and wait for maintainer response

---

## Notes

[Any additional context, insights, or considerations]