gh-devkade-collaborator-skills-oss-contribution-framework/references/issue-patterns.md

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:

// 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:

# 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:

// 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:

// 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:

**Checklist:**
- [ ] Component implementation
- [ ] State management
- [ ] Event handling
- [ ] Styling
- [ ] Responsive design
- [ ] Accessibility
- [ ] Loading states
- [ ] Error states
- [ ] User feedback (success/error messages)

API Endpoint:

**Checklist:**
- [ ] Route definition
- [ ] Request validation
- [ ] Business logic
- [ ] Response formatting
- [ ] Error handling
- [ ] Authentication/authorization
- [ ] Rate limiting (if needed)
- [ ] API documentation
- [ ] Integration tests

CLI Command:

**Checklist:**
- [ ] Command definition
- [ ] Argument parsing
- [ ] Validation
- [ ] Core logic
- [ ] Output formatting
- [ ] Error messages
- [ ] Help text
- [ ] Examples in docs

Library Function:

**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:

**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:

**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:

**Structure:**
1. Function/API signature
2. Parameters
3. Return value
4. Errors/exceptions
5. Examples
6. See also

**Style:**
- Precise
- Complete
- Technical
- Searchable

Conceptual:

**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:

// 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:

# 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:

// 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:

// 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:

// 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:

// 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:

// 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:

// 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:

// 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:

// 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:

// 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:

// 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.