NOW RAG is actually usable... might switch to gemma3:4b from glm-4.6 cloud for expenses reasons but we'll see

docs/rag/troubleshooting/common-issues.md

@@ -0,0 +1,89 @@
+# Common Issues
+
+## Permission Denied
+
+**Error**: "Not authorized for this action"
+
+**Cause**: Your role doesn't have permission
+
+**Check Permissions**:
+| Action | Allowed Roles |
+|--------|---------------|
+| Create task | PM, Board |
+| Cancel task | PM |
+| Pass/fail QA | QA only |
+| Complete docs | Documenter only |
+| Complete task | PM only |
+| Send notification | PM, Board |
+
+**Solution**: Request appropriate role to perform action
+
+## Task Stuck in Status
+
+**Problem**: Task won't transition
+
+**Causes**:
+1. Missing required fields
+2. Waiting on parallel action
+3. Invalid transition attempted
+
+**Check**:
+- For git tasks: branch exists?
+- For `awaiting_pm_review`: both `docs_complete` AND `pr_created`?
+- Is transition valid from current status?
+
+## Notification Not Received
+
+**Problem**: Expected notification didn't arrive
+
+**Causes**:
+1. Sender doesn't have notification permission
+2. Notification filtering
+3. Already acknowledged
+
+**Solutions**:
+- Check `roboco_notify_list()` for all notifications
+- Verify sender has PM/Board role
+- Check if already in `acked_by`
+
+## Escalation Not Routing
+
+**Problem**: Escalation went to wrong person
+
+**Cause**: Escalation auto-routes to your escalation target
+
+**Chain**:
+```
+Developer → Cell PM → Main PM → Product Owner → CEO
+```
+
+Cannot skip levels or choose target.
+
+## Tests Failing Before Submit
+
+**Problem**: Tests fail, can't submit to QA
+
+**Checklist**:
+```bash
+# Backend
+uv run pytest           # Tests
+uv run ruff check .     # Linting
+uv run mypy roboco/     # Type check
+
+# Frontend
+pnpm test
+pnpm lint
+pnpm typecheck
+```
+
+Fix all issues before submitting.
+
+## Lost Context After Pause
+
+**Problem**: Resuming task, forgot context
+
+**Solutions**:
+- Read `quick_context` field on task
+- Read your journal for this task
+- Get proactive context: `roboco_get_proactive_context(task_id)`
+- Read channel history for discussions

docs/rag/troubleshooting/git-errors.md

@@ -0,0 +1,72 @@
+# Git Error Troubleshooting
+
+## Workspace Not Found
+
+**Error**: "Workspace does not exist"
+
+**Cause**: Workspace not cloned yet
+
+**Solutions**:
+- If auto_clone enabled: workspace creates on first access
+- Manual: Wait for workspace service to clone
+- Check config: `ROBOCO_WORKSPACE_AUTO_CLONE=true`
+
+## Cannot Push
+
+**Error**: "Push failed"
+
+**Causes**:
+1. No commits to push
+2. Remote branch doesn't exist
+3. Conflicts with remote
+
+**Solutions**:
+- Create commits first: `roboco_git_commit(...)`
+- Check branch exists: `roboco_git_branches()`
+- Pull and resolve conflicts
+
+## Branch Already Exists
+
+**Error**: "Branch already exists"
+
+**Cause**: Trying to create existing branch
+
+**Solution**: Checkout existing branch:
+```python
+roboco_git_checkout(project_slug, branch_name)
+```
+
+## Merge Conflicts
+
+**Error**: "Merge conflict"
+
+**Cause**: Conflicting changes between branches
+
+**Solutions**:
+1. Pull latest from target branch
+2. Resolve conflicts manually
+3. Commit resolution
+4. Push again
+
+## PR Creation Failed
+
+**Error**: "PR creation failed"
+
+**Causes**:
+1. No commits on branch
+2. Branch not pushed
+3. GitHub CLI not configured
+
+**Solutions**:
+- Push branch first: `roboco_git_push()`
+- Verify commits exist: `roboco_git_log()`
+
+## Checkout Failed
+
+**Error**: "Cannot checkout - uncommitted changes"
+
+**Cause**: Working directory has uncommitted changes
+
+**Solutions**:
+- Commit changes: `roboco_git_commit(...)`
+- Or stash changes (if supported)

docs/rag/troubleshooting/kb-errors.md

@@ -0,0 +1,74 @@
+# Knowledge Base Troubleshooting
+
+## Empty Search Results
+
+**Problem**: `roboco_kb_search()` returns nothing
+
+**Causes**:
+1. Content not indexed yet
+2. Query too specific
+3. Wrong index type filter
+
+**Solutions**:
+- Check what's indexed: `roboco_kb_stats()`
+- Broaden query terms
+- Remove index_types filter
+- Trigger reindex: `roboco_reindex_all()`
+
+## Empty RAG Response
+
+**Problem**: `roboco_rag_query()` returns empty answer
+
+**Causes**:
+1. No relevant context found
+2. LLM returned thinking tags only
+3. Query too vague
+
+**Solutions**:
+- Check KB has relevant content
+- Rephrase query to be more specific
+- Use `roboco_kb_search()` first to verify content exists
+
+## Mentor Not Responding
+
+**Problem**: `roboco_ask_mentor()` fails or empty
+
+**Causes**:
+1. LLM timeout
+2. No relevant KB content
+3. Service temporarily unavailable
+
+**Solutions**:
+- Retry the query
+- Check KB stats
+- Use `roboco_kb_search()` as fallback
+
+## Index Failed
+
+**Problem**: `roboco_kb_index_code()` or `roboco_kb_index_docs()` fails
+
+**Causes**:
+1. Invalid file patterns
+2. Files not accessible
+3. Embedding service down
+
+**Solutions**:
+- Verify file patterns match files
+- Check file permissions
+- Verify Ollama is running
+
+## Cannot Clear Index
+
+**Problem**: "Not authorized to clear index"
+
+**Cause**: Only PM/CEO can clear indexes
+
+**Solution**: Ask PM or CEO to clear if needed
+
+## Proactive Context Empty
+
+**Problem**: `roboco_get_proactive_context()` returns empty
+
+**Cause**: No relevant context found for task
+
+**Solution**: Manual search with `roboco_kb_search()` using task keywords

docs/rag/troubleshooting/task-errors.md

@@ -0,0 +1,67 @@
+# Task Error Troubleshooting
+
+## Cannot Claim Task
+
+**Error**: "Task cannot be claimed"
+
+**Causes**:
+1. Task not in claimable status for your role
+2. Task already assigned to someone else
+3. Wrong role for this task type
+
+**Solutions**:
+- Check task status: `roboco_task_get(task_id)`
+- Verify your role can claim from current status
+- Contact PM if task needs reassignment
+
+**Claimable Status by Role**:
+| Role | Can Claim From |
+|------|----------------|
+| Developer | pending, needs_revision |
+| QA | awaiting_qa |
+| Documenter | awaiting_documentation |
+
+## Cannot Start Task
+
+**Error**: "Cannot transition to in_progress"
+
+**Causes**:
+1. Task not claimed by you
+2. For git tasks: branch not created yet
+3. Task in wrong status
+
+**Solutions**:
+- Claim first: `roboco_task_claim(task_id)`
+- Wait for PM to create branch (git tasks)
+- Check current status
+
+## Cannot Submit for QA
+
+**Error**: "Invalid transition from current status"
+
+**Causes**:
+1. Task not in `in_progress` or `verifying`
+2. Missing required fields
+
+**Solutions**:
+- Move through verification first
+- Ensure task is actively being worked
+
+## Self-Review Prevented
+
+**Error**: "Cannot review own work"
+
+**Cause**: QA/Documenter trying to claim task they developed
+
+**Solution**: Another QA/Documenter must handle this task
+
+## Git Task: No Branch
+
+**Error**: "Branch name required for git tasks"
+
+**Cause**: PM hasn't created branch yet
+
+**Solution**: Wait for PM or ask PM to create branch:
+```python
+roboco_git_create_branch(project_slug, task_id, "feature")
+```