Initial commit

references/issue-patterns.md

@@ -0,0 +1,714 @@
+# Issue Patterns Reference
+
+Common issue types and specialized approaches for each.
+
+## Bug Reports
+
+### Characteristics
+- Something is broken
+- Current behavior doesn't match expected
+- Often includes error messages
+- May have reproduction steps
+
+### Analysis Pattern
+
+**1. Reproduce**
+- Follow reproduction steps exactly
+- Verify bug exists
+- Note environment details
+
+**2. Isolate**
+- Minimal test case
+- Remove unrelated factors
+- Identify triggering conditions
+
+**3. Locate**
+- Find where error occurs
+- Trace backwards to cause
+- Identify root cause vs symptoms
+
+**4. Fix Strategy**
+- Fix root cause, not symptoms
+- Handle similar edge cases
+- Don't break working cases
+- Add regression test
+
+### Common Bug Patterns
+
+**Null/Undefined Errors:**
+```javascript
+// Bug: Crashes when data is null
+function process(data) {
+  return data.value // TypeError if data is null
+}
+
+// Fix: Handle null case
+function process(data) {
+  if (!data) return defaultValue
+  return data.value
+}
+
+// Test
+expect(process(null)).toBe(defaultValue)
+```
+
+**Off-by-One Errors:**
+```python
+# Bug: Skips last element
+for i in range(len(arr) - 1):
+    process(arr[i])
+
+# Fix
+for i in range(len(arr)):
+    process(arr[i])
+
+# Or better
+for item in arr:
+    process(item)
+```
+
+**Race Conditions:**
+```javascript
+// Bug: State changes between check and use
+if (cache.has(key)) {
+  return cache.get(key) // Might be deleted by now
+}
+
+// Fix: Get once, check result
+const value = cache.get(key)
+if (value !== undefined) {
+  return value
+}
+```
+
+**Input Validation:**
+```javascript
+// Bug: No validation
+function divide(a, b) {
+  return a / b // Division by zero
+}
+
+// Fix: Validate inputs
+function divide(a, b) {
+  if (b === 0) {
+    throw new Error('Division by zero')
+  }
+  return a / b
+}
+```
+
+---
+
+## Feature Requests
+
+### Characteristics
+- Request for new functionality
+- Describes user need
+- May include use cases
+- May have mockups/examples
+
+### Analysis Pattern
+
+**1. Understand Need**
+- Who needs this?
+- What problem does it solve?
+- What are use cases?
+- Why existing features insufficient?
+
+**2. Design API/Interface**
+- How will users interact?
+- What's the simplest interface?
+- Consistent with existing features?
+- Extensible for future needs?
+
+**3. Plan Implementation**
+- Where does it fit architecturally?
+- What components affected?
+- Data model changes needed?
+- Breaking changes?
+
+**4. Implementation Strategy**
+- Start with minimal viable version
+- Add polish incrementally
+- Get feedback early
+- Document well
+
+### Feature Types
+
+**UI Feature:**
+```markdown
+**Checklist:**
+- [ ] Component implementation
+- [ ] State management
+- [ ] Event handling
+- [ ] Styling
+- [ ] Responsive design
+- [ ] Accessibility
+- [ ] Loading states
+- [ ] Error states
+- [ ] User feedback (success/error messages)
+```
+
+**API Endpoint:**
+```markdown
+**Checklist:**
+- [ ] Route definition
+- [ ] Request validation
+- [ ] Business logic
+- [ ] Response formatting
+- [ ] Error handling
+- [ ] Authentication/authorization
+- [ ] Rate limiting (if needed)
+- [ ] API documentation
+- [ ] Integration tests
+```
+
+**CLI Command:**
+```markdown
+**Checklist:**
+- [ ] Command definition
+- [ ] Argument parsing
+- [ ] Validation
+- [ ] Core logic
+- [ ] Output formatting
+- [ ] Error messages
+- [ ] Help text
+- [ ] Examples in docs
+```
+
+**Library Function:**
+```markdown
+**Checklist:**
+- [ ] Function signature design
+- [ ] Input validation
+- [ ] Core implementation
+- [ ] Error handling
+- [ ] Documentation (JSDoc/docstrings)
+- [ ] Usage examples
+- [ ] Type definitions
+- [ ] Backwards compatibility
+```
+
+---
+
+## Documentation Issues
+
+### Characteristics
+- Missing or unclear docs
+- Outdated information
+- Requests for examples
+- Typos or formatting
+
+### Analysis Pattern
+
+**1. Identify Gap**
+- What's missing?
+- Who's the audience?
+- What level of detail?
+- Where should it live?
+
+**2. Research**
+- Understand the feature fully
+- Find code examples
+- Check similar docs
+- Verify current behavior
+
+**3. Write**
+- Clear and concise
+- Examples included
+- Proper formatting
+- Links to related docs
+
+**4. Verify**
+- Technically accurate
+- Examples work
+- No broken links
+- Proper grammar/spelling
+
+### Documentation Types
+
+**Tutorials:**
+```markdown
+**Structure:**
+1. What you'll build
+2. Prerequisites
+3. Step-by-step instructions
+4. Expected results
+5. Next steps
+
+**Style:**
+- Conversational
+- Hand-holding
+- Complete working example
+- Learn by doing
+```
+
+**How-To Guides:**
+```markdown
+**Structure:**
+1. Problem statement
+2. Solution approach
+3. Step-by-step
+4. Variations/alternatives
+
+**Style:**
+- Task-oriented
+- Practical
+- Assumes some knowledge
+- Shows best practices
+```
+
+**Reference:**
+```markdown
+**Structure:**
+1. Function/API signature
+2. Parameters
+3. Return value
+4. Errors/exceptions
+5. Examples
+6. See also
+
+**Style:**
+- Precise
+- Complete
+- Technical
+- Searchable
+```
+
+**Conceptual:**
+```markdown
+**Structure:**
+1. Overview
+2. Key concepts
+3. How it works
+4. When to use
+5. Related topics
+
+**Style:**
+- Explanatory
+- Big picture
+- Theory and context
+- Understanding-focused
+```
+
+---
+
+## Refactoring Issues
+
+### Characteristics
+- Code quality improvement
+- No behavior change
+- Technical debt
+- Maintainability focus
+
+### Analysis Pattern
+
+**1. Identify Problems**
+- Code smells
+- Duplication
+- Complexity
+- Poor naming
+- Tight coupling
+
+**2. Ensure Test Coverage**
+- Tests exist for current behavior
+- Tests are comprehensive
+- Tests will catch regressions
+
+**3. Plan Incremental Steps**
+- Small, safe transformations
+- Each step leaves code working
+- Can pause/resume anytime
+
+**4. Execute Carefully**
+- One refactoring at a time
+- Run tests after each step
+- Commit working states
+- Don't mix with feature work
+
+### Refactoring Patterns
+
+**Extract Function:**
+```javascript
+// Before: Long complex function
+function processOrder(order) {
+  // 50 lines of code
+  // mixing concerns
+}
+
+// After: Extracted smaller functions
+function processOrder(order) {
+  validateOrder(order)
+  const items = prepareItems(order.items)
+  const total = calculateTotal(items)
+  return createInvoice(order, items, total)
+}
+
+function validateOrder(order) { /* ... */ }
+function prepareItems(items) { /* ... */ }
+function calculateTotal(items) { /* ... */ }
+function createInvoice(order, items, total) { /* ... */ }
+```
+
+**Remove Duplication:**
+```python
+# Before: Duplicated logic
+def process_user_data(data):
+    if not data:
+        raise ValueError("Invalid data")
+    # process...
+
+def process_order_data(data):
+    if not data:
+        raise ValueError("Invalid data")
+    # process...
+
+# After: Extracted common logic
+def validate_data(data):
+    if not data:
+        raise ValueError("Invalid data")
+
+def process_user_data(data):
+    validate_data(data)
+    # process...
+
+def process_order_data(data):
+    validate_data(data)
+    # process...
+```
+
+**Improve Naming:**
+```javascript
+// Before: Unclear names
+function calc(x, y) {
+  const t = x * y
+  const d = t * 0.1
+  return t - d
+}
+
+// After: Clear names
+function calculateTotalWithDiscount(price, quantity) {
+  const subtotal = price * quantity
+  const discount = subtotal * 0.1
+  return subtotal - discount
+}
+```
+
+**Reduce Complexity:**
+```javascript
+// Before: Deep nesting
+function process(data) {
+  if (data) {
+    if (data.items) {
+      if (data.items.length > 0) {
+        // process
+      }
+    }
+  }
+}
+
+// After: Early returns
+function process(data) {
+  if (!data) return
+  if (!data.items) return
+  if (data.items.length === 0) return
+
+  // process
+}
+```
+
+---
+
+## Performance Issues
+
+### Characteristics
+- Something is slow
+- Resource usage high
+- Scalability problems
+- May include benchmarks
+
+### Analysis Pattern
+
+**1. Measure**
+- Reproduce performance issue
+- Measure current performance
+- Profile to find bottleneck
+- Get baseline numbers
+
+**2. Identify Cause**
+- Algorithm complexity
+- Unnecessary work
+- Resource leaks
+- Inefficient data structures
+
+**3. Optimize**
+- Fix the bottleneck
+- Use better algorithm
+- Cache when appropriate
+- Lazy load when possible
+
+**4. Verify**
+- Measure improvement
+- Check correctness maintained
+- Verify no regressions
+- Document tradeoffs
+
+### Performance Patterns
+
+**Algorithm Optimization:**
+```javascript
+// Before: O(n²)
+function findDuplicates(arr) {
+  const dupes = []
+  for (let i = 0; i < arr.length; i++) {
+    for (let j = i + 1; j < arr.length; j++) {
+      if (arr[i] === arr[j]) {
+        dupes.push(arr[i])
+      }
+    }
+  }
+  return dupes
+}
+
+// After: O(n)
+function findDuplicates(arr) {
+  const seen = new Set()
+  const dupes = new Set()
+  for (const item of arr) {
+    if (seen.has(item)) {
+      dupes.add(item)
+    }
+    seen.add(item)
+  }
+  return Array.from(dupes)
+}
+```
+
+**Caching:**
+```javascript
+// Before: Recalculates every time
+function expensiveCalculation(data) {
+  // Heavy computation
+  return result
+}
+
+// After: Cache results
+const cache = new Map()
+function expensiveCalculation(data) {
+  const key = JSON.stringify(data)
+  if (cache.has(key)) {
+    return cache.get(key)
+  }
+  const result = /* heavy computation */
+  cache.set(key, result)
+  return result
+}
+```
+
+**Lazy Loading:**
+```javascript
+// Before: Load everything upfront
+const data = loadAllData() // Slow!
+
+// After: Load on demand
+let data = null
+function getData() {
+  if (!data) {
+    data = loadAllData()
+  }
+  return data
+}
+```
+
+---
+
+## Security Issues
+
+### Characteristics
+- Security vulnerability
+- Potential exploit
+- Missing validation
+- Unsafe practices
+
+### Analysis Pattern
+
+**1. Assess Severity**
+- What can attacker do?
+- What data is at risk?
+- Who is affected?
+- How easy to exploit?
+
+**2. Identify Root Cause**
+- Missing validation?
+- Unsafe API usage?
+- Incorrect logic?
+- Outdated dependency?
+
+**3. Fix Securely**
+- Validate all inputs
+- Use safe APIs
+- Follow security best practices
+- Don't roll your own crypto
+
+**4. Verify Fix**
+- Test exploit no longer works
+- Check similar code
+- Add security tests
+- Consider security review
+
+### Security Patterns
+
+**Input Validation:**
+```javascript
+// Before: No validation
+app.post('/user/:id', (req, res) => {
+  const query = `SELECT * FROM users WHERE id = ${req.params.id}`
+  db.query(query) // SQL injection!
+})
+
+// After: Validated and parameterized
+app.post('/user/:id', (req, res) => {
+  const id = parseInt(req.params.id, 10)
+  if (isNaN(id)) {
+    return res.status(400).json({ error: 'Invalid ID' })
+  }
+  const query = 'SELECT * FROM users WHERE id = ?'
+  db.query(query, [id]) // Safe
+})
+```
+
+**XSS Prevention:**
+```javascript
+// Before: Direct HTML insertion
+element.innerHTML = userInput // XSS!
+
+// After: Escaped text
+element.textContent = userInput // Safe
+// Or use framework's escaping
+element.innerHTML = escapeHtml(userInput)
+```
+
+**Authorization:**
+```javascript
+// Before: No auth check
+app.delete('/user/:id', (req, res) => {
+  deleteUser(req.params.id) // Anyone can delete!
+})
+
+// After: Check permissions
+app.delete('/user/:id', requireAuth, (req, res) => {
+  if (req.user.id !== req.params.id && !req.user.isAdmin) {
+    return res.status(403).json({ error: 'Forbidden' })
+  }
+  deleteUser(req.params.id)
+})
+```
+
+---
+
+## CI/CD Issues
+
+### Characteristics
+- Build failures
+- Test flakiness
+- Deployment problems
+- Pipeline configuration
+
+### Analysis Pattern
+
+**1. Reproduce Locally**
+- Can you reproduce the issue?
+- Environment differences?
+- Missing dependencies?
+
+**2. Identify Cause**
+- Check CI logs
+- Look for error messages
+- Compare with working runs
+- Check recent changes
+
+**3. Fix**
+- Update configuration
+- Fix flaky tests
+- Add missing dependencies
+- Improve reliability
+
+**4. Verify**
+- Passes consistently
+- Doesn't break other jobs
+- Works across environments
+
+### CI/CD Patterns
+
+**Flaky Test Fix:**
+```javascript
+// Before: Flaky due to timing
+test('updates after delay', () => {
+  triggerUpdate()
+  expect(getValue()).toBe(newValue) // Sometimes fails
+})
+
+// After: Proper async handling
+test('updates after delay', async () => {
+  triggerUpdate()
+  await waitFor(() => expect(getValue()).toBe(newValue))
+})
+```
+
+**Environment-Specific Fix:**
+```javascript
+// Before: Assumes specific OS
+const path = '/usr/local/bin' // Fails on Windows
+
+// After: Cross-platform
+const path = require('path').join(os.homedir(), 'bin')
+```
+
+---
+
+## Dependency Updates
+
+### Characteristics
+- Upgrade library version
+- Fix security vulnerability
+- Get new features
+- Maintenance
+
+### Analysis Pattern
+
+**1. Check Changes**
+- Read changelog
+- Review breaking changes
+- Check migration guide
+- Assess impact
+
+**2. Update**
+- Update package version
+- Update code if needed
+- Update tests
+- Update docs
+
+**3. Test Thoroughly**
+- All tests pass
+- Manual testing
+- Check for regressions
+- Verify new version works
+
+**4. Document**
+- Note breaking changes
+- Update dependencies list
+- Mention in changelog
+
+---
+
+## Using This Reference
+
+When analyzing an issue:
+
+1. Identify issue type
+2. Read corresponding pattern
+3. Follow analysis checklist
+4. Apply relevant code patterns
+5. Adapt to specific context
+
+Each project and issue is unique - use these as starting points, not rigid rules.