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 broad, unscoped instructions.

BAD: "Refactor the codebase to use TypeScript"
→ Cascade may try to convert EVERY file at once, breaking everything

BAD: "Add validation to the API"
→ Which API? Which endpoints? What validation rules?

GOOD: "Convert src/utils/api.js to TypeScript. Add proper types for
all function parameters and return values. Don't change other files."

GOOD: "In src/routes/users.ts, add zod validation for the POST /users
endpoint. Validate email format, name length (2-50 chars), and role
must be 'admin' or 'user'. Return 400 with field-level errors."

Pitfall 4: Accepting Changes Without Review

The mistake: Accepting all Cascade changes without reading the diffs.

BAD: Cascade modifies 12 files → "Accept All" → broken tests
→ Cascade may have changed shared utilities, removed error handling,
  or introduced dependencies on APIs that don't exist

GOOD:
1. Read Cascade's explanation of what it changed
2. Review each file diff in the Cascade output
3. Check for: removed error handling, new imports, changed signatures
4. Run tests BEFORE committing
5. Use revert button if any file looks wrong

Pitfall 5: Not Checkpointing Before Cascade

The mistake: Running Cascade on a dirty working tree without a Git checkpoint.

BAD: Uncomitted changes + Cascade edits = impossible to separate
→ Can't tell what was your work vs what Cascade changed
→ Can't revert Cascade changes without losing your work

GOOD: git add -A && git commit -m "checkpoint: before cascade"
→ Clean separation between your work and Cascade's
→ Easy revert: git checkout -- .

Pitfall 6: Conflicting AI Extensions

The mistake: Running GitHub Copilot alongside Windsurf.

KNOWN CONFLICTS:
- GitHub Copilot — conflicts with Supercomplete
  Symptoms: duplicate suggestions, wrong completions, slow editor

- TabNine — conflicts with Supercomplete
  Symptoms: competing inline suggestions

- Cody (Sourcegraph) — conflicts with Cascade
  Symptoms: multiple AI panels, context confusion

FIX: Disable competing extensions
Settings > Extensions > search "copilot" > Disable

Pitfall 7: Ignoring .windsurfrules Character Limits

The mistake: Writing a 20,000 character .windsurfrules file.

LIMITS:
- .windsurfrules: 6,000 characters max
- Global rules (global_rules.md): 6,000 characters max
- Combined total: 12,000 characters max
- Individual workspace rules (.windsurf/rules/*.md): 12,000 chars each

WHAT HAPPENS WHEN EXCEEDED:
- Content is SILENTLY TRUNCATED
- Global rules take priority over workspace rules
- You won't get an error — just missing context

FIX: Keep .windsurfrules concise (stack, patterns, don'ts)
Move detailed rules to .windsurf/rules/ with trigger modes

Pitfall 8: Long Cascade Conversations

The mistake: Using a single Cascade conversation for hours of work.

BAD: 50-message Cascade conversation spanning multiple topics
→ Context window fills up, Cascade "forgets" early context
→ Suggestions become inconsistent or contradictory

GOOD: One task per Cascade session
→ Click + icon to start new conversation for each new task
→ Clean context = better suggestions
→ Use Memories for facts that should persist across sessions

Pitfall 9: Pasting Secrets into Cascade

The mistake: Sharing API keys or credentials in Cascade chat.

BAD: "My API key is sk-abc123def456, why isn't auth working?"
→ Secret is now in Cascade's context, may appear in suggestions later

GOOD: "I'm getting auth errors with the API key from .env. The error
message is 'Invalid API key'. What should I check?"
→ Cascade can help without seeing the actual secret

Pitfall 10: Not Using Turbo Mode Safely

The mistake: Enabling Turbo mode without configuring deny lists.

BAD: Turbo mode ON + no deny list
→ Cascade auto-runs `rm -rf`, `git push --force`, etc.

GOOD: Turbo mode ON + configured deny list
→ Fast auto-execution for safe commands (npm test, git status)
→ Manual approval for dangerous commands (rm, sudo, push --force)

CONFIGURE:
Settings > cascadeCommandsDenyList > add destructive commands

Error Handling

Pitfall	Symptom	Prevention
Wrong tool for task	Slow response for simple task	Tab for completions, Cmd+L for complex
Giant workspace	Slow indexing, vague AI	Open service directory, not root
Vague prompts	Wrong files modified	Specify paths, constraints, expected output
No review	Broken build after Cascade	Always review diffs, run tests
No checkpoint	Can't undo Cascade work	Always commit before Cascade
AI conflicts	Duplicate/wrong suggestions	Disable competing extensions
Over-limit rules	Silently truncated	Check char counts, use workspace rules
Long conversations	Context degradation	New session per task
Secrets in chat	Potential data exposure	Never paste actual credentials
Unsafe Turbo	Destructive commands auto-run	Configure deny list

Examples

Pre-Cascade Checklist

set -euo pipefail
echo "=== Pre-Cascade Checklist ==="
echo "Git clean: $(git status --porcelain | wc -l | xargs) uncommitted files"
echo "On branch: $(git branch --show-current)"
echo "Rules: $(wc -c < .windsurfrules 2>/dev/null || echo 0) chars (max 6000)"
echo "Conflicting exts: $(windsurf --list-extensions 2>/dev/null | grep -ci 'copilot\|tabnine\|cody' || echo 0)"

Common Prompt Templates

Feature: "In [file], add [feature] that [behavior]. Follow the pattern
in @[reference-file]. Include error handling for [edge cases]. Don't
modify [protected files]."

Bug fix: "@[file] The function [name] fails when [condition]. The error
is [error message]. Fix it and add a test for this edge case."

Refactor: "Extract [logic] from [file] into a new [file]. Update all
imports. Run tests after. Don't change public API signatures."

Resources

• Windsurf Documentation
• Cascade Best Practices
• Windsurf Rules Directory

Next Steps

Start with windsurf-install-auth if you're new, or windsurf-reference-architecture for team setup.