windsurf-advanced-troubleshooting

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 <[e-mail]>
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 ] &&