gh-devkade-collaborator-skills-oss-contribution-framework/skills/issue-analysis/SKILL.md

name, description

name	description
oss:issue-analysis	Phase 2 of OSS contribution - Deep analysis combining issue requirements with codebase exploration. Extracts requirements, explores code structure, identifies exact code locations to fix, traces execution paths, and maps code-level changes needed. Use when starting work on selected issue.

Phase 2: Issue Analysis & Code Exploration

Deep analysis of issue requirements combined with codebase exploration to identify exact code changes needed.

Purpose

Transform an issue into actionable code-level understanding by:

• Understanding requirements: What needs to be done and why
• Exploring codebase: Project structure, conventions, patterns
• Locating code: Find exact files/functions to modify
• Identifying problems: Pinpoint broken/missing code
• Planning changes: Map requirements to specific code modifications

When to Use

Triggers:

• "이 이슈 분석해줘"
• "코드에서 어디를 고쳐야 하나?"
• "이슈와 코드 연결"
• "문제 있는 코드 찾기"

Use when:

• Starting work on a selected issue
• Need to understand both requirements AND code
• Want to identify exact modification points
• Ready to plan implementation

Integrated Analysis Framework

Step 0: Review CONTRIBUTING.md Requirements

MANDATORY: Before analyzing the issue, review project contribution guidelines

• Refer to CONTRIBUTING.md read in Phase 1
• Ensure your analysis aligns with project conventions
• Note any specific requirements for:
  • Code style and formatting
  • Testing requirements
  • Documentation standards
  • Commit message format
  • Branch naming conventions

All analysis and subsequent work MUST comply with these guidelines

Step 1: Issue Type & Requirements Extraction

Identify issue type and extract core requirements.

Issue Types:

Bug Fix:

### Bug Analysis Template

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

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

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

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

**Impact:**
- Severity: [Critical/High/Medium/Low]
- Affected users: [who/how many]

Feature Request:

### Feature Analysis Template

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

**Acceptance Criteria:**
- [ ] [Criterion 1 - specific and testable]
- [ ] [Criterion 2]
- [ ] [Criterion 3]

Refactoring:

### Refactoring Analysis Template

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

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

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

Step 2: Project Structure & Convention Understanding

Explore codebase to understand organization and conventions.

A. Directory Structure Mapping:

# Get project overview
tree -L 2 -d

# Identify key directories
ls -la

### Project Structure

**Main source:** [path to primary code]

**Key directories:**
- `src/` or `lib/` - Main source code
- `tests/` or `__tests__/` - Test files
- `docs/` - Documentation
- `.github/` - CI/CD, workflows

**Organization principle:**
- [x] By feature (e.g., /users, /products)
- [ ] By layer (e.g., /models, /views, /controllers)
- [ ] By type (e.g., /components, /utils, /services)

**Technologies:**
- Language: [language + version]
- Framework: [framework]
- Build tool: [npm/cargo/maven/etc]
- Testing: [jest/pytest/etc]

B. Code Conventions Discovery:

# Check for style configs
cat .prettierrc .eslintrc package.json

# Find naming patterns
find src -type f -name "*.js" | head -10

### Code Conventions

**File Naming:**
- Components: [e.g., PascalCase.tsx]
- Utilities: [e.g., camelCase.ts]
- Tests: [e.g., file.test.js or file_test.go]

**Code Style:**
- Indentation: [2 spaces / 4 spaces / tabs]
- Quotes: [single / double]
- Import order: [external, internal, relative]

**Naming Patterns:**
- Classes: [PascalCase]
- Functions: [camelCase / snake_case]
- Constants: [UPPER_SNAKE_CASE]

C. Testing Patterns:

# Find test locations
find . -name "*test*" -type f | head -5

# Check test framework
cat package.json | grep -A5 "scripts"

### Testing Strategy

**Test Location:**
- Unit tests: [e.g., __tests__/, alongside source]
- Integration tests: [location]

**Test Framework:** [Jest / pytest / go test / etc]

**Test Naming Pattern:**
- [describe/test, test_, Test*]

**Run Commands:**
```bash
npm test              # All tests
npm test -- file.test.js  # Specific test
npm test -- --coverage    # With coverage

### Step 3: Code Location Discovery

Find exact files and functions related to the issue.

**A. Entry Point Discovery:**

```bash
# For UI bugs/features - find component
rg "ComponentName" --type tsx
rg "class.*ComponentName"

# For API/backend - find endpoint
rg "app\.(get|post|put).*endpoint"
rg "@app.route|router"

# For CLI - find command
rg "subcommand|command.*name"

# For library - find exported function
rg "export (function|class|const).*functionName"

### Entry Points

**Primary entry point:**
- File: `src/components/UserProfile.tsx:45`
- Function/Component: `UserProfile`
- Purpose: [what this code does]

**How to trigger:**
[Steps to reach this code - e.g., click button, call API]

B. Find Similar/Related Code:

# Find similar features for reference
rg "similar-feature" --type js

# Find similar patterns
find . -name "*Similar*.js"

# Find related tests
rg "describe.*YourFeature" tests/

### Reference Examples

**Similar code to reference:**
1. `src/components/UserSettings.tsx:120`
   - Similar pattern for form handling
   - Shows validation approach

2. `src/utils/validation.ts:45`
   - Input validation logic
   - Error handling pattern

Step 4: Code-Level Problem Identification

THIS IS THE CRITICAL STEP - Find exact code that needs fixing

A. For Bug Fixes - Trace to Root Cause:

# Search for error message or symptom
rg "error message text"

# Find function definitions
rg "function buggyFunction|def buggy_function"

# Find all callers
rg "buggyFunction\("

### Bug Root Cause Analysis

**Symptom Location:**
- File: `src/auth/session.ts:78`
- Function: `validateSession`
- Problem: Crashes when `user` is null

**Code Analysis:**
```typescript
// CURRENT CODE (BROKEN)
function validateSession(sessionId: string) {
  const session = getSession(sessionId)
  return session.user.id  // ❌ CRASHES if user is null
}

Root Cause:

• Missing null check for session.user
• Happens during logout race condition

Needs to be changed to:

// FIXED CODE
function validateSession(sessionId: string) {
  const session = getSession(sessionId)
  if (!session?.user) {  // ✅ Add null check
    return null
  }
  return session.user.id
}

Additional locations to check:

• src/auth/logout.ts:34 - may have similar issue
• src/auth/session.test.ts - add test for null user

**B. For Features - Identify Where to Add Code:**

```bash
# Find where similar features are implemented
rg "similar feature" --type js

# Find integration points
rg "import.*Component|from.*module"

### Feature Implementation Points

**Where to add code:**

**1. New function needed:**
- Location: `src/utils/export.ts` (new file)
- Function: `exportToCSV(data, options)`
- Based on: `src/utils/exportToJSON.ts` (similar pattern)

**2. UI Integration:**
- File: `src/components/DataTable.tsx:120`
- Add: Export button in toolbar
- Pattern: Follow existing "Download" button at line 115

**3. Hook into existing flow:**
- File: `src/components/DataTable.tsx:45`
- Add: Import new export function
- Call: On button click handler

**Code to add:**
```typescript
// In DataTable.tsx
import { exportToCSV } from '@/utils/export'

// Around line 120, add:
<Button onClick={() => exportToCSV(data, { headers: true })}>
  Export CSV
</Button>

**C. For Refactoring - Map Code Smells:**

```bash
# Find duplicated code
rg -A10 "duplicated pattern"

# Find long functions
# (Manual inspection)

### Refactoring Map

**Code smells identified:**

**1. Duplicated validation logic:**
- `src/auth/login.ts:34-50` (17 lines)
- `src/auth/register.ts:28-44` (17 lines)
- `src/auth/resetPassword.ts:15-31` (17 lines)

**Solution:**
- Extract to: `src/auth/validators.ts`
- New function: `validateUserInput(input)`
- Replace 3 duplications with function call

**2. God function:**
- `src/api/userController.ts:100-350` (250 lines!)
- Does: validation + business logic + DB + response

**Solution:**
- Split into:
  - `validateUserData()` at line 100
  - `createUser()` at line 150
  - `sendWelcomeEmail()` at line 200

Step 5: Execution Path Tracing

Trace code flow to understand full context.

### Execution Flow

**For [bug/feature]: [description]**

1. Entry: src/components/Login.tsx:89 - handleSubmit() └─> Calls: validateCredentials(username, password)

2. Flow: src/auth/validation.ts:23 - validateCredentials() └─> Calls: checkPassword(password) └─> Returns: {valid: boolean, error?: string}

3. Bug: src/auth/validation.ts:45 - checkPassword() └─> ❌ PROBLEM: Doesn't handle null password └─> FIX: Add null check at line 46

4. Result: Returns to handleSubmit, shows error

**Key functions in flow:**
- `handleSubmit()` @ Login.tsx:89 - Form submission
- `validateCredentials()` @ validation.ts:23 - Main validator
- `checkPassword()` @ validation.ts:45 - ❌ NEEDS FIX HERE

**Data transformations:**
- Input: `{username: string, password: string}`
- Validation: checks format, length, special chars
- Output: `{valid: boolean, error?: string}`

Step 6: Dependency & Impact Analysis

Understand what depends on your changes.

# Find all callers
rg "functionName\("

# Find all imports
rg "import.*ModuleName"

# Find test coverage
rg "describe.*functionName" tests/

### Dependencies & Impact

**Upstream (what calls this code):**
- `src/components/Login.tsx:89` - Login form
- `src/components/Register.tsx:67` - Registration form
- `src/api/authController.ts:120` - API endpoint

**Impact of change:**
- 🟢 Low risk - adding validation only
- All callers already handle error case
- Existing tests cover error path

**Downstream (what this calls):**
- `src/utils/crypto.ts:hashPassword()` - crypto library
- `src/models/User.ts:findByUsername()` - DB query

**Side effects:**
- None - pure validation function
- No state mutations
- No external calls

**Test coverage:**
- Current: `tests/auth/validation.test.ts`
- Need to add: test case for null password

Step 7: Modification Plan

Create concrete plan of what code to change.

### Modification Plan

**Files to modify:**

**1. PRIMARY FIX: src/auth/validation.ts**
- **Line 45-50:** Function `checkPassword()`
- **Change type:** Add null/undefined check
- **Before:**
```typescript
function checkPassword(password: string): boolean {
  return password.length >= 8  // ❌ Crashes if null
}

• After:

function checkPassword(password: string | null): boolean {
  if (!password) {  // ✅ Add null check
    return false
  }
  return password.length >= 8
}

• Risk: 🟢 Low - defensive programming

2. ADD TEST: tests/auth/validation.test.ts

• Line: After line 67 (add new test case)
• Add:

it('should return false for null password', () => {
  expect(checkPassword(null)).toBe(false)
})

3. UPDATE TYPES: src/types/auth.ts (if needed)

• Line 12: Update PasswordInput type to allow null

Files NOT to change:

• ❌ src/components/Login.tsx - already handles errors correctly
• ❌ src/api/authController.ts - no changes needed

### Step 8: Edge Cases & Implicit Requirements

Identify edge cases from code analysis.

```markdown
### Edge Cases Discovered

**From code inspection:**
- [ ] Null password: `checkPassword(null)` - FOUND in code trace
- [ ] Empty string: `checkPassword("")` - check if handled
- [ ] Very long password: `checkPassword("x".repeat(10000))` - DOS risk?
- [ ] Unicode characters: `checkPassword("パスワード")` - supported?
- [ ] SQL injection: `checkPassword("' OR 1=1--")` - sanitized?

**Integration concerns:**
- Depends on: crypto library (trusted)
- Affects: Login, Register, Reset Password flows
- Breaking change: No - only adding validation

**Performance:**
- No loops or heavy computation
- O(1) complexity
- No performance concerns

**Security:**
- Input validation ✅
- No sensitive data logged
- Follow OWASP guidelines

Step 9: Acceptance Criteria & Scope

Define concrete success criteria and scope.

### Scope Definition

**In Scope:**
1. Add null check to `checkPassword()` function
2. Add unit test for null password case
3. Verify no crashes on null input

**Out of Scope:**
1. Password strength improvements (separate issue #456)
2. UI error message improvements (separate issue #457)
3. Refactoring validation.ts (not requested)

**Complexity:** 🟢 Simple (< 2 hours)
- Single function change
- One test case addition
- Low risk change

### Acceptance Criteria

**Functional:**
- [ ] `checkPassword(null)` returns `false` (no crash)
- [ ] `checkPassword(undefined)` returns `false` (no crash)
- [ ] `checkPassword("valid")` still works correctly
- [ ] Existing tests still pass

**Quality:**
- [ ] New test added and passing
- [ ] No linting errors
- [ ] Type definitions updated
- [ ] Code follows project conventions

**Verification:**
```bash
npm test                    # All tests pass
npm run lint               # No errors
npm run type-check         # No type errors

Manual testing:

1. Open login form
2. Submit with empty password
3. Verify: No crash, shows error message

## Analysis Patterns by Issue Type

### Bug Fix Pattern

1. **Understand symptom** - Read issue description
2. **Reproduce locally** - Follow reproduction steps
3. **Explore codebase** - Find project structure
4. **Locate bug** - Trace code to root cause
5. **Identify fix point** - Exact line to change
6. **Plan changes** - What code to modify
7. **Consider side effects** - Impact analysis

### Feature Pattern

1. **Understand need** - User story, use cases
2. **Explore codebase** - Structure and conventions
3. **Find similar features** - Reference implementations
4. **Identify integration points** - Where to add code
5. **Plan new code** - What to create
6. **Map dependencies** - What it will interact with
7. **Design interface** - API, props, parameters

### Refactoring Pattern

1. **Identify code smell** - What's wrong
2. **Explore codebase** - Understand context
3. **Map all instances** - Find all occurrences
4. **Plan extraction** - New structure
5. **Ensure test coverage** - Safety net
6. **Plan incremental steps** - Small safe changes
7. **Verify no behavior change** - Tests still pass

## Output Format

Provide comprehensive analysis with code-level details:

```markdown
# 🔍 Issue Analysis: [Issue Title]

**Issue:** #[number] | **Type:** [bug/feature/refactor]
**Status:** Ready to implement

---

## Summary
[2-3 sentences: what needs to be done, what code needs to change, why]

---

## Requirements

### Issue Requirements
[What user/maintainer wants]

### Code Requirements
[What code needs to change based on exploration]

---

## Project Understanding

### Structure
[Key directories and organization]

### Conventions
[Naming, style, patterns to follow]

### Testing
[Framework, location, how to run]

---

## Code Analysis

### Entry Points
- [File:line - function/component name]

### Problem Code Identified

**File: [path]**
**Line: [number]**
**Function: [name]**

**Current code (BROKEN):**
```language
[actual problematic code]

Problem:

• [what's wrong]
• [why it breaks]

Fix needed:

[corrected code]

Execution Flow

[trace from entry to problem]

---

Modification Plan

Files to Change

1. [file path]

• Line: [number]
• Function: [name]
• Change: [specific modification]
• Before/After: [code snippets]

2. [test file]

• Add: [new test cases]

Impact Analysis

• Upstream callers: [list]
• Risk: 🟢/🟡/🔴
• Breaking change: Yes/No

---

Testing Plan

Existing tests to verify:

• [test file:description]

New tests to add:

• Test case 1: [description]
• Test case 2: [description]

Test commands:

npm test
npm test -- specific.test.js

---

Edge Cases

• [Edge case 1 - how to handle]
• [Edge case 2 - how to handle]

---

Acceptance Criteria

• [Specific, testable criterion 1]
• [Specific, testable criterion 2]
• All tests pass
• Follows CONTRIBUTING.md guidelines

---

Implementation Checklist

• Fix code at [file:line]
• Add test at [test-file]
• Run tests - all pass
• Run linter - no errors
• Manual verification

---

Next Steps

✅ Analysis complete - Ready for Phase 3: Solution Implementation

Start with:

1. [Specific first task - e.g., "Fix checkPassword() at validation.ts:45"]
2. [Second task]
3. [Third task]

## Integration with Main Framework

When invoked from main framework:

1. **Receive context:** Issue URL, type from Phase 1
2. **Execute integrated analysis:**
   - Extract requirements
   - Explore codebase structure
   - Locate exact code to change
   - Identify problems in code
   - Plan modifications
3. **Return comprehensive analysis:** Ready to implement
4. **Update tracker:** Mark Phase 2 complete
5. **Transition:** Phase 3 (Implementation) with concrete code-level plan

## Common Pitfalls

**Avoid:**

❌ **Analyzing requirements without looking at code** - Will miss context
❌ **Exploring code without understanding requirements** - Will get lost
❌ **Assuming code structure** - Always verify by reading
❌ **Stopping at "what" without finding "where"** - Need exact locations
❌ **Ignoring existing patterns** - Must follow project conventions
❌ **Not tracing full execution path** - Will miss side effects
❌ **Forgetting to check tests** - Test changes are part of solution

## Verification Before Implementation

**Before moving to Phase 3, verify:**

- [ ] Requirements fully understood
- [ ] Codebase structure mapped
- [ ] Exact modification points identified
- [ ] Problem code located (for bugs)
- [ ] Integration points clear (for features)
- [ ] All duplications found (for refactoring)
- [ ] Execution path traced
- [ ] Dependencies identified
- [ ] Test strategy planned
- [ ] Edge cases listed
- [ ] Impact assessed and acceptable

If any unclear, dig deeper or ask maintainer.