@polymorphism-tech/morph-spec 3.1.0 → 4.2.0

package/docs/troubleshooting.md

@@ -0,0 +1,269 @@
+# Troubleshooting - CLI Auto Context Detection
+
+Common issues and solutions for MORPH-SPEC auto-detection.
+
+## Claude Code Issues
+
+### Issue: "Claude Code environment not detected"
+
+**Cause**: Auto-detection requires Claude Code CLI to be installed and active.
+
+**Solutions**:
+
+1. **Use wizard mode** (recommended for first-time setup):
+   ```bash
+   morph-spec init --wizard
+   ```
+
+2. **Install Claude Code** and retry:
+   - Download from https://claude.ai/claude-code
+   - Ensure `claude` command is in PATH
+   - Retry `morph-spec init`
+
+3. **Skip auto-detection** and configure manually later:
+   ```bash
+   morph-spec init --skip-detection
+   # Later: morph-spec update --wizard
+   ```
+
+### Issue: "LLM analysis timeout"
+
+**Cause**: Analysis taking longer than 60 seconds (default timeout for interactive mode).
+
+**Solutions**:
+
+1. **Clean project before analysis**:
+   ```bash
+   rm -rf node_modules dist build .next
+   morph-spec init
+   ```
+
+2. **Use wizard mode** (instant):
+   ```bash
+   morph-spec init --wizard
+   ```
+
+3. **Check Claude Code performance**:
+   - Restart Claude Code
+   - Check system resources (CPU, memory)
+
+## LLM Analysis Errors
+
+### Issue: "Schema validation failed"
+
+**Cause**: LLM returned JSON that doesn't match the expected schema.
+
+**Diagnosis**:
+```bash
+# Enable debug mode to see LLM response
+DEBUG=1 morph-spec init
+```
+
+**Solutions**:
+
+1. **Use wizard mode** to provide manual input:
+   ```bash
+   morph-spec init --wizard
+   ```
+
+2. **Report issue** if recurring:
+   - Include project type in issue report
+   - Share anonymized `package.json` or `.csproj` structure
+
+### Issue: "LLM response is not valid JSON"
+
+**Cause**: LLM returned malformed JSON (rare).
+
+**Solutions**:
+
+1. **Retry** - may be a one-time error:
+   ```bash
+   morph-spec init
+   ```
+
+2. **Use wizard mode**:
+   ```bash
+   morph-spec init --wizard
+   ```
+
+## File System Issues
+
+### Issue: "Permission denied" when creating .morph/
+
+**Cause**: Insufficient permissions in project directory.
+
+**Solutions**:
+
+1. **Run with correct permissions**:
+   ```bash
+   sudo morph-spec init  # Unix/Mac
+   # Or run as administrator on Windows
+   ```
+
+2. **Check directory ownership**:
+   ```bash
+   ls -la .  # Should show your user as owner
+   ```
+
+### Issue: Config files getting overwritten
+
+**Cause**: Running `morph-spec update` without reviewing changes.
+
+**Protection**: Auto-detection creates backups:
+- `.morph/project.md.YYYY-MM-DDTHH-MM-SS.backup`
+- `.morph/config/config.json.YYYY-MM-DDTHH-MM-SS.backup`
+
+**Solutions**:
+
+1. **Review diff before approving**:
+   - Auto-detection shows diff when updating
+   - Choose "Edit" to modify before saving
+
+2. **Restore from backup** if needed:
+   ```bash
+   cp .morph/project.md.2026-02-14T10-30-00.backup .morph/project.md
+   ```
+
+3. **Skip auto-detection** during update:
+   ```bash
+   morph-spec update --skip-detection
+   ```
+
+## Detection Accuracy Issues
+
+### Issue: Wrong project type detected
+
+**Example**: Monorepo detected as `nextjs` instead of `monorepo`.
+
+**Solutions**:
+
+1. **Use wizard mode** for accurate manual input:
+   ```bash
+   morph-spec init --wizard
+   ```
+
+2. **Edit config after generation**:
+   - Choose "Edit" during review
+   - Manually correct `type` field in config.json
+
+3. **Report detection issue**:
+   - Helps improve LLM prompt and examples
+
+### Issue: Missing dependencies detected
+
+**Cause**: Auto-detection only reads whitelisted files (package.json, .csproj).
+
+**Solution**:
+
+- This is by design (privacy/security)
+- If critical dependency is missed, manually edit `.morph/project.md`
+
+### Issue: Low confidence score (<70%)
+
+**Cause**: Project structure is unclear or non-standard.
+
+**Solutions**:
+
+1. **Add README.md or CLAUDE.md** with project description
+2. **Use wizard mode** for manual configuration
+3. **Accept low confidence** - configs can be edited later
+
+## Edge Case Handling
+
+### Empty Project (no package.json or .csproj)
+
+**Behavior**: Auto-fallback to wizard mode.
+
+**Solution**: Answer 7 wizard questions to configure manually.
+
+### Monorepo with Multiple Stacks
+
+**Behavior**: Detects all stacks, sets `type: "monorepo"`.
+
+**Example Output**:
+```json
+{
+  "type": "monorepo",
+  "stack": {
+    "frontend": { "tech": "Next.js", "version": "15" },
+    "backend": { "tech": ".NET", "version": "10" }
+  }
+}
+```
+
+### Project with No Database
+
+**Behavior**: `stack.database` set to `null`.
+
+**Warning**: May show "Database technology not detected" in warnings.
+
+### Git Repo Without Remote
+
+**Behavior**: `gitRemote` set to `null`.
+
+**Not an error** - local repos are valid.
+
+## Privacy & Security Concerns
+
+### Question: What data is sent to LLM?
+
+**Answer**: Only sanitized, whitelisted data:
+- package.json (dependencies only, secrets removed)
+- .csproj filenames (not contents)
+- First 500 chars of README.md and CLAUDE.md
+- Directory structure (folder names only)
+- Infrastructure file counts (not contents)
+
+**Never sent**:
+- `.env` files
+- Secrets/passwords/API keys
+- File contents (except whitelisted files)
+- node_modules/
+- Source code
+
+### Question: Is data sent to Anthropic servers?
+
+**Answer**: No. LLM analysis runs locally in Claude Code. No external API calls.
+
+### Question: What if sensitive data is detected?
+
+**Behavior**: Secret redaction removes:
+- API keys (10+ patterns detected)
+- Passwords in connection strings
+- Bearer tokens
+- Private keys (PEM format)
+- GitHub/NPM tokens
+
+**Verification**: Review sanitized context in debug mode:
+```bash
+DEBUG=1 morph-spec init
+```
+
+## Getting Help
+
+### Enable Debug Mode
+
+```bash
+DEBUG=1 morph-spec init
+```
+
+Shows:
+- Full LLM prompts
+- Raw LLM responses
+- Schema validation errors
+- File read operations
+
+### Report Issues
+
+GitHub: https://github.com/polymorphism-tech/morph-spec-framework/issues
+
+Include:
+- MORPH-SPEC version (`morph-spec --version`)
+- Claude Code version
+- Project type (Next.js, Blazor, etc.)
+- Error message (with DEBUG=1 output if possible)
+- Anonymized `package.json` or `.csproj` structure
+
+---
+
+**Need more help?** Check the [CLI Auto Detection Guide](./cli-auto-detection.md).