windsurf-advanced-troubleshooting

Advanced Windsurf debugging for hard-to-diagnose IDE, Cascade, and indexing issues. Use when standard troubleshooting fails, Cascade produces consistently wrong output, or investigating deep configuration problems. Trigger with phrases like "windsurf deep debug", "windsurf mystery error", "windsurf impossible to fix", "cascade keeps failing", "windsurf advanced debug".

Ir para a instalação

Repositório: jeremylongshore/claude-code-plugins-plus-skills
Última atividade na origem: 17 de julho de 2026 às 22:18
Idioma detectado do SKILL.md: inglês
Estrelas: 2.604
Forks: 378

Opções de instalação

Por padrão, está selecionado o prompt que primeiro revisa a origem. Você pode mudar para um comando direto ou baixar uma cópia local.

Revise os arquivos de origem

Leia o SKILL.md e os arquivos complementares exibidos pelo SkillsMP antes de decidir se vai instalar.

Voltar à pesquisa Voltar à instalação

name	windsurf-advanced-troubleshooting
description	Advanced Windsurf debugging for hard-to-diagnose IDE, Cascade, and indexing issues. Use when standard troubleshooting fails, Cascade produces consistently wrong output, or investigating deep configuration problems. Trigger with phrases like "windsurf deep debug", "windsurf mystery error", "windsurf impossible to fix", "cascade keeps failing", "windsurf advanced debug".
allowed-tools	Read, Grep, Bash(ls:), Bash(curl:), Bash(find:*)
version	1.11.0
license	MIT
author	Jeremy Longshore <jeremy@intentsolutions.io>
tags	["saas","windsurf","debugging","advanced","troubleshooting"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

Windsurf Advanced Troubleshooting

Overview

Deep debugging techniques for Windsurf issues that resist standard troubleshooting. Covers Cascade context corruption, indexing engine problems, extension conflicts, MCP failures, and workspace configuration debugging.

Prerequisites

Standard troubleshooting attempted (see windsurf-common-errors)
Terminal access
Understanding of Windsurf's architecture (VS Code base + Codeium AI layer)

Instructions

Step 1: Isolate Windsurf Layer vs VS Code Layer

Windsurf = VS Code + Codeium AI Layer

If the issue is:
- Editor crashes, rendering, file system → VS Code layer
- AI suggestions wrong, Cascade fails, indexing stuck → Codeium layer
- Extension not working → Extension compatibility layer

Test VS Code layer:
  windsurf --disable-extensions  # Run without extensions
  # If issue persists → VS Code layer problem

Test Codeium layer:
  # Disable Codeium: Extensions > search "codeium" > Disable
  # If issue resolves → Codeium layer problem

Step 2: Debug Cascade Context Issues

When Cascade consistently gives wrong or irrelevant suggestions:

set -euo pipefail
echo "=== Cascade Context Debug ==="

# 1. Check rules file
echo "--- .windsurfrules ---"
if [ -f .windsurfrules ]; then
  CHARS=$(wc -c < .windsurfrules)
  echo "Size: $CHARS chars (limit: 6000)"
  [ "$CHARS" -gt 6000 ] && echo "WARNING: Over limit — content truncated!"
else
  echo "MISSING — Cascade has no project context"
fi

# 2. Check workspace rules
echo "--- Workspace Rules ---"
TOTAL_RULE_CHARS=0
if [ -d .windsurf/rules ]; then
  for rule in .windsurf/rules/*.md; 
    [ -f  ] || 
    CHARS=$( -c < )
    TOTAL_RULE_CHARS=$((TOTAL_RULE_CHARS + CHARS))
    HAS_TRIGGER=$(grep -c   || )
     
  
   

   



RULES_CHARS=$( -c < .windsurfrules 2>/dev/null ||  0)
GLOBAL_CHARS=$( -c < ~/.windsurf/global_rules.md 2>/dev/null ||  0)
TOTAL=$((RULES_CHARS + GLOBAL_CHARS))
 
 
[  -gt 12000 ] &&  


 
MEMORY_DIR=
 [ -d  ]; 
  MEMORY_COUNT=$(find  - f |  -l)
   
  [  -gt 50 ] &&

set -euo pipefail
echo "=== Indexing Debug ==="

# Count files that would be indexed
TOTAL_FILES=$(find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' | wc -l)
echo "Total files (excluding node_modules, .git): $TOTAL_FILES"

# Check for large files that slow indexing
echo "--- Large files (>1MB, not in node_modules) ---"
find . -type f -size +1M -not -path '*/node_modules/*' -not -path '*/.git/*' | head -10

# Check .codeiumignore effectiveness
if [ -f .codeiumignore ]; then
  echo "--- .codeiumignore patterns ---"
  wc -l < .codeiumignore
  echo "patterns defined"
else
  echo "WARNING: No .codeiumignore — indexing everything"
fi

# Recommendations
if [ "$TOTAL_FILES" -gt 10000 ]; then
  echo ""
  echo "RECOMMENDATION: >10K files. Open a subdirectory instead of root."
  echo "RECOMMENDATION: Add more patterns to .codeiumignore"
fi

set -euo pipefail
echo "=== Extension Conflict Check ==="

# List all installed extensions
windsurf --list-extensions 2>/dev/null | while read ext; do
  # Check for known conflicts
  case "$ext" in
    *copilot*|*tabnine*|*cody*|*intellicode*|*aws-toolkit*codewhisperer*)
      echo "CONFLICT: $ext — competes with Supercomplete/Cascade"
      ;;
    *remote*|*liveshare*|*container*)
      echo "OK: $ext — compatible but may affect performance"
      ;;
    *)
      echo "OK: $ext"
      ;;
  esac
done

echo ""
echo "Resolution: Disable conflicting extensions or run:"
echo "  windsurf --disable-extensions  # Test in clean mode"

set -euo pipefail
echo "=== MCP Debug ==="

MCP_CONFIG="$HOME/.codeium/windsurf/mcp_config.json"
if [ -f "$MCP_CONFIG" ]; then
  echo "MCP config exists"
  # Validate JSON
  python3 -c "import json; json.load(open('$MCP_CONFIG'))" 2>&1 && echo "JSON: valid" || echo "JSON: INVALID"

  # Check each server command
  python3 -c "
import json
config = json.load(open('$MCP_CONFIG'))
for name, server in config.get('mcpServers', {}).items():
    cmd = server.get('command', 'N/A')
    print(f'  {name}: command={cmd}')
  "
else
  echo "No MCP config at $MCP_CONFIG"
fi

## Progressive Reset (least to most destructive)

1. Restart Cascade
   Command Palette > "Cascade: Restart"

2. Reset Indexing
   Command Palette > "Codeium: Reset Indexing"

3. Reload Window
   Cmd/Ctrl+Shift+P > "Developer: Reload Window"

4. Clear Memories
   Delete contents of ~/.codeium/windsurf/memories/

5. Reset All Codeium State
   Close Windsurf
   rm -rf ~/.codeium/windsurf/cache/
   Reopen Windsurf (re-indexes, re-authenticates)

6. Clean Install
   Uninstall Windsurf
   rm -rf ~/.codeium/
   rm -rf ~/.config/Windsurf/  # Linux
   # or: rm -rf ~/Library/Application Support/Windsurf/  # macOS
   Reinstall from windsurf.com/download

Issue	Cause	Solution
Cascade gives contradictory advice	Conflicting memories	Clear old memories
Rules ignored	Over 12K combined chars	Trim rules, check total budget
Wrong file suggestions	Stale index	Reset indexing
Slow after update	Extension incompatibility	Test with `--disable-extensions`
MCP tools missing	Config JSON invalid	Validate with python3 json parser
Everything broken	Corrupted state	Progressive reset (Step 6)

echo "WS files: $(find . -not -path '*/node_modules/*' -not -path '*/.git/*' -type f | wc -l) | Rules: $(wc -c < .windsurfrules 2>/dev/null || echo 0)c | Ignore: $(wc -l < .codeiumignore 2>/dev/null || echo 0) patterns | Exts: $(windsurf --list-extensions 2>/dev/null | wc -l)"

Attach:
1. Output from all diagnostic scripts above
2. Debug bundle from windsurf-debug-bundle
3. Exact prompts that produce wrong results
4. Expected vs actual Cascade behavior