troubleshooting-assistant

Included with Lifetime

$97 forever

Diagnoses and resolves MCP server registration failures, GPU detection, BigQuery authentication, index build failures, import errors, search quality issues, and performance problems.

AI Agents

What this skill does


# Troubleshooting Assistant Skill

Expert diagnostic system for identifying and resolving Claude Patent Creator issues.

## When to Use

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.

## Troubleshooting Methodology

```
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)
```

## Common Issues & Quick Fixes

| 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 rebuild-index` |
| Import errors | Activate venv: `venv\Scripts\activate` |
| Slow searches | Check GPU usage, reduce top_k, disable HyDE |
| Irrelevant results | Rephrase query with MPEP terminology |

## Detailed Issue Guides

### MCP Server Issues

**Problems:** Server not loading, tools don't work/return errors

- 5-step diagnostic workflow
- Path verification and correction
- Dependency troubleshooting
- Server restart procedures

### GPU & BigQuery Issues

**Problems:** GPU not detected, slow performance, BigQuery auth fails, query timeouts

- CUDA detection and PyTorch reinstallation
- Performance diagnostics and optimization
- BigQuery authentication and permissions
- Timeout configuration

### Index, Dependencies & Configuration

**Problems:** Index not found, build fails, ModuleNotFoundError, import errors, env vars not loading, irrelevant search results

- Index rebuild procedures
- OOM (Out of Memory) solutions
- Virtual environment activation
- Pydantic validation errors
- Configuration troubleshooting
- Search quality tuning

## Diagnostic Tools

### Health Check Suite

```bash
# Full system health
patent-creator health

# Individual components
python scripts/test_gpu.py
python scripts/test_bigquery.py
python scripts/test_analyzers.py
python scripts/test_install.py
```

### Component Isolation

```python
# Test MPEP search
python -c "from mcp_server.mpep_search import MPEPIndex; \
           index = MPEPIndex(); \
           print('OK' if index.search('test', top_k=1) else 'FAILED')"

# Test BigQuery
python -c "from mcp_server.bigquery_search import BigQueryPatentSearch; \
           search = BigQueryPatentSearch(); \
           print('OK' if search.search_patents('neural network', limit=1) else 'FAILED')"

# Test analyzers
python -c "from mcp_server.claims_analyzer import ClaimsAnalyzer; \
           analyzer = ClaimsAnalyzer(); \
           print('OK' if analyzer.analyze('1. A test claim.') else 'FAILED')"
```

- 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 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 rebuild-index` |
| "Out of memory" | Index Build | Reduce batch size |
| "Validation error" | Input | Check Pydantic model parameters |

### Diagnostic Commands

```bash
# System health
patent-creator health

# Test components
python scripts/test_gpu.py
python scripts/test_bigquery.py
python scripts/test_install.py

# Check registration
claude mcp list

# Check paths
patent-creator verify-config

# Enable debug logging
export PATENT_LOG_LEVEL=DEBUG
```

Files: 1

Size: 4.6 KB

Complexity: 8/100

Category: AI Agents

Source: https://github.com/robthepcguy/claude-patent-creator/tree/main/skills/troubleshooting-assistant

Related in AI Agents

skill-development

Included

Comprehensive meta-skill for creating, managing, validating, auditing, and distributing Claude Code skills and slash commands (unified in v2.1.3+). Provides skill templates, creation workflows, validation patterns, audit checklists, naming conventions, YAML frontmatter guidance, progressive disclosure examples, and best practices lookup. Use when creating new skills, validating existing skills, auditing skill quality, understanding skill architecture, needing skill templates, learning about YAML frontmatter requirements, progressive disclosure patterns, tool restrictions (allowed-tools), skill composition, skill naming conventions, troubleshooting skill activation issues, creating custom slash commands, configuring command frontmatter, using command arguments ($ARGUMENTS, $1, $2), bash execution in commands, file references in commands, command namespacing, plugin commands, MCP slash commands, Skill tool configuration, or deciding between skills vs slash commands. Delegates to docs-management skill for official documentation.

AI Agentsscripts

reprompter

Included

Transform messy prompts into well-structured, effective prompts — single or multi-agent. Use when: "reprompt", "reprompt this", "clean up this prompt", "structure my prompt", rough text needing XML tags and best practices, "reprompter teams", "repromptception", "run with quality", "smart run", "smart agents", multi-agent tasks, audits, parallel work, anything going to agent teams. Don't use when: simple Q&A, pure chat, immediate execution-only tasks. See "Don't Use When" section for details. Outputs: Structured XML/Markdown prompt, quality score (before/after), optional team brief + per-agent sub-prompts, agent team output files. Success criteria: Single mode quality score ≥ 7/10; Repromptception per-agent prompt quality score 8+/10; all required sections present, actionable and specific.

AI Agentsscripts

adaptive-compaction

Included

Adaptive add-on policy and recovery layer that decides WHEN to compact, prune, snapshot, or fork -- replacing fixed-percent auto-compaction across Claude Code, Codex, and MCP-capable hosts. Trigger on auto-compact timing or damage: "when should I compact", "is it safe to compact now or start a fresh session", "auto-compact fires too early/mid-task", "switching to an unrelated task but the window still has space", "context rot", "answers get worse the longer the session runs", "the agent forgot the plan or my decisions after it summarized", "add a layer on top that manages context without changing the agent", raising autoCompactWindow to give the policy room, or installing/tuning a cross-tool compaction policy or PreCompact hook -- even when "compaction" is never said but the problem is context-window pressure or post-summarization memory loss. Do NOT use to summarize a conversation, build RAG, write a summarization prompt (decides WHEN not HOW), or answer max-context-length trivia.

AI Agentsscripts

agent-skill-creator

Included

Create cross-platform agent skills from workflow descriptions. Activates when users ask to create an agent, automate a repetitive workflow, create a custom skill, or need advanced agent creation. Triggers on phrases like create agent for, automate workflow, create skill for, every day I have to, daily I need to, turn process into agent, need to automate, create a cross-platform skill, validate this skill, export this skill, migrate this skill. Supports single skills, multi-agent suites, transcript processing, template-based creation, interactive configuration, cross-platform export, and spec validation.

AI Agentsscripts

llm-wiki

Included

Use when building or maintaining a persistent personal knowledge base (second brain) in Obsidian where an LLM incrementally ingests sources, updates entity/concept pages, maintains cross-references, and keeps a synthesis current. Triggers include "second brain", "Obsidian wiki", "personal knowledge management", "ingest this paper/article/book", "build a research wiki", "compound knowledge", "Memex", or whenever the user wants knowledge to accumulate across sessions instead of being re-derived by RAG on every query.

AI Agentsscripts

skill-master

Included

Agent Skills authoring, evaluation, and optimization. Create, edit, validate, benchmark, and improve skills following the agentskills.io specification. Use when designing SKILL.md files, structuring skill folders (references, scripts, assets), ingesting external documentation into skills, running trigger evals, benchmarking skill quality, optimizing descriptions, or performing blind A/B comparisons. Keywords: agentskills.io, SKILL.md, skill authoring, eval, benchmark, trigger optimization.

AI Agentsscripts