# Troubleshooting Guide

Solutions to common issues with AI Flow Kit.

## Installation & Setup

### "aiflow command not found"

**Global installation:**
```bash
npm install -g @relipa/ai-flow-kit
aiflow --version
```

**Local installation:**
```bash
cd your-project
npm install @relipa/ai-flow-kit
npx aiflow --version
```

**Windows cmd/PowerShell:**
```cmd
npm install -g @relipa/ai-flow-kit
refreshenv
aiflow --version
```

### "Permission denied" on Mac/Linux

```bash
# Make script executable
chmod +x ~/.npm/_npx/*/bin/aiflow.js

# Or reinstall globally
npm uninstall -g @relipa/ai-flow-kit
npm install -g @relipa/ai-flow-kit
```

---

## Initialization

### "aiflow init" fails with error

**Check Node.js version:**
```bash
node --version  # Should be 14 or higher
npm --version   # Should be 6 or higher
```

**Clear npm cache:**
```bash
npm cache clean --force
npm install -g @relipa/ai-flow-kit
```

**Check disk space:**
```bash
# On Mac/Linux
df -h

# On Windows
dir C:\
```

---

## Context Loading

### "Cannot load context from Jira"

**Verify credentials:**
```bash
echo $JIRA_API_TOKEN
echo $JIRA_EMAIL
echo $JIRA_DOMAIN
```

If empty, set them:

**Mac/Linux:**
```bash
export JIRA_API_TOKEN=your-token
export JIRA_EMAIL=your-email
export JIRA_DOMAIN=your-domain
```

**Windows PowerShell:**
```powershell
$env:JIRA_API_TOKEN = "your-token"
$env:JIRA_EMAIL = "your-email"
$env:JIRA_DOMAIN = "your-domain"
```

**Verify connection:**
```bash
aiflow doctor
# Should show: ✓ Jira adapter configured
```

### "Cannot connect to Backlog"

```bash
# Check credentials
echo $BACKLOG_API_KEY
echo $BACKLOG_SPACE_KEY

# Verify API key is valid
# Visit: https://<space-key>.backlogtool.com/api/v2/users/me
# (Use API key as username, empty password)
```

### "Cannot load from Google Sheets"

```bash
# Verify Google Sheets service account
ls ~/.config/google-sheets-key.json

# Or set path
export GOOGLE_SHEETS_CREDS=/path/to/credentials.json
```

---

## Configuration

### ".aiflowrc.json" not being read

**Verify file exists:**
```bash
ls -la .aiflowrc.json
# Should show file in current directory
```

**Check file format:**
```bash
# Verify it's valid JSON
cat .aiflowrc.json | jq .
# Should not show errors
```

**Reload configuration:**
```bash
aiflow update
aiflow doctor
```

### "Config option not working"

**Verify option name:**
```bash
# Check configuration guide
# for correct spelling and format
cat docs/configuration.md
```

**Check precedence:**
Options are overridden in this order:
1. Environment variables (highest)
2. CLI flags
3. `.aiflowrc.json`
4. Global config
5. Defaults (lowest)

---

## Context Management

### "Context file not found"

```bash
# Check context exists
ls .aiflow/context/

# If missing, reload context
aiflow use JIRA-123  # Reload from ticket
# or
aiflow use --file path/to/context.json
```

### "Cannot save context"

**Check permissions:**
```bash
ls -ld .claude
# Should show: drwxr-xr-x

chmod -R 755 .claude
```

**Check disk space:**
```bash
df -h
# Should have > 100MB free
```

---

## Prompting

### "Generated prompt is incomplete"

**Check context loaded:**
```bash
aiflow context --show
# Should show title, description, criteria
```

**Try with more detail:**
```bash
aiflow prompt bug-fix --detail comprehensive
```

**Check framework template:**
```bash
ls CLAUDE.md
cat CLAUDE.md | head -20
```

### "Prompt has formatting issues"

**Save to file instead:**
```bash
aiflow prompt bug-fix -o prompt.md
# Review file before copying
cat prompt.md
```

**Copy from file carefully:**
```bash
# Ensure all text is selected
# Including blank lines
```

---

## Task Detection

### "Task type not detected"

**Show detection confidence:**
```bash
aiflow detect "Your description" --verbose
```

**Manually specify type:**
```bash
aiflow prompt bug-fix      # If you know it's a bug
aiflow prompt feature      # If you know it's a feature
```

**Lower confidence threshold:**
```json
{
  "detection": {
    "confidence_threshold": 0.7
  }
}
```

### "Wrong task type detected"

**Improve description:**
```bash
# Bad: "Something is broken"
# Better: "Payment processing fails on checkout"

aiflow detect "Payment processing fails on checkout" --verbose
```

**Provide context ticket:**
```bash
aiflow use JIRA-123
# Better context helps detection
```

---

## Version Management

### "Cannot update to latest"

**Check internet connection:**
```bash
ping npm.js
```

**Clear npm cache:**
```bash
npm cache clean --force
```

**Force update:**
```bash
aiflow update --force
```

### "Want to use older version"

**See available versions:**
```bash
ls .aiflow/versions/
```

**Switch to older version:**
```bash
aiflow use 0.9.0
aiflow doctor
# Verify it works
```

### "Updated but changes not appearing"

```bash
# Update and clear cache
aiflow update

# Verify update
aiflow doctor

# Reload in Claude Code
# (Close and reopen)
```

---

## Skills & Rules

### "Custom skill not showing up"

**Verify file created:**
```bash
ls custom/skills/my-skill/SKILL.md
```

**Check file format:**
```bash
# Should have frontmatter
head -5 custom/skills/my-skill/SKILL.md
# Should show: ---\nname: my-skill
```

**Reload skills:**
```bash
aiflow update
aiflow doctor
```

### "Custom rule not applied"

**Verify rule file:**
```bash
ls custom/rules/my-rule.md
cat custom/rules/my-rule.md | head -10
```

**Check rule is in prompt:**
```bash
aiflow prompt bug-fix | grep -i "my-rule"
```

**Verify rule syntax:**
```bash
# Rules are markdown with examples
# Check for proper formatting
```

---

## Memory System

### "Memory not saving"

**Check directory exists:**
```bash
ls -la .aiflow/memory/
```

**Create if missing:**
```bash
mkdir -p .aiflow/memory
chmod 755 .aiflow/memory
```

**Try again:**
```bash
aiflow memory --save "test" "value"
aiflow memory --get "test"
```

### "Memory not loading automatically"

**Check auto-load enabled:**
```json
{
  "memory": {
    "autoLoadRelevant": true
  }
}
```

**Manually load relevant memory:**
```bash
aiflow memory --search "payment"
# Then manually reference in prompt
```

---

## Health Check

### "aiflow doctor shows errors"

**Run with fix:**
```bash
aiflow doctor --fix
# Automatically fix common issues
```

**Reinitialize:**
```bash
aiflow init
# Recreates missing files
```

**Detailed check:**
```bash
aiflow doctor --verbose
# Shows detailed checks
```

---

## Performance Issues

### "aiflow commands slow"

**Check disk I/O:**
```bash
# Try on different disk
# (SSD vs HDD makes difference)
```

**Check file size:**
```bash
du -sh .claude/
du -sh .aiflow/
# Should be < 100MB combined
```

**Clear old contexts:**
```bash
aiflow context --clear
# Removes cached contexts
```

### "Context loading slow"

**Check MCP timeout:**
```json
{
  "mcp": {
    "timeout": 30000
  }
}
```

**Use manual context:**
```bash
aiflow use --manual
# Faster than MCP queries
```

---

## Validation & Quality

### "Validation is too strict"

**Use less strict ruleset:**
```bash
aiflow validate output.php --ruleset default
# Instead of: --ruleset strict
```

**Disable specific rules:**
```json
{
  "validationRules": {
    "naming": false,
    "codeStyle": true
  }
}
```

### "Validation not catching issues"

**Use strict ruleset:**
```bash
aiflow validate output.php --ruleset strict
```

**Add custom rules:**
```bash
touch custom/rules/my-strict-rule.md
aiflow update
```

---

## Claude Code Integration

### "Claude doesn't detect skill"

**Verify skill is in `.claude/skills/`:**
```bash
ls .claude/skills/investigate-bug/
```

**Check CLAUDE.md includes context:**
```bash
cat CLAUDE.md | head -20
# Should reference skills
```

**Update Claude Code:**
- Close Claude Code
- `aiflow update`
- Reopen Claude Code

### "AI not following team rules"

**Verify rules in `.rules/`:**
```bash
ls .rules/
```

**Check CLAUDE.md loaded:**
```bash
cat CLAUDE.md | grep -i "rule"
```

**Refresh Claude Code:**
- Close and reopen
- Run `aiflow doctor` to verify setup

## Telemetry Tracking

### "Telemetry connection test failed"

**Verify Apps Script settings:**
- Ensure the Apps Script Web App is deployed and accessible.
- Ensure the `TEAM_SECRET` is exactly correct without trailing spaces.

**Bypass / Opt-out locally:**
If you don't want telemetry tracked on a specific repo, or the upload is failing constantly:
```bash
touch .aiflow/no-telemetry
# CLI will automatically ignore logging for this repo.
```

---

## Getting More Help

1. **Check logs:**
   ```bash
   aiflow doctor --verbose
   ```

2. **Check documentation:**
   ```bash
   cat docs/getting-started.md
   cat docs/architecture.md
   ```

3. **Verify setup:**
   ```bash
   aiflow doctor
   ```

4. **Ask for help:**
   - Create an issue on GitHub
   - Check existing issues/discussions
   - Contact team lead

---

## Quick Fixes Checklist

- [ ] `npm install -g @relipa/ai-flow-kit` — Fresh install
- [ ] `aiflow update` — Update to latest
- [ ] `aiflow doctor` — Verify setup
- [ ] `aiflow doctor --fix` — Auto-fix issues
- [ ] `aiflow init --framework <name>` — Reinitialize
- [ ] Clear contexts: `aiflow context --clear`
- [ ] Restart Claude Code — Reload configuration

---

**Still stuck?** Check [Getting Started](./getting-started.md) or create an issue. 🆘