Crisis Debugging Advisor

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

# 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

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

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

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

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

// 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 custom logic

Pattern 4: "Performance Degraded to Unusable"

Root Causes:

• Memory leaks from AI code
• Inefficient re-renders
• Large data handling issues

Debugging Steps:

1. Performance tab - identify bottlenecks
2. Memory tab - check for leaks
3. Profile component updates - Vue DevTools
4. Test with smaller datasets

Emergency Recovery Procedures

Procedure 1: Safe Mode Development

When app is completely broken:

# 1. Create minimal working version
mkdir crisis-recovery
cd crisis-recovery

# 2. Copy only essential files
# - package.json
# - vite.config.js (minimal)
# - index.html (minimal)
# - src/main.ts (basic Vue setup)
# - src/App.vue (empty template)

# 3. Build incrementally
# Start with blank app, add one feature at a time

Procedure 2: Git Bisect for Problem Isolation

# Start binary search through git history
git bisect start
git bisect bad HEAD  # Current version is broken
git bisect good v1.0-stable  # Last known good version

# Git will checkout a commit for testing
npm run dev
# Test manually
git bisect good  # or git bisect bad

# Continue until problem commit is identified

Procedure 3: Component Isolation Testing

<!-- Create TestComponent.vue for isolation -->
<template>
  <div class="test-component">
    <h2>Component Test: {{ componentName }}</h2>
    <button @click="testClick">Test Click</button>
    <p>Clicks: {{ clickCount }}</p>
    <p v-if="error" class="error">Error: {{ error }}</p>
  </div>
</template>

<script setup>
import { ref } from 'vue'

const props = defineProps({
  componentName: String
})

const clickCount = ref(0)
const error = ref(null)

const testClick = () => {
  try {
    clickCount.value++
    // Add component-specific test logic here
  } catch (e) {
    error.value = e.message
  }
}
</script>

Communication Protocol with AI Tools

When Reporting Issues to AI:

Bad Report: "The app is broken" Good Report:

ISSUE REPORT:
- Feature: Task creation in BoardView
- Steps to Reproduce:
  1. Navigate to BoardView
  2. Click "Add Task" button
  3. Type "Test Task"
  4. Press Enter
- Expected Result: Task appears in "Planned" swimlane
- Actual Result: Button click does nothing, no console errors
- Browser Console: [Paste exact console output]
- Environment: Chrome 120, Vue 3.4.0, Pinia 2.1.0

When Requesting AI Assistance:

Template:

CONTEXT: I'm in a crisis debugging situation. Previous AI suggestions claimed success but functionality is still broken.

CURRENT STATUS:
- Working: [List what actually works]
- Broken: [List what's broken with specific failures]
- Last Working Version: [git tag or description]
- Recent Changes: [List recent modifications]

REQUESTED ACTION:
- [Specific, measurable request]
- Success Criteria: [How I'll verify it works]
- Verification Plan: [How I'll test before accepting]

CONSTRAINTS:
- I will manually verify in browser before accepting
- I need incremental changes, not wholesale rewrites
- If you're uncertain, please say so rather than guessing

Prevention Strategies

1. Trust-but-Verify Development

• Never accept AI claims at face value
• Always create success criteria before implementing
• Test manually in browser every single change
• Maintain a working baseline at all times

2. Incremental Feature Development

• One feature at a time, fully tested
• Commit after each working feature
• Tag releases with descriptive names
• Maintain rollback capability

3. Automated Verification Setup

// Create automated smoke tests
const smokeTests = {
  testBasicFunctionality: async () => {
    // Test core app functionality
    await page.goto('http://localhost:5546')
    await expect(page.locator('#app')).toBeVisible()
    await expect(page.locator('[data-testid="task-create"]')).toBeVisible()
  },

  testDataPersistence: async () => {
    // Test that data saves and loads
    await page.fill('[data-testid="task-input"]', 'Test Task')
    await page.press('[data-testid="task-input"]', 'Enter')
    await page.reload()
    await expect(page.locator('text=Test Task')).toBeVisible()
  }
}

Quick Reference: Crisis Action Plan

When Everything Feels Broken:

1. STOP - Don't make more changes
2. BREATHE - This is solvable with systematic approach
3. ASSESS - Use Reality Check Matrix (30 minutes)
4. ISOLATE - Binary search through recent changes (2 hours)
5. REBUILD - Start from working foundation (4-8 hours)
6. VERIFY - Every change manually tested
7. PREVENT - Implement trust-but-verify protocol

Remember: Your manual testing is the ground truth. AI tools are assistants, not authorities. If it doesn't work in the browser, it's broken - regardless of what AI claims.

Created by: Crisis Debugging Research Team Based on: Systematic debugging methodologies, AI verification protocols, and real-world crisis recovery scenarios Last Updated: 2025-11-09

MANDATORY USER VERIFICATION REQUIREMENT

Policy: No Fix Claims Without User Confirmation

CRITICAL: Before claiming ANY issue, bug, or problem is "fixed", "resolved", "working", or "complete", the following verification protocol is MANDATORY:

Step 1: Technical Verification

• Run all relevant tests (build, type-check, unit tests)
• Verify no console errors
• Take screenshots/evidence of the fix

Step 2: User Verification Request

REQUIRED: Use the AskUserQuestion tool to explicitly ask the user to verify the fix:

"I've implemented [description of fix]. Before I mark this as complete, please verify:
1. [Specific thing to check #1]
2. [Specific thing to check #2]
3. Does this fix the issue you were experiencing?

Please confirm the fix works as expected, or let me know what's still not working."

Step 3: Wait for User Confirmation

• DO NOT proceed with claims of success until user responds
• DO NOT mark tasks as "completed" without user confirmation
• DO NOT use phrases like "fixed", "resolved", "working" without user verification

Step 4: Handle User Feedback

• If user confirms: Document the fix and mark as complete
• If user reports issues: Continue debugging, repeat verification cycle

Prohibited Actions (Without User Verification)

• Claiming a bug is "fixed"
• Stating functionality is "working"
• Marking issues as "resolved"
• Declaring features as "complete"
• Any success claims about fixes

Required Evidence Before User Verification Request

1. Technical tests passing
2. Visual confirmation via Playwright/screenshots
3. Specific test scenarios executed
4. Clear description of what was changed

Remember: The user is the final authority on whether something is fixed. No exceptions.