windsurf-reliability-patterns

Windsurf Reliability Patterns

Overview

Reliability patterns for safe Cascade usage: Git checkpointing, incremental task scoping, validation gates, and rollback strategies. Cascade's multi-file editing is powerful but requires discipline to avoid breaking your codebase.

Prerequisites

• Windsurf with Cascade enabled
• Git repository initialized
• Test suite available
• Understanding of Cascade Write mode

Instructions

Step 1: Always Commit Before Cascade

The most important reliability pattern: create a clean Git checkpoint before every Cascade session.

# Before starting a Cascade task
git add -A && git commit -m "checkpoint: before cascade session"

# After Cascade completes:
git diff                                    # Review all changes
npm test && npm run typecheck               # Validate

# If good:
git add -A && git commit -m "[cascade] add notification service"

# If bad:
git checkout -- .                           # Revert everything
# Or selectively:
git checkout -- src/problem-file.ts         # Revert one file

Step 2: Use Feature Branches for Cascade Work

# Create dedicated branch for each Cascade task
git checkout -b cascade/add-notification-service

# Do Cascade work on this branch
# ...

# If results are good:
git checkout main && git merge cascade/add-notification-service

# If results are bad:
git checkout main && git branch -D cascade/add-notification-service
# Clean slate, main branch untouched

Step 3: Scope Tasks Incrementally

Large tasks cause Cascade to make sweeping changes that are hard to review. Break into steps.

BAD (too broad):
"Refactor the authentication system to use JWT instead of sessions"
→ Cascade may modify 30+ files, hard to review, likely has bugs

GOOD (incremental):
Step 1: "Create src/services/jwt.ts with functions: generateToken,
         validateToken, refreshToken. Use the jose library."
Step 2: "Create tests/services/jwt.test.ts with tests for all three functions"
Step 3: "Run the tests and fix any failures"
Step 4: "Update src/middleware/auth.ts to use jwt.ts instead of
         express-session. Keep the old code commented out."
Step 5: "Run the full test suite and fix any failures"
Step 6: "Remove commented-out session code from auth.ts"

Each step: review diff → test → commit → next step

Step 4: Validate After Every Cascade Edit

#!/bin/bash
# scripts/cascade-validate.sh — run after every Cascade edit
set -euo pipefail

echo "=== Post-Cascade Validation ==="

# Type check
echo "1/4 TypeScript..."
npm run typecheck || { echo "FAIL: Type errors. Ask Cascade to fix."; exit 1; }

# Lint
echo "2/4 Lint..."
npm run lint || { echo "FAIL: Lint errors. Ask Cascade to fix."; exit 1; }

# Tests
echo "3/4 Tests..."
npm test || { echo "FAIL: Test failures. Ask Cascade to fix."; exit 1; }

# Build
echo "4/4 Build..."
npm run build || { echo "FAIL: Build errors. Ask Cascade to fix."; exit 1; }

echo "ALL PASSED. Safe to commit."

Step 5: Use Cascade Checkpoints

Cascade supports named checkpoints within a conversation:

1. Start Cascade task
2. After each significant step, Cascade shows a revert button
3. Hover over any previous step → click revert arrow → rolls back to that point
4. WARNING: Reverts are irreversible (can't undo a revert)
5. For complex tasks, commit to Git between Cascade steps for a safer safety net

Step 6: Cascade Constraint Patterns

Add constraints to prompts to prevent Cascade from going too wide:

Scope constraints:
"Only modify files in src/services/"
"Don't change any existing tests"
"Don't modify any files except src/services/auth.ts"
"Don't install new dependencies"

Quality constraints:
"Follow the Result<T,E> pattern used in other services"
"Match the coding style in @src/services/payment.ts"
"Include error handling for all edge cases"
"Add JSDoc comments on all public functions"

Safety constraints:
"Don't modify the database schema"
"Don't change any API response formats"
"Don't remove any existing functionality"
"Keep backward compatibility with existing callers"

Step 7: Team Safety Policy

# Team Cascade Usage Policy

1. **Git checkpoint before Cascade** — non-negotiable
2. **One task per Cascade session** — don't mix refactor + feature
3. **Review every file diff** — never "accept all" without reading
4. **Run tests after accepting** — `npm test` before committing
5. **Tag AI commits** — use `[cascade]` prefix for traceability
6. **Feature branches only** — never use Cascade on main/develop
7. **Start fresh for new tasks** — close old Cascade sessions
8. **Narrow scope** — specific files > vague descriptions

Error Handling

Examples

Safe Cascade Workflow (Complete)

set -euo pipefail
# 1. Branch
git checkout -b cascade/feature-name

# 2. Checkpoint
git add -A && git commit -m "checkpoint: pre-cascade" --allow-empty

# 3. Cascade task (in Windsurf)
# ... Cascade edits files ...

# 4. Validate
npm run typecheck && npm test && npm run lint

# 5. Commit
git add -A && git commit -m "[cascade] implement feature-name"

# 6. Merge (after review)
git checkout main && git merge cascade/feature-name
git branch -d cascade/feature-name

Recover from Bad Cascade Edit

# Option 1: Revert all changes since checkpoint
git checkout -- .

# Option 2: Revert specific file
git checkout -- src/broken-file.ts

# Option 3: Reset to last commit
git reset --hard HEAD

# Option 4: Cherry-pick good commits from bad branch
git log cascade/feature-name --oneline  # Find good commits
git cherry-pick <good-commit-hash>

Resources

• Windsurf Cascade
• Git Workflows

Next Steps

For policy guardrails, see windsurf-policy-guardrails.