aiwf 0.3.23 → 0.4.0

package/docs/TROUBLESHOOTING.md

@@ -1,722 +0,0 @@
-# AIWF Troubleshooting Guide
-
-This guide helps you resolve common issues when using AIWF (AI Workflow Framework). If you can't find a solution here, please check our [GitHub Issues](https://github.com/moonklabs/aiwf/issues) or create a new issue.
-
-## Table of Contents
-
-1. [Installation Issues](#installation-issues)
-2. [Command Execution Problems](#command-execution-problems)
-3. [Performance Issues](#performance-issues)
-4. [Git Integration Problems](#git-integration-problems)
-5. [AI Persona Issues](#ai-persona-issues)
-6. [Context Compression Problems](#context-compression-problems)
-7. [Test Failures](#test-failures)
-8. [Language and Localization](#language-and-localization)
-9. [Common Error Messages](#common-error-messages)
-10. [Advanced Debugging](#advanced-debugging)
-
----
-
-## Installation Issues
-
-### Problem: Installation fails with "EACCES: permission denied"
-
-**Symptoms:**
-```bash
-npm ERR! code EACCES
-npm ERR! syscall mkdir
-npm ERR! path /usr/local/lib/node_modules/aiwf
-```
-
-**Solutions:**
-
-1. **Install globally:**
-   ```bash
-   npm install -g aiwf
-   aiwf install
-   ```
-
-2. **Fix npm permissions:**
-   ```bash
-   # Option 1: Change npm's default directory
-   mkdir ~/.npm-global
-   npm config set prefix '~/.npm-global'
-   echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
-   source ~/.bashrc
-   
-   # Option 2: Use a Node version manager
-   # Install nvm and use it to manage Node installations
-   ```
-
-3. **Use sudo (Not recommended):**
-   ```bash
-   sudo npm install -g aiwf
-   ```
-
-### Problem: "Cannot find module" errors during installation
-
-**Symptoms:**
-```bash
-Error: Cannot find module 'chalk'
-Error: Cannot find module 'ora'
-```
-
-**Solutions:**
-
-1. **Clear npm cache:**
-   ```bash
-   npm cache clean --force
-   ```
-
-2. **Delete node_modules and reinstall:**
-   ```bash
-   rm -rf node_modules package-lock.json
-   npm install
-   ```
-
-3. **Check Node.js version:**
-   ```bash
-   node --version  # Should be 14.0.0 or higher
-   ```
-
-### Problem: Installation hangs or times out
-
-**Symptoms:**
-- Installation process freezes
-- Network timeout errors
-
-**Solutions:**
-
-1. **Check internet connection**
-
-2. **Use different npm registry:**
-   ```bash
-   npm config set registry https://registry.npmjs.org/
-   ```
-
-3. **Increase timeout:**
-   ```bash
-   npm config set timeout 60000
-   ```
-
-4. **Try offline installation:**
-   ```bash
-   aiwf install --offline
-   ```
-
----
-
-## Command Execution Problems
-
-### Problem: Commands not recognized in Claude Code
-
-**Symptoms:**
-```
-Command not found: /project:aiwf:initialize
-```
-
-**Solutions:**
-
-1. **Verify installation:**
-   ```bash
-   ls -la .claude/commands/aiwf/
-   ```
-
-2. **Reinstall AIWF commands:**
-   ```bash
-   aiwf install --force
-   ```
-
-3. **Check Claude Code settings:**
-   - Ensure custom commands are enabled
-   - Restart Claude Code after installation
-
-### Problem: Commands execute but produce no output
-
-**Symptoms:**
-- Command runs without errors
-- No visible changes or output
-
-**Solutions:**
-
-1. **Check command syntax:**
-   ```bash
-   # Correct
-   /project:aiwf:initialize
-   
-   # Incorrect
-   /project:aiwf initialize
-   ```
-
-2. **Verify working directory:**
-   ```bash
-   pwd  # Should be in project root
-   ```
-
-3. **Check permissions:**
-   ```bash
-   ls -la .aiwf/
-   # Ensure write permissions
-   ```
-
-### Problem: Korean commands not working
-
-**Symptoms:**
-```
-Command not found: /프로젝트:aiwf:초기화
-```
-
-**Solutions:**
-
-1. **Verify Korean language installation:**
-   ```bash
-   aiwf-lang status
-   ```
-
-2. **Switch to Korean:**
-   ```bash
-   aiwf-lang set ko
-   ```
-
-3. **Use alternative command format:**
-   ```bash
-   /project:aiwf:initialize_kr
-   ```
-
----
-
-## Performance Issues
-
-### Problem: Slow command execution
-
-**Symptoms:**
-- Commands take several seconds to complete
-- High CPU/memory usage
-
-**Solutions:**
-
-1. **Enable caching:**
-   ```javascript
-   // In .aiwf/config.json
-   {
-     "performance": {
-       "enableCache": true,
-       "cacheSize": 100
-     }
-   }
-   ```
-
-2. **Reduce file scanning scope:**
-   ```bash
-   # Add to .aiwfignore
-   node_modules/
-   dist/
-   coverage/
-   *.log
-   ```
-
-3. **Use batch operations:**
-   ```javascript
-   // Instead of individual operations
-   await processor.addReadOperation(file1);
-   await processor.addReadOperation(file2);
-   await processor.processBatch();
-   ```
-
-### Problem: Out of memory errors
-
-**Symptoms:**
-```
-FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
-```
-
-**Solutions:**
-
-1. **Increase Node.js memory:**
-   ```bash
-   export NODE_OPTIONS="--max-old-space-size=4096"
-   ```
-
-2. **Use memory profiler:**
-   ```javascript
-   const profiler = new MemoryProfiler();
-   profiler.startProfiling();
-   // ... operations ...
-   const report = profiler.generateReport();
-   ```
-
-3. **Process files in chunks:**
-   ```javascript
-   const processor = new FileBatchProcessor({
-     maxConcurrency: 5,
-     batchSize: 10
-   });
-   ```
-
-### Problem: Token limit exceeded quickly
-
-**Symptoms:**
-- Context overflow errors
-- Conversation resets frequently
-
-**Solutions:**
-
-1. **Use aggressive compression:**
-   ```bash
-   /project:aiwf:compress_context:aggressive
-   ```
-
-2. **Exclude unnecessary files:**
-   ```javascript
-   // In persona context rules
-   {
-     "exclude": ["test/**", "docs/**", "*.md"]
-   }
-   ```
-
-3. **Monitor token usage:**
-   ```javascript
-   const tracker = new TokenTracker();
-   const stats = tracker.getSessionStats();
-   console.log(`Tokens used: ${stats.percentageUsed}%`);
-   ```
-
----
-
-## Git Integration Problems
-
-### Problem: Commits not linking to features
-
-**Symptoms:**
-- Feature progress not updating
-- Commits missing from feature ledger
-
-**Solutions:**
-
-1. **Check commit message format:**
-   ```bash
-   # Good formats
-   git commit -m "feat(FL001): implement login"
-   git commit -m "[FL001] fix validation bug"
-   git commit -m "FL001: update styles"
-   
-   # Bad format
-   git commit -m "implement login for FL001"
-   ```
-
-2. **Install Git hooks:**
-   ```bash
-   /project:aiwf:install_git_hooks
-   ```
-
-3. **Manually link commits:**
-   ```bash
-   /project:aiwf:link_feature_commit FL001 abc123def
-   ```
-
-### Problem: Git hooks not executing
-
-**Symptoms:**
-- No automatic feature updates
-- Hooks exist but don't run
-
-**Solutions:**
-
-1. **Check hook permissions:**
-   ```bash
-   chmod +x .git/hooks/post-commit
-   chmod +x .git/hooks/pre-commit
-   ```
-
-2. **Verify hook content:**
-   ```bash
-   cat .git/hooks/post-commit
-   ```
-
-3. **Test hooks manually:**
-   ```bash
-   ./.git/hooks/post-commit
-   ```
-
-### Problem: Branch naming conflicts
-
-**Symptoms:**
-- Cannot create feature branches
-- Branch names already exist
-
-**Solutions:**
-
-1. **Use unique feature IDs:**
-   ```bash
-   git checkout -b feature/FL001-unique-description
-   ```
-
-2. **Clean up old branches:**
-   ```bash
-   /project:aiwf:clean_feature_branches
-   ```
-
-3. **Check existing branches:**
-   ```bash
-   git branch -a | grep FL
-   ```
-
----
-
-## AI Persona Issues
-
-### Problem: Persona not switching properly
-
-**Symptoms:**
-- Behavior doesn't change after switch
-- Wrong context being applied
-
-**Solutions:**
-
-1. **Verify current persona:**
-   ```bash
-   /project:aiwf:ai_persona:status
-   ```
-
-2. **Reset to default:**
-   ```bash
-   /project:aiwf:ai_persona:reset
-   ```
-
-3. **Wait for switch to complete:**
-   ```javascript
-   await manager.switchPersona('architect');
-   // Wait 2-3 seconds for context update
-   await new Promise(r => setTimeout(r, 3000));
-   ```
-
-### Problem: Persona context rules not applying
-
-**Symptoms:**
-- All files included despite exclusions
-- Wrong priorities applied
-
-**Solutions:**
-
-1. **Check persona configuration:**
-   ```bash
-   cat .aiwf/personas/architect.json
-   ```
-
-2. **Validate context rules:**
-   ```javascript
-   const rules = manager.getPersonaContext('architect');
-   console.log(rules);
-   ```
-
-3. **Clear persona cache:**
-   ```bash
-   rm -rf .aiwf/cache/personas/
-   ```
-
----
-
-## Context Compression Problems
-
-### Problem: Compression failing with large files
-
-**Symptoms:**
-```
-Error: Maximum file size exceeded
-Error: Compression timeout
-```
-
-**Solutions:**
-
-1. **Process files individually:**
-   ```javascript
-   const compressor = new ContextCompressor();
-   for (const file of largeFiles) {
-     await compressor.compressFile(file, 'aggressive');
-   }
-   ```
-
-2. **Increase timeout:**
-   ```javascript
-   const compressor = new ContextCompressor({
-     timeout: 300000  // 5 minutes
-   });
-   ```
-
-3. **Split large files:**
-   ```bash
-   split -l 1000 largefile.js part_
-   ```
-
-### Problem: Poor compression quality
-
-**Symptoms:**
-- Important code removed
-- Logic broken after compression
-
-**Solutions:**
-
-1. **Use conservative mode:**
-   ```bash
-   /project:aiwf:compress_context:conservative
-   ```
-
-2. **Exclude critical files:**
-   ```javascript
-   await compressor.compressDirectory('./src', 'balanced', {
-     exclude: ['critical.js', 'config.js']
-   });
-   ```
-
-3. **Review compression rules:**
-   ```javascript
-   const result = compressor.compressContext(content, 'balanced');
-   console.log(result.compressionRatio);
-   ```
-
----
-
-## Test Failures
-
-### Problem: Integration tests failing
-
-**Symptoms:**
-```
-19 tests failing
-Module not found errors
-```
-
-**Solutions:**
-
-1. **Install test dependencies:**
-   ```bash
-   npm install --include=dev
-   ```
-
-2. **Run tests individually:**
-   ```bash
-   npm test -- --testNamePattern="specific test"
-   ```
-
-3. **Check test environment:**
-   ```bash
-   npm run test:env
-   ```
-
-### Problem: Coverage below threshold
-
-**Symptoms:**
-```
-Jest: "global" coverage threshold for statements (80%) not met: 0%
-```
-
-**Solutions:**
-
-1. **Generate coverage report:**
-   ```bash
-   npm run test:coverage
-   ```
-
-2. **Identify uncovered code:**
-   ```bash
-   npx jest --coverage --coverageReporters=html
-   open coverage/index.html
-   ```
-
-3. **Add missing tests:**
-   ```javascript
-   describe('NewFeature', () => {
-     test('should work correctly', () => {
-       // Add test implementation
-     });
-   });
-   ```
-
----
-
-## Language and Localization
-
-### Problem: Wrong language detected
-
-**Symptoms:**
-- English interface when expecting Korean
-- Mixed language content
-
-**Solutions:**
-
-1. **Check system locale:**
-   ```bash
-   echo $LANG
-   locale
-   ```
-
-2. **Force language selection:**
-   ```bash
-   aiwf-lang set ko  # For Korean
-   aiwf-lang set en  # For English
-   ```
-
-3. **Reset language detection:**
-   ```bash
-   aiwf-lang reset
-   rm ~/.aiwf-lang
-   ```
-
-### Problem: Missing translations
-
-**Symptoms:**
-- Some text appears in English only
-- Untranslated placeholders
-
-**Solutions:**
-
-1. **Update language files:**
-   ```bash
-   aiwf install --update-lang
-   ```
-
-2. **Check translation files:**
-   ```bash
-   ls .aiwf/i18n/
-   ```
-
-3. **Report missing translations:**
-   ```bash
-   /project:aiwf:report_translation_issue
-   ```
-
----
-
-## Common Error Messages
-
-### "ENOENT: no such file or directory"
-
-**Cause:** Required file or directory missing
-
-**Solution:**
-```bash
-# Recreate AIWF structure
-aiwf install --repair
-```
-
-### "EPERM: operation not permitted"
-
-**Cause:** Permission issues
-
-**Solution:**
-```bash
-# Fix permissions
-chmod -R u+rw .aiwf/
-```
-
-### "EEXIST: file already exists"
-
-**Cause:** Trying to create existing file
-
-**Solution:**
-```bash
-# Force overwrite
-aiwf install --force
-```
-
-### "ValidationError: Invalid feature ID"
-
-**Cause:** Wrong feature ID format
-
-**Solution:**
-```bash
-# Use correct format: FL001, FL002, etc.
-/project:aiwf:create_feature "My Feature"
-```
-
----
-
-## Advanced Debugging
-
-### Enable Debug Mode
-
-```bash
-# Set debug environment variable
-export AIWF_DEBUG=true
-
-# Run with verbose output
-aiwf install --verbose
-```
-
-### Check System Information
-
-```bash
-# Create diagnostic report
-/project:aiwf:diagnostic_report
-```
-
-### Analyze Performance
-
-```javascript
-// Enable performance monitoring
-const benchmark = new PerformanceBenchmark({
-  memoryProfiling: true
-});
-
-const suite = BenchmarkSuites.fullSystem();
-const report = await benchmark.run(suite);
-await benchmark.generateHTMLReport('./performance.html');
-```
-
-### Trace Command Execution
-
-```bash
-# Enable command tracing
-export AIWF_TRACE=true
-
-# View execution logs
-tail -f .aiwf/logs/commands.log
-```
-
----
-
-## Getting Help
-
-If you can't resolve your issue:
-
-1. **Search existing issues:**
-   - [GitHub Issues](https://github.com/moonklabs/aiwf/issues)
-
-2. **Create a new issue with:**
-   - AIWF version: `aiwf --version`
-   - Node.js version: `node --version`
-   - Operating system
-   - Error messages
-   - Steps to reproduce
-
-3. **Join the community:**
-   - Discord: [discord.gg/aiwf](https://discord.gg/aiwf)
-   - Discussions: [GitHub Discussions](https://github.com/moonklabs/aiwf/discussions)
-
-4. **Emergency support:**
-   - Email: support@aiwf.dev (for critical issues only)
-
----
-
-## Prevention Tips
-
-1. **Keep AIWF updated:**
-   ```bash
-   aiwf --check-updates
-   ```
-
-2. **Regular backups:**
-   ```bash
-   /project:aiwf:backup
-   ```
-
-3. **Monitor system health:**
-   ```bash
-   /project:aiwf:health_check
-   ```
-
-4. **Follow best practices:**
-   - Use appropriate compression modes
-   - Commit regularly
-   - Keep documentation updated
-   - Test changes before deploying