scene-capability-engine 3.0.0

package/docs/troubleshooting.md

@@ -0,0 +1,1135 @@
+# Troubleshooting Guide
+
+> Common issues and solutions for kse
+
+---
+
+**Version**: 1.42.0  
+**Last Updated**: 2026-02-11  
+**Audience**: All Users  
+**Estimated Time**: Reference as needed
+
+---
+
+## Quick Navigation
+
+- [Installation Issues](#installation-issues)
+- [Adoption Issues](#adoption-issues)
+- [Command Issues](#command-issues)
+- [Integration Issues](#integration-issues)
+- [Watch Mode Issues](#watch-mode-issues)
+- [Document Governance Issues](#document-governance-issues)
+- [Platform-Specific Issues](#platform-specific-issues)
+- [Getting More Help](#getting-more-help)
+
+---
+
+## Installation Issues
+
+### Error: "npm install -g kse" fails
+
+**Symptoms:**
+```
+npm ERR! code EACCES
+npm ERR! syscall access
+npm ERR! path /usr/local/lib/node_modules
+```
+
+**Cause:** Insufficient permissions to install global npm packages
+
+**Solutions:**
+
+**Option 1: Use npx (Recommended)**
+```bash
+# No installation needed, run directly
+npx kse status
+npx kse adopt
+```
+
+**Option 2: Fix npm permissions (macOS/Linux)**
+```bash
+# Create npm directory in home folder
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+
+# Add to PATH (add to ~/.bashrc or ~/.zshrc)
+export PATH=~/.npm-global/bin:$PATH
+
+# Reload shell config
+source ~/.bashrc  # or source ~/.zshrc
+
+# Now install
+npm install -g kse
+```
+
+**Option 3: Use sudo (Not Recommended)**
+```bash
+sudo npm install -g kse
+```
+
+---
+
+### Error: "kse: command not found"
+
+**Symptoms:**
+```bash
+$ kse status
+bash: kse: command not found
+```
+
+**Cause:** kse is not in your PATH
+
+**Solutions:**
+
+**Check if kse is installed:**
+```bash
+npm list -g kse
+```
+
+**If installed, find where:**
+```bash
+npm root -g
+# Output: /usr/local/lib/node_modules (or similar)
+```
+
+**Add to PATH:**
+```bash
+# macOS/Linux - Add to ~/.bashrc or ~/.zshrc
+export PATH="/usr/local/bin:$PATH"
+
+# Windows - Add to System Environment Variables
+# C:\Users\YourName\AppData\Roaming\npm
+```
+
+**Verify:**
+```bash
+which kse  # macOS/Linux
+where kse  # Windows
+```
+
+---
+
+### Error: "Node.js version too old"
+
+**Symptoms:**
+```
+Error: kse requires Node.js 14 or higher
+Current version: v12.x.x
+```
+
+**Cause:** kse requires Node.js 14+
+
+**Solution:**
+
+**Update Node.js:**
+```bash
+# Using nvm (recommended)
+nvm install 18
+nvm use 18
+
+# Or download from nodejs.org
+# https://nodejs.org/
+```
+
+**Verify:**
+```bash
+node --version
+# Should show v14.x.x or higher
+```
+
+---
+
+## Adoption Issues
+
+### Error: "Not a git repository"
+
+**Symptoms:**
+```bash
+$ kse adopt
+Error: Not a git repository
+kse requires a git repository to track Specs
+```
+
+**Cause:** kse requires git for version control
+
+**Solution:**
+
+**Initialize git:**
+```bash
+git init
+git add .
+git commit -m "Initial commit"
+
+# Now adopt kse
+kse adopt
+```
+
+**Why git is required:**
+- Specs should be version controlled
+- Team collaboration needs git
+- kse uses git to detect project root
+
+---
+
+### Error: "kse.json already exists"
+
+**Symptoms:**
+```bash
+$ kse adopt
+Error: kse.json already exists
+Use 'kse upgrade' to update existing installation
+```
+
+**Cause:** Project already has kse installed
+
+**Solutions:**
+
+**If you want to upgrade:**
+```bash
+kse upgrade
+```
+
+**If you want to start fresh:**
+```bash
+# Backup existing Specs
+cp -r .kiro .kiro.backup
+
+# Remove kse
+rm kse.json
+rm -rf .kiro
+
+# Re-adopt
+kse adopt
+```
+
+---
+
+### Error: "Permission denied creating .kiro directory"
+
+**Symptoms:**
+```bash
+$ kse adopt
+Error: EACCES: permission denied, mkdir '.kiro'
+```
+
+**Cause:** Insufficient permissions in project directory
+
+**Solution:**
+
+**Check directory permissions:**
+```bash
+ls -la
+```
+
+**Fix permissions:**
+```bash
+# Make sure you own the directory
+sudo chown -R $USER:$USER .
+
+# Or run in a directory you own
+cd ~/projects/my-project
+kse adopt
+```
+
+---
+
+## Command Issues
+
+### Error: "No Specs found"
+
+**Symptoms:**
+```bash
+$ kse status
+No Specs found in .kiro/specs/
+```
+
+**Cause:** No Specs have been created yet
+
+**Solution:**
+
+**Create your first Spec:**
+```bash
+kse spec bootstrap --name 01-00-my-feature --non-interactive
+```
+
+**Or check if Specs exist:**
+```bash
+ls -la .kiro/specs/
+```
+
+---
+
+### Error: "Invalid Spec name format"
+
+**Symptoms:**
+```bash
+$ kse spec bootstrap --name my-feature --non-interactive
+Error: Invalid Spec name format
+Expected: {number}-{number}-{kebab-case-name}
+```
+
+**Cause:** Spec names must follow the format: `XX-YY-feature-name`
+
+**Solution:**
+
+**Use correct format:**
+```bash
+# ✅ Correct
+kse spec bootstrap --name 01-00-user-login --non-interactive
+kse spec bootstrap --name 02-01-fix-auth-bug --non-interactive
+
+# ❌ Wrong
+kse spec bootstrap --name user-login --non-interactive
+kse spec bootstrap --name 01-user-login --non-interactive
+kse spec bootstrap --name UserLogin --non-interactive
+```
+
+---
+
+### Error: "Context export failed"
+
+**Symptoms:**
+```bash
+$ kse context export 01-00-user-login
+Error: Failed to export context
+```
+
+**Possible Causes & Solutions:**
+
+**1. Spec doesn't exist:**
+```bash
+# Check Spec exists
+ls .kiro/specs/01-00-user-login/
+
+# If not, create it
+kse spec bootstrap --name 01-00-user-login --non-interactive
+```
+
+**2. Missing Spec files:**
+```bash
+# Spec needs at least requirements.md
+ls .kiro/specs/01-00-user-login/requirements.md
+
+# Create if missing
+touch .kiro/specs/01-00-user-login/requirements.md
+```
+
+**3. File permission issues:**
+```bash
+# Check permissions
+ls -la .kiro/specs/01-00-user-login/
+
+# Fix if needed
+chmod 644 .kiro/specs/01-00-user-login/*.md
+```
+
+---
+
+### Error: "Task not found"
+
+**Symptoms:**
+```bash
+$ kse task claim 01-00-user-login 1.1
+Error: Task 1.1 not found in tasks.md
+```
+
+**Cause:** Task ID doesn't exist in tasks.md
+
+**Solution:**
+
+**Check tasks.md:**
+```bash
+cat .kiro/specs/01-00-user-login/tasks.md
+```
+
+**Verify task ID format:**
+```markdown
+# tasks.md should have:
+- [ ] 1.1 Task description
+- [ ] 1.2 Another task
+
+# Not:
+- [ ] Task description (missing ID)
+```
+
+---
+
+## Integration Issues
+
+### My AI tool doesn't understand the context
+
+**Symptoms:**
+- AI generates code that doesn't match your Spec
+- AI asks for information already in the Spec
+- AI ignores design decisions
+
+**Solutions:**
+
+**1. Be explicit in your prompt:**
+```
+❌ Bad: "Implement the login feature"
+
+✅ Good: "Please implement the login feature following the 
+requirements and design in the provided context. Pay special 
+attention to the API design and error handling sections."
+```
+
+**2. Verify context was provided:**
+```bash
+# Check context file exists and has content
+cat .kiro/specs/01-00-user-login/context-export.md
+
+# Should contain requirements, design, and tasks
+```
+
+**3. Break down large contexts:**
+```bash
+# Instead of entire Spec, export specific task
+kse prompt generate 01-00-user-login 1.1
+```
+
+**4. Use steering rules:**
+```bash
+# Include project-specific rules
+kse context export 01-00-user-login --include-steering
+```
+
+---
+
+### Context file too large for AI tool
+
+**Symptoms:**
+- AI tool rejects context (too many tokens)
+- AI tool truncates context
+- Error: "Context exceeds maximum length"
+
+**Solutions:**
+
+**1. Use task-specific prompts:**
+```bash
+# Export just one task
+kse prompt generate 01-00-user-login 1.1
+```
+
+**2. Simplify your Spec:**
+- Remove unnecessary details from requirements
+- Condense design documentation
+- Break large Specs into smaller ones
+
+**3. Use a tool with larger context window:**
+- Claude Code: 200K tokens
+- GPT-4 Turbo: 128K tokens
+- Gemini Pro: 1M tokens
+
+---
+
+### AI generates code that doesn't match design
+
+**Symptoms:**
+- Code structure differs from design
+- API endpoints don't match specification
+- Component names are different
+
+**Solutions:**
+
+**1. Improve design specificity:**
+```markdown
+# ❌ Vague
+- Create authentication system
+
+# ✅ Specific
+- Create AuthController class with login() method
+- Method signature: async login(email: string, password: string): Promise<AuthResult>
+- Return { token: string } on success
+- Return { error: string } on failure
+```
+
+**2. Reference design in prompt:**
+```
+"Please implement exactly as specified in the Design section,
+using the exact class names, method signatures, and API endpoints
+documented."
+```
+
+**3. Provide code examples in design:**
+```markdown
+## Example Implementation
+```javascript
+class AuthController {
+  async login(email, password) {
+    // Implementation here
+  }
+}
+```
+```
+
+---
+
+## Watch Mode Issues
+
+### Watch mode not detecting changes
+
+**Symptoms:**
+```bash
+$ kse watch status
+Status: Running
+
+# But editing Spec files doesn't trigger actions
+```
+
+**Solutions:**
+
+**1. Restart watch mode:**
+```bash
+kse watch stop
+kse watch start
+```
+
+**2. Check watch patterns:**
+```bash
+kse watch config
+# Verify patterns include your files
+```
+
+**3. Check file system events:**
+```bash
+# Some editors don't trigger file system events
+# Try saving with "Save As" instead of "Save"
+```
+
+**4. Increase watch delay:**
+```bash
+# If changes are too rapid
+kse watch config --delay 1000
+```
+
+---
+
+### Watch mode consuming too much CPU
+
+**Symptoms:**
+- High CPU usage when watch mode is running
+- System becomes slow
+
+**Solutions:**
+
+**1. Reduce watch scope:**
+```bash
+# Watch only specific Specs
+kse watch start --spec 01-00-user-login
+```
+
+**2. Exclude unnecessary files:**
+```bash
+# Add to watch config
+{
+  "exclude": [
+    "node_modules/**",
+    ".git/**",
+    "*.log"
+  ]
+}
+```
+
+**3. Stop when not needed:**
+```bash
+# Stop watch mode when not actively developing
+kse watch stop
+```
+
+---
+
+### Watch mode actions not executing
+
+**Symptoms:**
+- Watch mode detects changes
+- But actions don't run
+
+**Solutions:**
+
+**1. Check action configuration:**
+```bash
+kse watch config
+# Verify actions are properly configured
+```
+
+**2. Check action logs:**
+```bash
+kse watch logs
+# Look for error messages
+```
+
+**3. Test action manually:**
+```bash
+# Try running the action command directly
+kse context export 01-00-user-login
+```
+
+---
+
+## Document Governance Issues
+
+### Diagnostic not finding violations
+
+**Symptoms:**
+```bash
+$ kse docs diagnose
+✅ Project is compliant
+# But you know there are temporary files
+```
+
+**Cause:** Files don't match temporary patterns or are in unexpected locations
+
+**Solutions:**
+
+**1. Check what patterns are configured:**
+```bash
+kse docs config
+# Look at "Temporary Patterns" section
+```
+
+**2. Add custom patterns if needed:**
+```bash
+kse docs config --set temporary-patterns "*-SUMMARY.md,SESSION-*.md,*-COMPLETE.md,TEMP-*.md,WIP-*.md,MVP-*.md,DRAFT-*.md"
+```
+
+**3. Manually check for violations:**
+```bash
+# Check root directory
+ls *.md
+
+# Should only see: README.md, README.zh.md, CHANGELOG.md, CONTRIBUTING.md
+```
+
+---
+
+### Cleanup not removing files
+
+**Symptoms:**
+```bash
+$ kse docs cleanup
+Deleted 0 file(s)
+# But temporary files still exist
+```
+
+**Possible Causes & Solutions:**
+
+**1. Files don't match temporary patterns:**
+```bash
+# Check file names
+ls *.md
+
+# If file is "notes.md" (doesn't match patterns)
+# Either rename it to match pattern or delete manually
+mv notes.md TEMP-notes.md
+kse docs cleanup
+```
+
+**2. Files are in subdirectories:**
+```bash
+# Cleanup only checks root and Spec directories
+# Check subdirectories manually
+find . -name "*-SUMMARY.md"
+```
+
+**3. Permission issues:**
+```bash
+# Check file permissions
+ls -la *.md
+
+# Fix if needed
+chmod u+w filename.md
+kse docs cleanup
+```
+
+---
+
+### Archive moving files to wrong subdirectory
+
+**Symptoms:**
+```bash
+$ kse docs archive --spec my-spec
+# Files moved to unexpected subdirectories
+```
+
+**Cause:** File type classification based on filename
+
+**Solution:**
+
+**Understand classification rules:**
+- **scripts/** - `.js`, `.py`, `.sh`, "script" in name
+- **reports/** - "report", "analysis", "summary" in name
+- **tests/** - `.test.js`, `.spec.js`, "test" in name
+- **results/** - "result", "output" in name
+- **docs/** - Everything else
+
+**Rename files to match intended subdirectory:**
+```bash
+# Want file in reports/
+mv data.md analysis-report.md
+
+# Want file in scripts/
+mv tool.js test-script.js
+
+# Then archive
+kse docs archive --spec my-spec
+```
+
+---
+
+### Git hooks not blocking commits
+
+**Symptoms:**
+```bash
+$ git commit -m "Add feature"
+# Commit succeeds even with violations
+```
+
+**Possible Causes & Solutions:**
+
+**1. Hooks not installed:**
+```bash
+# Check status
+kse docs hooks status
+
+# If not installed
+kse docs hooks install
+```
+
+**2. Hook file not executable:**
+```bash
+# Check permissions (macOS/Linux)
+ls -la .git/hooks/pre-commit
+
+# Make executable
+chmod +x .git/hooks/pre-commit
+```
+
+**3. Using --no-verify flag:**
+```bash
+# This bypasses hooks
+git commit --no-verify -m "message"
+
+# Remove --no-verify to enable validation
+git commit -m "message"
+```
+
+**4. Not a git repository:**
+```bash
+# Check if .git exists
+ls -la .git/
+
+# If not, initialize git
+git init
+kse docs hooks install
+```
+
+---
+
+### Validation failing for valid structure
+
+**Symptoms:**
+```bash
+$ kse docs validate --spec my-spec
+❌ Missing required file: requirements.md
+# But the file exists
+```
+
+**Possible Causes & Solutions:**
+
+**1. File in wrong location:**
+```bash
+# Check exact path
+ls -la .kiro/specs/my-spec/requirements.md
+
+# Should be directly in Spec directory, not in subdirectory
+```
+
+**2. Wrong Spec name:**
+```bash
+# Check Spec directory name
+ls .kiro/specs/
+
+# Use exact name
+kse docs validate --spec 01-00-my-feature
+```
+
+**3. Case sensitivity (Linux/macOS):**
+```bash
+# File is "Requirements.md" but should be "requirements.md"
+mv Requirements.md requirements.md
+```
+
+---
+
+### Configuration changes not taking effect
+
+**Symptoms:**
+```bash
+$ kse docs config --set root-allowed-files "README.md,CUSTOM.md"
+✅ Configuration updated
+
+$ kse docs diagnose
+# Still reports CUSTOM.md as violation
+```
+
+**Cause:** Configuration file not being read or cached
+
+**Solutions:**
+
+**1. Verify configuration was saved:**
+```bash
+# Check config file
+cat .kiro/config/docs.json
+
+# Should show your changes
+```
+
+**2. Check for typos in key name:**
+```bash
+# Wrong: root-files
+# Correct: root-allowed-files
+
+kse docs config --set root-allowed-files "README.md,CUSTOM.md"
+```
+
+**3. Restart any running processes:**
+```bash
+# If watch mode is running
+kse watch stop
+kse watch start
+```
+
+---
+
+### "Permission denied" when installing hooks
+
+**Symptoms:**
+```bash
+$ kse docs hooks install
+Error: EACCES: permission denied, open '.git/hooks/pre-commit'
+```
+
+**Cause:** Insufficient permissions for .git/hooks directory
+
+**Solutions:**
+
+**1. Check directory permissions:**
+```bash
+ls -la .git/hooks/
+```
+
+**2. Fix permissions:**
+```bash
+# Make hooks directory writable
+chmod u+w .git/hooks/
+
+# Try again
+kse docs hooks install
+```
+
+**3. Check if file is read-only:**
+```bash
+# If pre-commit already exists
+ls -la .git/hooks/pre-commit
+
+# Remove read-only flag
+chmod u+w .git/hooks/pre-commit
+```
+
+---
+
+### Stats showing no data
+
+**Symptoms:**
+```bash
+$ kse docs stats
+⚠️  No execution history found
+```
+
+**Cause:** No governance commands have been run yet
+
+**Solution:**
+
+**Run some governance commands:**
+```bash
+# Run diagnostic
+kse docs diagnose
+
+# Run cleanup
+kse docs cleanup --dry-run
+
+# Now check stats
+kse docs stats
+```
+
+**Note:** Only actual operations are logged (not --dry-run for cleanup/archive)
+
+---
+
+### Report generation fails
+
+**Symptoms:**
+```bash
+$ kse docs report
+Error: ENOENT: no such file or directory, open '.kiro/reports/...'
+```
+
+**Cause:** Reports directory doesn't exist
+
+**Solution:**
+
+**Create reports directory:**
+```bash
+mkdir -p .kiro/reports
+
+# Try again
+kse docs report
+```
+
+**Or let kse create it:**
+```bash
+# Run diagnostic first (creates directory structure)
+kse docs diagnose
+
+# Then generate report
+kse docs report
+```
+
+---
+
+## Platform-Specific Issues
+
+### Windows Issues
+
+#### PowerShell vs CMD
+
+**Issue:** Commands work in CMD but not PowerShell (or vice versa)
+
+**Solution:**
+```powershell
+# Use CMD for kse commands
+cmd /c kse status
+
+# Or configure PowerShell execution policy
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+#### Path separators
+
+**Issue:** Paths with forward slashes don't work
+
+**Solution:**
+```bash
+# ❌ Wrong on Windows
+kse context export .kiro/specs/01-00-user-login
+
+# ✅ Correct on Windows
+kse context export .kiro\specs\01-00-user-login
+
+# ✅ Or use forward slashes (kse handles both)
+kse context export 01-00-user-login
+```
+
+#### Line endings
+
+**Issue:** Files have wrong line endings (CRLF vs LF)
+
+**Solution:**
+```bash
+# Configure git to handle line endings
+git config --global core.autocrlf true
+
+# Or use .gitattributes
+echo "*.md text eol=lf" >> .gitattributes
+```
+
+---
+
+### macOS Issues
+
+#### Gatekeeper blocking kse
+
+**Issue:** "kse cannot be opened because it is from an unidentified developer"
+
+**Solution:**
+```bash
+# kse is installed via npm, so this shouldn't happen
+# But if it does:
+xattr -d com.apple.quarantine $(which kse)
+```
+
+#### Permission issues
+
+**Issue:** "Operation not permitted"
+
+**Solution:**
+```bash
+# Grant Terminal full disk access
+# System Preferences → Security & Privacy → Privacy → Full Disk Access
+# Add Terminal.app
+```
+
+---
+
+### Linux Issues
+
+#### Different shells
+
+**Issue:** Commands work in bash but not zsh (or vice versa)
+
+**Solution:**
+```bash
+# Add kse to PATH in your shell config
+# For bash: ~/.bashrc
+# For zsh: ~/.zshrc
+export PATH="$HOME/.npm-global/bin:$PATH"
+
+# Reload config
+source ~/.bashrc  # or ~/.zshrc
+```
+
+#### Permission issues
+
+**Issue:** "Permission denied" errors
+
+**Solution:**
+```bash
+# Check file permissions
+ls -la $(which kse)
+
+# Should be executable
+chmod +x $(which kse)
+```
+
+---
+
+## Getting More Help
+
+### Before Asking for Help
+
+**Gather information:**
+```bash
+# kse version
+kse --version
+
+# Node.js version
+node --version
+
+# npm version
+npm --version
+
+# Operating system
+uname -a  # macOS/Linux
+ver       # Windows
+
+# Current directory structure
+ls -la .kiro/
+```
+
+### Where to Get Help
+
+**1. Documentation:**
+- [Quick Start Guide](quick-start.md)
+- [FAQ](faq.md)
+- [Command Reference](command-reference.md)
+
+**2. GitHub Issues:**
+- Search existing issues: https://github.com/heguangyong/scene-capability-engine/issues
+- Create new issue: https://github.com/heguangyong/scene-capability-engine/issues/new
+
+**3. GitHub Discussions:**
+- Ask questions: https://github.com/heguangyong/scene-capability-engine/discussions
+- Share tips and tricks
+- Connect with other users
+
+**4. Community:**
+- Discord: [Join our Discord](https://discord.gg/kse)
+- Twitter: [@kse_dev](https://twitter.com/kse_dev)
+
+### Creating a Good Issue Report
+
+**Include:**
+1. **What you tried to do**
+2. **What you expected to happen**
+3. **What actually happened**
+4. **Error messages** (full text)
+5. **Environment info** (OS, Node version, kse version)
+6. **Steps to reproduce**
+
+**Example:**
+```markdown
+## Description
+Context export fails for Spec with Chinese characters in filename
+
+## Steps to Reproduce
+1. Create Spec: kse spec bootstrap --name 01-00-用户登录 --non-interactive
+2. Run: kse context export 01-00-用户登录
+3. Error occurs
+
+## Expected Behavior
+Context should export successfully
+
+## Actual Behavior
+Error: Invalid filename
+
+## Environment
+- OS: macOS 13.0
+- Node: v18.12.0
+- kse: v1.0.0
+
+## Error Message
+```
+Error: EINVAL: invalid filename
+```
+```
+
+---
+
+## Related Documentation
+
+- **[Quick Start Guide](quick-start.md)** - Get started with kse
+- **[FAQ](faq.md)** - Frequently asked questions
+- **[Command Reference](command-reference.md)** - All kse commands
+- **[Integration Modes](integration-modes.md)** - Using kse with AI tools
+
+---
+
+## Summary
+
+**Most Common Issues:**
+1. **Installation** - Use npx or fix npm permissions
+2. **Command not found** - Add kse to PATH
+3. **Spec name format** - Use XX-YY-feature-name format
+4. **Context too large** - Use task-specific prompts
+5. **Watch mode** - Restart or check configuration
+6. **Document governance** - Check patterns and permissions
+
+**Quick Fixes:**
+```bash
+# Restart kse watch mode
+kse watch stop && kse watch start
+
+# Verify installation
+kse --version
+
+# Check Spec structure
+ls -la .kiro/specs/
+
+# Test context export
+kse context export spec-name
+
+# Check document compliance
+kse docs diagnose
+
+# Clean up temporary files
+kse docs cleanup --dry-run
+```
+
+**Still stuck?** → [Create an issue](https://github.com/heguangyong/scene-capability-engine/issues/new)
+
+---
+
+**Version**: 1.42.0  
+**Last Updated**: 2026-02-11
+