troubleshooting-assistant ยท diff
git:20261110.0e87468 to git:20261110.5be8a6c
69 added, 127 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: troubleshooting-assistant
- description: Diagnoses and resolves MCP server registration failures, GPU detection, BigQuery authentication, index build failures, import errors, search quality issues, and performance problems.
+ description: Diagnose MCP registration, dependency, search, GPU and index failures.
---
- # Troubleshooting Assistant Skill
-
- > **Windows:** use `$HOME\patent-creator-venv\Scripts\python.exe` and `$HOME\patent-creator-venv\Scripts\patent-creator.exe` wherever this page says `~/patent-creator-venv/bin/python` or `~/patent-creator-venv/bin/patent-creator`.
-
- Expert diagnostic system for identifying and resolving Claude Patent Creator issues.
-
- ## When to Use
+ # Troubleshooting Assistant
- System not working, error messages, slow performance, MCP server not loading, search returns no results/errors, GPU not detected, BigQuery auth fails, index build fails, tests failing, unexpected behavior.
+ Record the exact error and reproduce the smallest failing operation. Check the installed environment before changing configuration.
- ## Troubleshooting Methodology
+ macOS/Linux:
+ ```bash
+ "$HOME/patent-creator-venv/bin/patent-creator" health
+ ```
+ Windows PowerShell:
+ ```powershell
+ & "$HOME\patent-creator-venv\Scripts\patent-creator.exe" health
```
- Problem Reported
- |
- [1] Gather Information (errors, recent changes, system state)
- |
- [2] Reproduce Issue (minimal test case, consistent?)
- |
- [3] Isolate Component (which part failing? dependencies?)
- |
- [4] Diagnose Root Cause (check logs, test components, verify config)
- |
- [5] Apply Fix (targeted solution, verify works)
- |
- [6] Prevent Recurrence (document, add monitoring, update checks)
+
+ macOS/Linux:
+ ```bash
+ "$HOME/patent-creator-venv/bin/patent-creator" verify-config
```
- ## Common Issues & Quick Fixes
+ Windows PowerShell:
+ ```powershell
+ & "$HOME\patent-creator-venv\Scripts\patent-creator.exe" verify-config
+ ```
- | Issue | Quick Fix |
- |-------|-----------|
- | MCP server not loading | `claude mcp list` -> Re-register if missing |
- | GPU not detected | Reinstall PyTorch with CUDA |
- | BigQuery auth fails | `gcloud auth application-default login` |
- | Index not found | `~/patent-creator-venv/bin/patent-creator setup --rebuild` |
- | Import errors | Use the venv's own commands (`~/patent-creator-venv/bin/...`); nothing needs activating. Reinstall: `~/patent-creator-venv/bin/python -m pip install --upgrade git+https://github.com/RobThePCGuy/Claude-Patent-Creator.git` |
- | Slow searches | Check GPU usage, reduce top_k, disable HyDE |
- | Irrelevant results | Rephrase query with MPEP terminology |
+ Check registration with `claude mcp list`. After repairs, restart Claude Code and exercise the failing MCP operation again.
- ## Detailed Issue Guides
+ ## Component diagnostics
- ### MCP Server Issues
+ The diagnostic scripts live in the plugin source, not in the pip package. Resolve `${CLAUDE_PLUGIN_ROOT}` to the actual plugin folder first. For a source checkout, use its absolute path. Set `PLUGIN_ROOT` below to that location; the example deliberately includes a space. Keep paths quoted.
- **Problems:** Server not loading, tools don't work/return errors
+ macOS/Linux:
+ ```bash
+ PLUGIN_ROOT="/absolute/path/Patent Plugin"
+ ```
- - 5-step diagnostic workflow
- - Path verification and correction
- - Dependency troubleshooting
- - Server restart procedures
+ Windows PowerShell:
+ ```powershell
+ $PLUGIN_ROOT = "C:\absolute\path\Patent Plugin"
+ ```
- ### GPU & BigQuery Issues
+ macOS/Linux:
+ ```bash
+ "$HOME/patent-creator-venv/bin/python" "$PLUGIN_ROOT/scripts/test_install.py"
+ ```
- **Problems:** GPU not detected, slow performance, BigQuery auth fails, query timeouts
+ Windows PowerShell:
+ ```powershell
+ & "$HOME\patent-creator-venv\Scripts\python.exe" "$PLUGIN_ROOT/scripts/test_install.py"
+ ```
- - CUDA detection and PyTorch reinstallation
- - Performance diagnostics and optimization
- - BigQuery authentication and permissions
- - Timeout configuration
+ macOS/Linux:
+ ```bash
+ "$HOME/patent-creator-venv/bin/python" "$PLUGIN_ROOT/scripts/test_analyzers.py"
+ ```
- ### Index, Dependencies & Configuration
+ Windows PowerShell:
+ ```powershell
+ & "$HOME\patent-creator-venv\Scripts\python.exe" "$PLUGIN_ROOT/scripts/test_analyzers.py"
+ ```
- **Problems:** Index not found, build fails, ModuleNotFoundError, import errors, env vars not loading, irrelevant search results
+ Use `scripts/test_gpu.py` for an intended CUDA installation, `scripts/test_google_patents.py` for configured SerpApi, or `scripts/test_bigquery.py` only for configured BigQuery. Use the quoted invocation pattern above and report skipped optional components. Live search tests consume service quota.
- - Index rebuild procedures
- - OOM (Out of Memory) solutions
- - Virtual environment activation
- - Pydantic validation errors
- - Configuration troubleshooting
- - Search quality tuning
+ For credentials saved only with `config set`, prefer the corresponding MCP status/search tools after restarting Claude Code. These standalone diagnostics do not all load saved settings; an unset-key result from a script does not prove that the saved configuration is broken.
- ## Diagnostic Tools
+ ## Repairs
- ### Health Check Suite
+ - Import failure: reinstall the package in the same venv:
+ macOS/Linux:
```bash
- # Full system health
- ~/patent-creator-venv/bin/patent-creator health
-
- # Individual components
- ~/patent-creator-venv/bin/python ${CLAUDE_PLUGIN_ROOT}/scripts/test_gpu.py
- ~/patent-creator-venv/bin/python ${CLAUDE_PLUGIN_ROOT}/scripts/test_bigquery.py
- ~/patent-creator-venv/bin/python ${CLAUDE_PLUGIN_ROOT}/scripts/test_analyzers.py
- ~/patent-creator-venv/bin/python ${CLAUDE_PLUGIN_ROOT}/scripts/test_install.py
+ "$HOME/patent-creator-venv/bin/python" -m pip install --upgrade git+https://github.com/RobThePCGuy/Claude-Patent-Creator.git
```
- ### Component Isolation
-
- ```python
- # Test MPEP search
- ~/patent-creator-venv/bin/python -c "from mcp_server.mpep_search import MPEPIndex; \
- index = MPEPIndex(); index.build_index(); \
- print('OK' if index.search('test', top_k=1) else 'FAILED')"
-
- # Test BigQuery
- ~/patent-creator-venv/bin/python -c "from mcp_server.bigquery_search import BigQueryPatentSearch; \
- search = BigQueryPatentSearch(); \
- print('OK' if search.search_by_keywords('neural network', limit=1) else 'FAILED')"
-
- # Test analyzers
- ~/patent-creator-venv/bin/python -c "from mcp_server.claims_analyzer import ClaimsAnalyzer; \
- analyzer = ClaimsAnalyzer(); \
- print('OK' if analyzer.analyze('1. A test claim.') else 'FAILED')"
+ Windows PowerShell:
+ ```powershell
+ & "$HOME\patent-creator-venv\Scripts\python.exe" -m pip install --upgrade git+https://github.com/RobThePCGuy/Claude-Patent-Creator.git
```
- - Log analysis (debug mode)
- - MCP communication debugging
- - Performance profiling
- - Memory profiling
- - Issue escalation procedures
-
- ## Best Practices for Prevention
-
- 1. Regular health checks (weekly `~/patent-creator-venv/bin/patent-creator health`)
- 2. Monitor logs for warnings/errors
- 3. Keep dependencies updated (test before deploying)
- 4. Backup before changes (especially index rebuilds)
- 5. Document modifications
- 6. Test after changes (run test suite)
- 7. Version control (use git)
- 8. Environment consistency (same Python/CUDA versions)
-
- ## Quick Reference
-
- ### Most Common Errors
-
- | Error | Category | Solution |
- |-------|----------|----------|
- | "Tool not found" | MCP | `claude mcp list` |
- | "ModuleNotFoundError" | Dependencies | Activate venv, reinstall |
- | "CUDA not available" | GPU | Reinstall PyTorch with CUDA |
- | "Permission denied" (BigQuery) | Auth | `gcloud auth application-default login` |
- | "Index not found" | Index | `~/patent-creator-venv/bin/patent-creator rebuild-index` |
- | "Out of memory" | Index Build | Reduce batch size |
- | "Validation error" | Input | Check Pydantic model parameters |
+ - Missing or damaged index: follow the **Index Manager** skill. Check the actual Storage paths, then use `setup --rebuild`; rebuilding does not update source editions.
+ - GPU failure: follow `docs/GPU_SETUP.md` under the plugin root. Avoid choosing a CUDA wheel without checking the GPU architecture.
+ - Build OOM: save `PATENT_EMBED_BATCH_SIZE` as 16 or 8 with `config set`, then retry. CPU mode is available through `PATENT_MPEP_DEVICE=cpu` saved with `config set`.
+ - SerpApi failure: call `check_google_patents_status`; check saved key configuration and quota without printing the key.
+ - BigQuery failure: only if this provider is wanted, follow `/configure-bigquery`.
+ - Search quality: inspect retrieved source text and metadata, vary the query, and distinguish no matches from a service failure.
- ### Diagnostic Commands
+ Enable debug logging if needed:
+ macOS/Linux:
```bash
- # System health
- ~/patent-creator-venv/bin/patent-creator health
-
- # Test components
- ~/patent-creator-venv/bin/python ${CLAUDE_PLUGIN_ROOT}/scripts/test_gpu.py
- ~/patent-creator-venv/bin/python ${CLAUDE_PLUGIN_ROOT}/scripts/test_bigquery.py
- ~/patent-creator-venv/bin/python ${CLAUDE_PLUGIN_ROOT}/scripts/test_install.py
-
- # Check registration
- claude mcp list
-
- # Check paths
- ~/patent-creator-venv/bin/patent-creator verify-config
+ "$HOME/patent-creator-venv/bin/patent-creator" config set PATENT_LOG_LEVEL DEBUG
+ ```
- # Enable debug logging
- export PATENT_LOG_LEVEL=DEBUG
+ Windows PowerShell:
+ ```powershell
+ & "$HOME\patent-creator-venv\Scripts\patent-creator.exe" config set PATENT_LOG_LEVEL DEBUG
```
+
+ Restart Claude Code to apply settings. Restore normal logging with `config unset PATENT_LOG_LEVEL`. Keep credentials out of diagnostic reports.