Cascade Write mode is Windsurf's primary productivity tool. It acts as an autonomous agent that can create files, modify code across multiple files, run terminal commands, install dependencies, and debug errors -- all from a single natural language prompt. This is the "money-path" workflow for Windsurf users.
.windsurfrules configured (see windsurf-sdk-patterns)Always commit or stash before a Cascade session. Cascade writes directly to your files.
git add -A && git commit -m "checkpoint: before cascade session"
# Or for uncommitted work:
git stash push -m "pre-cascade stash"
Press Cmd/Ctrl+L to open the Cascade panel. Ensure "Write" mode is selected (not "Chat"). Write mode allows Cascade to:
Structure your prompt with scope, specifics, and constraints:
"In src/services/, create a NotificationService that:
1. Sends email via Resend API (already in package.json)
2. Sends Slack messages via webhook URL from env
3. Uses the Result<T,E> pattern from src/types/result.ts
4. Includes retry logic with exponential backoff (max 3 retries)
5. Add unit tests in tests/services/notification.test.ts
Don't modify any existing files except to add exports."
Cascade shows its reasoning and plan before executing:
Cascade output flow:
1. "I'll create the notification service with email and Slack support..."
2. Creates src/services/notification.ts (shows diff)
3. Creates tests/services/notification.test.ts (shows diff)
4. Runs: npm install resend (if needed)
5. Runs: npx vitest run tests/services/notification.test.ts
6. Reports results
Review each file diff in the Cascade output. You can:
If tests fail, Cascade retains context about what it just did:
"The test for sendSlack is failing with 'fetch is not defined'.
Fix it by using the node:test built-in fetch mock."
Cascade reads the error, understands its own recent changes, and applies targeted fixes.
@src/types/result.ts — force Cascade to read this file for the Result pattern
@src/services/ — reference the entire services directory for consistency
@web resend API docs — search the web for current Resend documentation
| Issue | Cause | Solution |
|---|---|---|
| Cascade modifies wrong files | Vague prompt | Specify exact file paths and constraints |
| Changes break existing tests | No constraint on existing code | Add "don't modify existing files" to prompt |
| Cascade loops on error | Insufficient context | Paste the full error message, reference relevant files |
| Write mode not available | On Free plan with no credits | Check credit balance at windsurf.com/account |
| Cascade ignores .windsurfrules | Rules file > 6,000 chars | Trim rules or split into workspace rules |
"Add a user profile page:
1. Create app/profile/page.tsx as a Server Component
2. Create app/profile/edit/page.tsx as a Client Component with form
3. Add GET /api/profile and PUT /api/profile route handlers
4. Use the existing UserSchema from lib/types/user.ts for validation
5. Style with Tailwind matching the existing design system
6. Add tests for both API routes"
"Extract the authentication logic from src/middleware/auth.ts into:
- src/services/auth.ts (JWT validation, token refresh)
- src/services/session.ts (session management)
Update all imports across the codebase. Run tests after."
For configuration management workflow, see windsurf-core-workflow-b.