first commit

docs/troubleshooting.md

@@ -0,0 +1,263 @@
+# Troubleshooting
+
+Common issues and solutions for the AI Code Review system.
+
+## Installation Issues
+
+### `ModuleNotFoundError: No module named 'requests'`
+
+Install dependencies:
+
+```bash
+pip install requests pyyaml
+```
+
+### `ImportError: cannot import name 'BaseAgent'`
+
+Ensure you're running from the correct directory:
+
+```bash
+cd tools/ai-review
+python main.py pr owner/repo 123
+```
+
+---
+
+## Authentication Issues
+
+### `repository not found`
+
+**Causes:**
+- Bot token lacks access to the repository
+- Repository path is incorrect
+
+**Solutions:**
+1. Verify token has `repo` permissions
+2. Check repository path format: `owner/repo`
+3. Ensure token can access both the target repo and the AI tooling repo
+
+### `401 Unauthorized`
+
+**Causes:**
+- Invalid or expired token
+- Missing token in environment
+
+**Solutions:**
+1. Regenerate the bot token
+2. Verify `AI_REVIEW_TOKEN` is set correctly
+3. Check organization secret scope is "All Repositories"
+
+### `403 Forbidden`
+
+**Causes:**
+- Token lacks write permissions
+- Repository is private and token doesn't have access
+
+**Solutions:**
+1. Ensure token has `issue:write` permission
+2. Add bot account as collaborator to private repos
+
+---
+
+## LLM Issues
+
+### `OPENAI_API_KEY not set`
+
+Set the environment variable:
+
+```bash
+export OPENAI_API_KEY="sk-..."
+```
+
+Or in workflow:
+
+```yaml
+env:
+  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+```
+
+### `Rate limit exceeded`
+
+**Causes:**
+- Too many requests to LLM provider
+- API quota exhausted
+
+**Solutions:**
+1. Increase rate limit interval in config
+2. Switch to a different provider temporarily
+3. Check your API plan limits
+
+### `JSON decode error` from LLM
+
+**Causes:**
+- LLM returned non-JSON response
+- Response was truncated
+
+**Solutions:**
+1. Increase `max_tokens` in config
+2. Check LLM response in logs
+3. Improve prompt to enforce JSON output
+
+---
+
+## Workflow Issues
+
+### Workflow doesn't trigger
+
+**Causes:**
+- Workflow file not in correct location
+- Event type not configured
+
+**Solutions:**
+1. Ensure workflow is in `.gitea/workflows/`
+2. Check event types match your needs:
+   ```yaml
+   on:
+     pull_request:
+       types: [opened, synchronize]
+   ```
+3. Verify Gitea Actions is enabled for the repository
+
+### `review.py not found`
+
+**Causes:**
+- Central repo checkout failed
+- Path is incorrect
+
+**Solutions:**
+1. Verify the checkout step has correct repository and path
+2. Check bot token has access to the AI tooling repo
+3. Ensure path matches: `.ai-review/tools/ai-review/main.py`
+
+### PR comments not appearing
+
+**Causes:**
+- Token lacks issue write permission
+- API URL is incorrect
+
+**Solutions:**
+1. Check `AI_REVIEW_API_URL` is correct
+2. Verify token has `issue:write` permission
+3. Check workflow logs for API errors
+
+### @ai-bot edits the issue instead of replying
+
+**Causes:**
+- Workflow is using the wrong CLI command for comments
+- `event_type` is incorrectly set to "issues"
+
+**Solutions:**
+1. Ensure your workflow uses the `comment` command for mentions:
+   ```yaml
+   python main.py comment owner/repo 123 "@ai-bot ..."
+   ```
+2. Verify you have separate jobs for `issues` vs `issue_comment` events (see [Workflows](workflows.md))
+
+---
+
+## Label Issues
+
+### Labels not being applied
+
+**Causes:**
+- Labels don't exist in repository
+- Label names don't match config
+
+**Solutions:**
+1. Create labels matching your config:
+   - `priority: high`
+   - `type: bug`
+   - `ai-approved`
+2. Or update config to match existing labels:
+   ```yaml
+   labels:
+     priority:
+       high: "P0"  # Your label name
+   ```
+
+### `label not found` error
+
+The agent gracefully handles missing labels. Create labels manually or disable auto-labeling:
+
+```yaml
+agents:
+  issue:
+    auto_label: false
+```
+
+---
+
+## Performance Issues
+
+### Reviews are slow
+
+**Causes:**
+- Large diffs taking long to process
+- LLM response time
+
+**Solutions:**
+1. Reduce max diff lines:
+   ```yaml
+   review:
+     max_diff_lines: 500
+   ```
+2. Use a faster model:
+   ```yaml
+   model:
+     openai: gpt-4.1-mini  # Faster than gpt-4
+   ```
+3. Consider Ollama for local, faster inference
+
+### Timeout errors
+
+Increase timeout in API calls or use async processing:
+
+```python
+client = GiteaClient(timeout=60)  # Increase from default 30
+```
+
+---
+
+## Debugging
+
+### Enable verbose logging
+
+```bash
+python main.py -v pr owner/repo 123
+```
+
+### Check workflow logs
+
+1. Go to repository -> Actions
+2. Click on the failed workflow run
+3. Expand job steps to see output
+
+### Test locally
+
+```bash
+# Set environment variables
+export AI_REVIEW_TOKEN="your_token"
+export AI_REVIEW_API_URL="https://your-gitea/api/v1"
+export OPENAI_API_KEY="sk-..."
+
+# Run locally
+cd tools/ai-review
+python main.py pr owner/repo 123
+```
+
+### Validate Python syntax
+
+```bash
+python -m py_compile main.py
+```
+
+---
+
+## Getting Help
+
+1. Check the [documentation](README.md)
+2. Search existing issues in the repository
+3. Create a new issue with:
+   - Steps to reproduce
+   - Error messages
+   - Environment details (Gitea version, Python version)