crisis-debugging-advisor

What this skill does

# Crisis Debugging Advisor

**Category**: Development Strategy & Debugging Methodology
**Target Users**: Developers feeling stuck with countless app issues and AI false success claims
**Primary Goal**: Systematic approach to regain control when AI assistants claim success but reality shows broken functionality

## When to Use This Skill

Use this advisor when you experience:
- ✅ **"Claude Code keeps claiming success but everything is still broken"**
- ✅ **Feeling overwhelmed with countless issues that make the app unusable**
- ✅ **AI tools reporting success while manual testing shows failures**
- ✅ **Not knowing what your next step should be**
- ✅ **App completely broken after AI-assisted development**
- ✅ **Loss of trust in AI-generated solutions**
- ✅ **Complex Vue.js/React application state management issues**

## Core Philosophy: Reality-First Verification

**Golden Rule**: **Manual verification ALWAYS trumps AI claims. If it doesn't work in browser, it's broken. Period.**

This skill implements the **Reality-First Verification Protocol (RFVP)**:
1. **AI suggestions are hypotheses, not facts**
2. **Browser testing is ground truth**
3. **Systematic verification over blind trust**
4. **Incremental validation over wholesale changes**

## The 4-Phase Crisis Debugging Framework

### Phase 1: Situation Assessment & Reality Check (15-30 minutes)

**Objective**: Establish ground truth of what actually works vs. what's broken

```bash
# Step 1: Create a Reality Check Matrix
# Create this file manually in your project root:
REALITY_CHECK.md

# Structure:
## Core Functionality Status
- [ ] App loads without console errors
- [ ] Basic task creation works
- [ ] Data persistence (IndexedDB) works
- [ ] Navigation between views works
- [ ] Timer functionality works
- [ ] Canvas interactions work

## AI Claim vs Reality Test
- [ ] AI: "Fixed X" → Manual Test: [ ] Actually works
- [ ] AI: "Implemented Y" → Manual Test: [ ] Actually works
```

**Immediate Actions**:
1. **Open browser dev tools** - Clear all errors first
2. **Test ONE core feature** - Pick the most critical functionality
3. **Document exact failure points** - Not "broken" but "task creation fails at step 3"
4. **Take screenshots** - Visual evidence of failures

### Phase 2: Binary Search Debugging (2-4 hours)

**Objective**: Systematically isolate the root cause using divide-and-conquer

**Binary Search Protocol**:
1. **Identify last known working state** (git tag, backup, or memory)
2. **List all major changes since then**
3. **Test changes in chunks** (half at a time)
4. **Continue halving until problem isolated**

```bash
# Implementation Example:
git log --oneline -20  # List last 20 changes
# Test changes 1-10: npm run dev + manual test
# If broken: test changes 1-5
# If working: test changes 6-10
# Continue until single problematic commit identified
```

**Vue.js Specific Binary Search**:
1. **Test stores in isolation** - Disable Pinia stores one by one
2. **Test components in isolation** - Comment out components systematically
3. **Test composables** - Remove custom composables progressively
4. **Test routes** - Disable routes one by one

### Phase 3: Ground-Up Reconstruction (4-8 hours)

**Objective**: Build from a working foundation, verifying each layer

**Layer-by-Layer Verification**:
```javascript
// Layer 1: Core App Bootstrap
const coreAppTest = {
  test: "Does Vue app mount without errors?",
  verify: () => {
    // Remove all components, just test app mounting
    createApp(App).mount('#app')
  }
}

// Layer 2: Basic State Management
const storeTest = {
  test: "Does basic Pinia store work?",
  verify: () => {
    // Test simplest store with basic counter
    const testStore = defineStore('test', () => {
      const count = ref(0)
      return { count }
    })
  }
}

// Layer 3: Basic Component
const componentTest = {
  test: "Does simplest component render?",
  verify: () => {
    // Test component with just <div>Hello World</div>
  }
}
```

**Reconstruction Order**:
1. **Blank Vue app** - Just mounting, no features
2. **Basic routing** - Single static route
3. **Simplest Pinia store** - Basic counter or boolean
4. **One basic component** - Static content only
5. **Add complexity incrementally** - One feature at a time

### Phase 4: AI Trust Rebuilding & New Protocol (Ongoing)

**Objective**: Establish systematic AI verification workflow

**AI Verification Protocol**:
```
FOR EACH AI SUGGESTION:
1. AI provides code change
2. BEFORE implementing: Create success test criteria
3. Implement change
4. MANUAL verification in browser
5. IF works: Accept and document
6. IF fails: Reject and report back to AI with exact failure
```

**Success Test Criteria Template**:
```javascript
// Before accepting AI suggestion:
const successCriteria = {
  feature: "Task Creation",
  steps: [
    "Navigate to BoardView",
    "Click 'Add Task' button",
    "Type 'Test Task'",
    "Press Enter",
    "Task appears in list"
  ],
  expectedResults: [
    "No console errors",
    "Task persists on refresh",
    "Task appears in correct swimlane"
  ]
}
```

## Crisis Debugging Toolset

### Essential Verification Scripts

Create these in your project for systematic testing:

**1. Core Functionality Test** (`test-core.js`):
```javascript
// Run in browser console to test basic functionality
const coreTests = {
  testAppMount: () => {
    return document.querySelector('#app') !== null
  },
  testNoConsoleErrors: () => {
    // Monitor console for 30 seconds
    return console.errorCount === 0
  },
  testBasicStore: () => {
    // Test if Pinia stores are accessible
    try {
      const store = useTaskStore()
      return store !== undefined
    } catch {
      return false
    }
  }
}
```

**2. Store State Validator** (`validate-stores.js`):
```javascript
// Run to validate all store states
const validateStores = () => {
  const stores = ['tasks', 'canvas', 'timer', 'ui']
  const results = {}

  stores.forEach(storeName => {
    try {
      const store = useStore(storeName)
      results[storeName] = {
        accessible: true,
        hasData: Object.keys(store.$state).length > 0,
        errors: null
      }
    } catch (error) {
      results[storeName] = {
        accessible: false,
        hasData: false,
        errors: error.message
      }
    }
  })

  return results
}
```

### Debugging Environment Setup

**Browser DevTools Configuration**:
1. **Console Panel**: Clear all errors first
2. **Network Panel**: Monitor failed API/IndexedDB calls
3. **Vue DevTools**: Install and inspect component tree
4. **Performance Panel**: Check for memory leaks/freezes

**Essential Browser Extensions**:
- Vue DevTools (for Vue.js apps)
- React DevTools (for React apps)
- Redux DevTools (if using Redux)
- IndexedDB Viewer (Chrome extension)

## Common Crisis Patterns & Solutions

### Pattern 1: "AI Claims Success, But App Won't Load"

**Root Causes**:
- Syntax errors in AI-generated code
- Missing imports/dependencies
- Broken component references

**Debugging Steps**:
1. **Check browser console** for syntax errors
2. **Validate imports** - all referenced files exist
3. **Test component mounting** - comment out AI components
4. **Rollback to working version** and implement manually

### Pattern 2: "State Management Completely Broken"

**Root Causes**:
- Conflicting store mutations
- Broken reactivity chains
- IndexedDB corruption

**Debugging Steps**:
1. **Clear browser storage** (IndexedDB, localStorage)
2. **Test stores in isolation** - disable all but one
3. **Check Pinia DevTools** for state anomalies
4. **Reset to default store state** manually

### Pattern 3: "Canvas/Interactive Elements Dead"

**Root Causes**:
- Event handler conflicts
- CSS z-index issues
- Vue Flow integration problems

**Debugging Steps**:
1. **Test basic click events** on simple elements
2. **Check CSS for pointer-events: none**
3. **Isolate canvas component** - remove all other elements
4. **Test Vue Flow basic functionality** without cust