Initial commit

TROUBLESHOOTING.md

@@ -0,0 +1,192 @@
+# Worktree Troubleshooting Guide
+
+Common issues and their solutions when managing worktrees.
+
+## Issue 1: "My worktree isn't working"
+
+### Symptoms
+- User can't access the worktree
+- Services appear down
+- URLs not responding
+
+### Diagnosis Steps
+1. Run `/list_worktrees` to check status
+2. Look for service status (running/stopped)
+3. Check port configuration
+
+### Solutions
+- If services are stopped, recreate the worktree
+- If ports conflict, use a different port offset
+- Check if processes crashed (look at PIDs)
+
+### What to tell the user
+> Let me check the status of your worktrees...
+> [run /list_worktrees]
+> I see the issue - [explain problem and solution]
+
+---
+
+## Issue 2: "I can't create a worktree"
+
+### Symptoms
+- Creation command fails
+- Error messages about existing worktrees
+- Port conflicts
+
+### Common Causes
+1. **Worktree already exists** - Branch already has a worktree
+2. **Invalid branch name** - Branch doesn't exist in repository
+3. **Port already in use** - Another service using the ports
+
+### Solutions
+1. Check existing worktrees: `/list_worktrees`
+2. Verify branch exists: `git branch -a`
+3. Try a different port offset if ports conflict
+4. Remove old worktree first if recreating
+
+### What to tell the user
+> It looks like [diagnosis]. Let me [solution approach].
+
+---
+
+## Issue 3: "How do I access my worktree?"
+
+### User doesn't know the URLs
+
+### Solution
+1. Run `/list_worktrees` to see access URLs
+2. Show the Dashboard URL for their specific worktree
+3. Explain the port scheme
+
+### What to tell the user
+> Here are the access URLs for your worktree:
+> - Dashboard: http://localhost:[CLIENT_PORT]/dashboard
+> - Server API: http://localhost:[SERVER_PORT]
+> - Client: http://localhost:[CLIENT_PORT]
+
+---
+
+## Issue 4: "Services won't stop"
+
+### Symptoms
+- Processes still running after removal attempt
+- Ports still in use
+- Can't recreate worktree due to conflicts
+
+### Solutions
+1. Use `/remove_worktree` which force-kills processes
+2. If still stuck, run `/list_worktrees` to see PIDs
+3. Can manually kill processes if needed: `kill -9 <PID>`
+
+### What to tell the user
+> I'll use the remove command which will force-stop all services...
+> [run /remove_worktree]
+
+---
+
+## Issue 5: "Port conflicts"
+
+### Symptoms
+- Error about port already in use
+- Services fail to start
+- Multiple worktrees on same ports
+
+### Solutions
+1. List existing worktrees to see port allocation
+2. Use explicit port offset when creating: `/create_worktree branch-name 4`
+3. Remove unused worktrees to free up ports
+
+### Port Allocation Reference
+- Main: 4000, 5173
+- Offset 1: 4010, 5183
+- Offset 2: 4020, 5193
+- Offset 3: 4030, 5203
+- Pattern: BASE + (offset * 10)
+
+---
+
+## Issue 6: "Worktree directory exists but not listed"
+
+### Symptoms
+- Directory in `trees/` folder
+- Not showing in `/list_worktrees`
+- Git doesn't recognize it
+
+### Likely Cause
+Incomplete removal or manual deletion
+
+### Solutions
+1. Check `git worktree list` to see git's view
+2. If orphaned, remove directory manually: `rm -rf trees/branch-name`
+3. If needed, prune git worktrees: `git worktree prune`
+
+### What to tell the user
+> It looks like there's an orphaned worktree. Let me clean it up...
+
+---
+
+## Issue 7: "Dependencies not installing"
+
+### Symptoms
+- Services fail to start
+- Missing modules errors
+- Build failures
+
+### Solutions
+1. Check the creation output for install errors
+2. Manually run install in worktree: `cd trees/branch-name && npm install`
+3. Verify package.json exists in worktree
+
+---
+
+## Issue 8: "Database issues in worktree"
+
+### Symptoms
+- Database errors
+- Data conflicts between main and worktree
+- Migrations not running
+
+### Note
+Each worktree should have isolated database configuration. Check:
+1. .env file in worktree has unique DB settings
+2. Database name includes branch identifier
+3. Migrations ran successfully during creation
+
+---
+
+## General Debugging Approach
+
+When user reports any issue:
+
+1. **Gather information**
+   - Run `/list_worktrees` first
+   - Ask which specific worktree
+   - Ask what they were trying to do
+
+2. **Diagnose**
+   - Check service status
+   - Verify port configuration
+   - Look for error patterns
+
+3. **Resolve**
+   - Use appropriate command
+   - Verify fix worked
+   - Explain what happened
+
+4. **Prevent**
+   - Suggest best practices
+   - Recommend cleanup of unused worktrees
+   - Note any configuration issues
+
+---
+
+## Quick Diagnostic Checklist
+
+When troubleshooting, check:
+
+- ✓ Does worktree directory exist? (`ls trees/`)
+- ✓ Is git aware of it? (`git worktree list`)
+- ✓ Are services running? (`/list_worktrees`)
+- ✓ Are ports available? (check PIDs)
+- ✓ Is configuration correct? (check .env, settings.json)
+- ✓ Did dependencies install? (check node_modules)