Troubleshooting

Solve common issues quickly

🔧 Most issues solved in 2 minutes

⚡ Quick Fixes

Try these solutions for the most common problems

1

Plugin Not Loading

/plugin list

Check if sift-coder appears in the list. If not, re-run /plugin in the plugin directory.

2

Commands Not Recognized

/siftcoder:status

Test if the plugin is working. If you see status output, the plugin is loaded correctly.

3

Build/Test Failures

/siftcoder:heal

Self-healing attempts to fix build and test failures automatically.

4

Check Permissions

ls -la

Ensure you have write permissions for the directory you're working in.

🔍 Common Issues & Solutions

📥 Installation Issues

❌ Plugin doesn't appear in list

  1. Verify you're in the correct directory: cd path/to/sift-coder
  2. Check plugin.json exists: ls .claude-plugin/plugin.json
  3. Re-run installation: /plugin
  4. Restart Claude Code
  5. Check enabledPlugins in ~/.claude/settings.json

❌ "Plugin not found" error

  1. Verify Claude Code version: claude --version
  2. Update Claude Code if needed
  3. Check plugin.json is valid JSON
  4. Ensure plugin.json has correct format

❌ Commands return "not found"

  1. Run /plugin list to verify plugin loaded
  2. Try full command: /siftcoder:status
  3. Check for typos in command name
  4. See command reference for correct syntax

⚙️ Runtime Issues

❌ Agent loops or repeats

  1. Press Ctrl+C to interrupt
  2. Use /siftcoder:pause to stop workflow
  3. Check /siftcoder:trace to see what's happening
  4. Adjust maxIterations in config

❌ Build keeps failing

  1. Run /siftcoder:investigate "build failure"
  2. Check error logs carefully
  3. Try /siftcoder:fix with specific error
  4. Disable problematic quality gates temporarily

❌ Tests keep failing

  1. Run /siftcoder:fuzz-mind to find edge cases
  2. Use /siftcoder:flaky-tests to identify flaky tests
  3. Check /siftcoder:coverage for untested code
  4. Review test logic with /siftcoder:investigate

❌ "Blast radius too large" error

  1. Review which files would be affected
  2. Use /siftcoder:scope to protect sensitive files
  3. Break task into smaller, focused changes
  4. Create checkpoint before proceeding

⚡ Performance Issues

❌ Commands are slow

  1. Enable parallel agents in config
  2. Reduce maxIterations if agent loops
  3. Disable unnecessary quality gates
  4. Use /siftcoder:budget to track costs

❌ High API costs

  1. Run /siftcoder:budget to see usage
  2. Set cost limits in configuration
  3. Use /siftcoder:trace to identify expensive operations
  4. Reduce verbosity to decrease token usage

❌ Memory issues

  1. Use /siftcoder:focus to limit to specific files
  2. Break large tasks into smaller ones
  3. Clear session with /siftcoder:checkpoint clear
  4. Disable persistence if not needed

☁️ Salesforce Issues

❌ Deployment fails

  1. Run /siftcoder:sf-deploy --validate-only
  2. Check org credentials: sfdx force:org:display
  3. Review deployment errors with /siftcoder:investigate
  4. Use /siftcoder:sf-diff to see changes

❌ Apex tests fail

  1. Run /siftcoder:sf-test --verbose for details
  2. Use /siftcoder:apex to check for issues
  3. Check test data with /siftcoder:sf-test-data
  4. Verify org access permissions

🔬 Diagnostic Commands

Use these commands to investigate issues

/siftcoder:status

Check plugin health and configuration

/siftcoder:trace

See full execution history

/siftcoder:investigate

Explore codebase read-only

/siftcoder:budget

View token usage and costs

/siftcoder:scope list

See protected files

/siftcerer:checkpoint list

View available restore points

💡 Get More Help

📖

Documentation

Comprehensive guides and reference

Browse Docs →
🔍

Command Reference

All 103 commands documented

View Commands →
🐙

GitHub Issues

Report bugs and request features

Open Issue →
💬

Community

Get help from other users

Join Discussion →

✅ Avoid Issues Entirely

🎯 Use Scope Management

Protect critical files before making changes

/siftcoder:scope add .env
/siftcoder:scope add src/critical/*

💾 Create Checkpoints

Save state before risky operations

/siftcoder:checkpoint save "before-refactor"

👀 Preview Changes

Review diffs before applying

/siftcoder:preview

📊 Monitor Costs

Track token usage regularly

/siftcoder:budget

🔍 Investigate First

Use read-only mode to understand

/siftcoder:investigate "Issue"

⚙️ Configure Properly

Set appropriate quality gates

/siftcoder:config

🆘 Still Stuck?

If you've tried the solutions above and still need help:

  1. Run /siftcoder:status and copy the output
  2. Run /siftcoder:trace and copy recent activity
  3. Search GitHub Issues for similar problems
  4. Create a new issue with the diagnostic information

When reporting issues, include:

  • ✅ SiftCoder version (from /siftcoder:status)
  • ✅ Claude Code version
  • ✅ Operating system
  • ✅ Command you ran
  • ✅ Error message (full text)
  • ✅ Steps to reproduce