windsurf-known-pitfalls

# Windsurf Known Pitfalls ## Overview Real gotchas when using Windsurf IDE. Cascade, Supercomplete, workspace indexing, and the rules system each have behaviors that catch developers off guard. Learn from these before they catch you. ## Prerequisites - Windsurf installed and configured - Understanding of Cascade vs Supercomplete - Awareness of workspace indexing behavior ## Instructions ### Pitfall 1: Using Cascade for Simple Tasks **The mistake:** Opening Cascade (Cmd+L) to complete a single line of code. ``` BAD: Opening Cascade to write "add a console.log" → Cascade spins up full agent context, reads multiple files = slow and expensive GOOD: Use Supercomplete (Tab) for inline completions → Instant, free, no credits consumed RULE OF THUMB: - Single line / simple completion → Tab (Supercomplete) - Inline edit of selection → Cmd+I (Command) - Multi-file task / complex reasoning → Cmd+L (Cascade) ``` ### Pitfall 2: Opening Monorepo Root in Windsurf **The mistake:** Opening a 100K+ file monorepo as a single workspace. ``` BAD: windsurf ~/company-monorepo/ → Cascade indexes everything, slow context, vague suggestions GOOD: windsurf ~/company-monorepo/services/payments/ → Focused context, fast indexing, precise suggestions WHY: Cascade's context window is limited. More files = more noise. A focused workspace with 5K files gives better suggestions than a bloated workspace with 100K files. ``` ### Pitfall 3: Vague Cascade Prompts **The mistake:** Giving Cascade broa...