@tinkcarlos/skillora 0.2.0

package/.claude/skills/bug-fixing/references/impact-analysis.md

@@ -0,0 +1,511 @@
+# Impact Analysis Guide
+
+> Maps blast radius across code, modules, APIs, and infrastructure to prevent regressions.
+
+## Table of Contents
+
+- [Why 5 Layers?](#why-5-layers)
+- [🔴 Multi-Environment Configuration Analysis (MANDATORY)](#-multi-environment-configuration-analysis-mandatory)
+- [Layer-by-Layer Analysis](#layer-by-layer-analysis)
+  - [Layer 0: Bug Location](#layer-0-bug-location)
+  - [Layer 1: Direct Callers](#layer-1-direct-callers)
+  - [Layer 2: Indirect Callers](#layer-2-indirect-callers)
+  - [Layer 3: Cross-Module Dependencies](#layer-3-cross-module-dependencies)
+  - [Layer 4: External Interfaces](#layer-4-external-interfaces)
+  - [Layer 5: System-Wide Impact](#layer-5-system-wide-impact)
+- [Impact Analysis Template](#impact-analysis-template)
+- [Tools for Impact Analysis](#tools-for-impact-analysis)
+
+How to trace all code affected by a bug or fix through 5 layers.
+
+---
+
+## Why 5 Layers?
+
+| Layer | What it Covers | Why Important |
+|-------|---------------|---------------|
+| 0 | Bug location | Direct fix location |
+| 1 | Direct callers | Immediate code using buggy code |
+| 2 | Indirect callers | Code using Layer 1 |
+| 3 | Cross-module | Other modules affected |
+| 4 | External interfaces | APIs, UIs, contracts |
+| 5 | System-wide | Infrastructure, monitoring |
+
+Missing any layer can lead to:
+- Incomplete fix
+- New bugs introduced
+- Unexpected side effects
+- Production incidents
+
+---
+
+## 🔴 Multi-Environment Configuration Analysis (MANDATORY)
+
+> **Critical**: Configuration bugs are among the most common causes of "fix doesn't work" scenarios. ALWAYS analyze ALL environments before declaring a fix complete.
+
+### Why This Matters
+
+| Scenario | Problem | Result |
+|----------|---------|--------|
+| Fix only in `.env` | Dev mode uses `.env.development` | Bug persists in dev |
+| Fix only in prod config | Staging uses different config | Bug appears in staging |
+| Fix in code, not config | Config overrides code behavior | Fix has no effect |
+| Fix in one startup script | Multiple scripts exist | Some modes still broken |
+
+### 🔴 Environment Configuration Checklist (MANDATORY)
+
+**Before declaring ANY configuration-related fix complete:**
+
+```markdown
+## Environment Configuration Impact
+
+### 1. Environment Files Audit
+| File | Exists | Needs Update | Updated |
+|------|--------|--------------|---------|
+| `.env` | [ ] | [ ] | [ ] |
+| `.env.local` | [ ] | [ ] | [ ] |
+| `.env.development` | [ ] | [ ] | [ ] |
+| `.env.development.local` | [ ] | [ ] | [ ] |
+| `.env.test` | [ ] | [ ] | [ ] |
+| `.env.staging` | [ ] | [ ] | [ ] |
+| `.env.production` | [ ] | [ ] | [ ] |
+| `.env.production.local` | [ ] | [ ] | [ ] |
+
+### 2. Startup Scripts Audit
+| Script | Mode | Config Used | Needs Update |
+|--------|------|-------------|--------------|
+| `npm run dev` | Development | ? | [ ] |
+| `npm run start` | Production | ? | [ ] |
+| `npm run build` | Build | ? | [ ] |
+| `dev.bat` / `dev.sh` | Development | ? | [ ] |
+| `start.bat` / `start.sh` | Production | ? | [ ] |
+| Docker Compose | Various | ? | [ ] |
+
+### 3. Configuration Loading Order
+Document how your app loads configuration:
+1. Default values in code
+2. `.env` file (base)
+3. `.env.[mode]` file (mode-specific)
+4. `.env.local` file (local overrides)
+5. Environment variables (runtime)
+6. Command-line arguments
+
+### 4. Verification Commands
+| Environment | Command | Expected Result |
+|-------------|---------|-----------------|
+| Development | `npm run dev` | [ ] Works |
+| Production | `npm run start` | [ ] Works |
+| Test | `npm run test` | [ ] Works |
+| Docker | `docker-compose up` | [ ] Works |
+```
+
+### Common Environment Configuration Patterns
+
+#### Pattern 1: Node.js / Vite / React
+
+```
+Project Root/
+├── .env                    # Base config (all modes)
+├── .env.local              # Local overrides (gitignored)
+├── .env.development        # Development mode
+├── .env.development.local  # Dev local overrides
+├── .env.production         # Production mode
+├── .env.production.local   # Prod local overrides
+└── .env.test               # Test mode
+```
+
+**Loading Priority** (Vite example):
+1. `.env` (always loaded)
+2. `.env.local` (always loaded, gitignored)
+3. `.env.[mode]` (mode-specific)
+4. `.env.[mode].local` (mode-specific, gitignored)
+
+#### Pattern 2: Python / Django / Flask
+
+```
+Project Root/
+├── .env                    # Base config
+├── config/
+│   ├── settings/
+│   │   ├── base.py         # Base settings
+│   │   ├── development.py  # Dev settings
+│   │   ├── production.py   # Prod settings
+│   │   └── test.py         # Test settings
+```
+
+#### Pattern 3: Java / Spring Boot
+
+```
+src/main/resources/
+├── application.yml              # Base config
+├── application-dev.yml          # Development profile
+├── application-prod.yml         # Production profile
+├── application-test.yml         # Test profile
+└── application-local.yml        # Local overrides
+```
+
+### 🔴 Multi-Environment Fix Protocol
+
+When fixing a configuration-related bug:
+
+```
+1. IDENTIFY all environment files
+   └─→ grep -r "CONFIG_KEY" . --include="*.env*" --include="*.yml" --include="*.json"
+
+2. IDENTIFY all startup scripts
+   └─→ Check package.json scripts, .bat/.sh files, docker-compose.yml
+
+3. DETERMINE which environments are affected
+   └─→ Map: startup script → config file → affected variable
+
+4. APPLY fix to ALL relevant files
+   └─→ Don't assume "production only" - check dev, test, staging
+
+5. VERIFY in ALL modes
+   └─→ Run each startup script and confirm fix works
+
+6. DOCUMENT in bug-records.md
+   └─→ List all files modified and environments impacted
+```
+
+### Quick Commands for Environment Analysis
+
+```bash
+# Find all env files
+find . -name ".env*" -o -name "*.env" 2>/dev/null
+
+# Find all config files
+find . -name "config.*" -o -name "*.config.*" -o -name "settings.*" 2>/dev/null
+
+# Search for a config key across all files
+grep -rn "YOUR_CONFIG_KEY" . --include="*.env*" --include="*.yml" --include="*.json" --include="*.ts" --include="*.js"
+
+# Find startup scripts
+grep -rn "NODE_ENV\|VITE_\|REACT_APP_" . --include="*.sh" --include="*.bat" --include="*.ps1" --include="package.json"
+
+# Check which env file is loaded in dev mode
+npm run dev 2>&1 | head -20  # Look for "Loading env from..."
+```
+
+---
+
+## Layer-by-Layer Analysis
+
+### Layer 0: Bug Location
+
+Identify the exact location of the bug:
+
+```markdown
+## Layer 0: Bug Location
+
+### File Analysis
+| Attribute | Value |
+|-----------|-------|
+| File | `src/services/user-service.ts` |
+| Function | `getUserById()` |
+| Line | 42-45 |
+| Bug Type | Null reference |
+
+### Code Snapshot
+```typescript
+// Line 42-45
+async function getUserById(id: string): Promise<User> {
+  const user = await this.repository.find(id);
+  return user; // BUG: Can return null, not handled
+}
+```
+
+### Bug Behavior
+- **Input**: Any user ID
+- **Trigger**: User ID doesn't exist in database
+- **Result**: Returns null instead of User
+```
+
+### Layer 1: Direct Callers
+
+Find all code that directly uses the buggy function:
+
+```bash
+# Find all imports/uses
+grep -r "getUserById" --include="*.ts" --include="*.tsx"
+
+# Use IDE "Find References" feature
+# In VSCode: Right-click → Find All References
+```
+
+```markdown
+## Layer 1: Direct Callers
+
+| File | Function | Line | How Used | Impact |
+|------|----------|------|----------|--------|
+| profile-service.ts | getProfile() | 23 | Get user for profile | Will crash |
+| order-service.ts | getOrderOwner() | 15 | Get user for order | Will crash |
+| auth-service.ts | validateSession() | 88 | Validate user exists | Wrong validation |
+| admin-service.ts | getUserDetails() | 42 | Admin view user | Will crash |
+
+### Caller Code Examples
+
+**profile-service.ts:23**
+```typescript
+async function getProfile(userId: string) {
+  const user = await userService.getUserById(userId);
+  return {
+    name: user.name, // CRASH if user is null
+    email: user.email,
+  };
+}
+```
+```
+
+### Layer 2: Indirect Callers
+
+Find code that calls Layer 1 functions:
+
+```markdown
+## Layer 2: Indirect Callers
+
+### profile-service.ts callers:
+| File | Function | Line | Impact |
+|------|----------|------|--------|
+| ProfilePage.tsx | useProfile() | 12 | UI crash |
+| settings-handler.ts | getSettings() | 34 | API 500 |
+
+### order-service.ts callers:
+| File | Function | Line | Impact |
+|------|----------|------|--------|
+| OrderList.tsx | renderOrder() | 56 | List renders wrong |
+| invoice-generator.ts | generate() | 78 | Invoice fails |
+
+### Total Layer 2 Impact
+- 4 UI components may crash
+- 2 API handlers may return 500
+- 1 background job may fail
+```
+
+### Layer 3: Cross-Module Dependencies
+
+Identify other modules that depend on affected code:
+
+```markdown
+## Layer 3: Cross-Module Impact
+
+### Module Dependency Map
+```
+[User Module]
+    ↓ exports getUserById
+[Profile Module] ────→ [Settings Module]
+    │                      │
+    ↓                      ↓
+[Order Module] ←───── [Invoice Module]
+    │
+    ↓
+[Notification Module]
+```
+
+### Impact by Module
+| Module | Dependency | Direct Impact | Cascading Impact |
+|--------|------------|---------------|------------------|
+| Profile | User.getUserById | Profile crashes | Settings unavailable |
+| Order | User.getUserById | Order view broken | Invoice generation fails |
+| Notification | Order.getOrderOwner | Notification errors | User not notified |
+| Analytics | Profile.getProfile | Analytics incorrect | Reports wrong |
+```
+
+### Layer 4: External Interfaces
+
+Check APIs, webhooks, and contracts:
+
+```markdown
+## Layer 4: External Interface Impact
+
+### REST API Endpoints
+| Endpoint | Method | Uses | Current Behavior | Should Be |
+|----------|--------|------|------------------|-----------|
+| /api/users/:id | GET | getUserById | Returns null, 200 | Return 404 |
+| /api/profile/:id | GET | getProfile | Crashes, 500 | Return 404 |
+| /api/orders | GET | getOrderOwner | Shows null name | Handle gracefully |
+
+### GraphQL
+| Query | Uses | Impact |
+|-------|------|--------|
+| user(id: ID!) | getUserById | Returns null violating schema |
+| profile(id: ID!) | getProfile | Resolver crashes |
+
+### Webhooks
+| Event | Payload | Impact |
+|-------|---------|--------|
+| user.updated | User data | May send null data |
+| order.created | Order with user | May send null user |
+
+### Third-party Integrations
+| Integration | Data Shared | Impact |
+|-------------|-------------|--------|
+| Stripe | User email | May pass null |
+| SendGrid | User name | Email has blank name |
+| Analytics | User ID | Events have null user |
+```
+
+### Layer 5: System-Wide Impact
+
+Consider infrastructure and operations:
+
+```markdown
+## Layer 5: System-Wide Impact
+
+### Database
+| Concern | Impact | Mitigation |
+|---------|--------|------------|
+| Data integrity | None | Bug doesn't modify data |
+| Query patterns | None | No change needed |
+
+### Cache
+| Cache | Impact | Action Needed |
+|-------|--------|---------------|
+| User cache | May cache null | Add null check before cache |
+| Profile cache | May serve stale | Clear on user delete |
+
+### Message Queue
+| Queue | Impact | Action Needed |
+|-------|--------|---------------|
+| email-queue | May have null user | Add validation |
+| notification-queue | May fail to process | Add error handling |
+
+### Logging & Monitoring
+| System | Impact | Action |
+|--------|--------|--------|
+| Error logs | Spike in null errors | Expected, will resolve |
+| Metrics | Error rate increase | Set up alert |
+| APM | Transaction failures | Expected pattern |
+
+### Infrastructure
+| Component | Impact | Notes |
+|-----------|--------|-------|
+| Load balancer | None | N/A |
+| CDN | None | N/A |
+| Database replicas | None | N/A |
+```
+
+---
+
+## Impact Analysis Template
+
+```markdown
+# Impact Analysis: [Bug ID]
+
+## Summary
+| Metric | Count |
+|--------|-------|
+| Files potentially affected | X |
+| Functions affected | X |
+| API endpoints affected | X |
+| UI components affected | X |
+| External integrations affected | X |
+
+## Layer 0: Bug Location
+[Complete Layer 0 analysis]
+
+## Layer 1: Direct Callers
+[Complete Layer 1 analysis]
+
+## Layer 2: Indirect Callers
+[Complete Layer 2 analysis]
+
+## Layer 3: Cross-Module
+[Complete Layer 3 analysis]
+
+## Layer 4: External Interfaces
+[Complete Layer 4 analysis]
+
+## Layer 5: System-Wide
+[Complete Layer 5 analysis]
+
+## Fix Impact Assessment
+
+### Fix Scope
+| Scope | Description |
+|-------|-------------|
+| Minimum | Fix only Layer 0 |
+| Recommended | Fix Layer 0-1 |
+| Complete | Fix all layers |
+
+### Recommended Changes
+| Layer | File | Change | Priority |
+|-------|------|--------|----------|
+| 0 | user-service.ts | Add null check | Critical |
+| 1 | profile-service.ts | Handle null user | High |
+| 4 | user-controller.ts | Return 404 | High |
+| 3 | notification-module | Validate user | Medium |
+
+### Testing Requirements
+| Layer | Tests Needed |
+|-------|-------------|
+| 0 | Unit test for null case |
+| 1 | Unit tests for callers |
+| 2 | Integration tests |
+| 4 | API tests |
+| 5 | Smoke tests |
+
+## Risk Assessment
+
+### If Only Layer 0 Fixed
+- [Risk 1]: Callers still don't handle null
+- [Risk 2]: Error message not user-friendly
+
+### If Complete Fix Applied
+- [Benefit 1]: All callers handle gracefully
+- [Benefit 2]: Users see proper 404 messages
+
+### Recommendation
+[Recommended scope and justification]
+```
+
+---
+
+## Tools for Impact Analysis
+
+### Code Search
+
+```bash
+# Find all references to a function
+grep -r "getUserById" --include="*.ts" --include="*.tsx" src/
+
+# Find imports of a module
+grep -r "from.*user-service" --include="*.ts" src/
+
+# Use AST-based search for accuracy
+npx ts-prune # Find unused exports
+```
+
+### Dependency Graphs
+
+```bash
+# Generate dependency graph
+npx madge --image deps.png src/
+
+# Find circular dependencies
+npx madge --circular src/
+
+# Python: pydeps
+pip install pydeps
+pydeps src/services/user_service.py
+```
+
+### IDE Features
+
+- **Find All References** (F12 / Shift+F12)
+- **Call Hierarchy** (Ctrl+Shift+H)
+- **Type Hierarchy**
+- **Find Usages**
+
+### Git Analysis
+
+```bash
+# Find recent changes to file
+git log --oneline -20 src/services/user-service.ts
+
+# Find who else works with this code
+git log --format='%an' src/services/user-service.ts | sort | uniq -c
+
+# Find related files changed together
+git log --name-only --format='' -- src/services/user-service.ts | sort | uniq -c | sort -rn
+```