diff --git a/Docs/Developer-Guide/technical-architecture.md b/Docs/Developer-Guide/technical-architecture.md index c0ccf08..719f09e 100644 --- a/Docs/Developer-Guide/technical-architecture.md +++ b/Docs/Developer-Guide/technical-architecture.md @@ -2525,52 +2525,34 @@ class MCPResponse: request_id: str ``` -#### Error Handling Patterns +#### Issue Handling Patterns -**Exception Hierarchy:** +**Note:** SuperClaude Framework operates through instruction files and does not have runtime exception handling. The only error-generating component is the Python installation script. The following represents conceptual error categories for understanding potential issues: + +**Issue Categories:** ```python -# Exception classes for API error handling +# Conceptual issue types for understanding framework challenges +# (These are not actual classes - SuperClaude is instruction-based) -class SuperClaudeException(Exception): - """Base exception for all SuperClaude Framework errors""" - - def __init__(self, message: str, error_code: str = None, context: Dict = None): - super().__init__(message) - self.error_code = error_code or "SUPERCLAUDE_ERROR" - self.context = context or {} - self.timestamp = datetime.now() +# Component Installation Issues: +# - Missing dependencies during setup +# - File permission problems +# - Incorrect installation paths -class ComponentInstallationError(SuperClaudeException): - """Raised when component installation fails""" - -class AgentCoordinationError(SuperClaudeException): - """Raised when agent coordination fails""" - -class MCPConnectionError(SuperClaudeException): - """Raised when MCP server connection fails""" - -class ValidationError(SuperClaudeException): - """Raised when validation criteria are not met""" +# Configuration Issues: +# - Malformed instruction files +# - Missing required @imports +# - Circular import references -# Usage example with error handling -try: - result = component_manager.install_component("agents", options) - if not result.success: - raise ComponentInstallationError( - f"Installation failed: {result.error}", - error_code="INSTALL_FAILED", - context={"component": "agents", "files": result.installed_files} - ) -except ComponentInstallationError as e: - print(f"Installation error [{e.error_code}]: {e}") - print(f"Context: {e.context}") - # Handle specific installation errors -except SuperClaudeException as e: - print(f"Framework error: {e}") - # Handle general framework errors -except Exception as e: - print(f"Unexpected error: {e}") - # Handle unexpected errors +# MCP Server Issues: +# - Node.js not installed +# - Server configuration problems +# - Connection timeouts + +# Claude Code Integration Issues: +# - Instructions not loading +# - Command recognition problems +# - Behavioral mode conflicts ``` #### Integration Examples @@ -2601,7 +2583,8 @@ async def implement_secure_feature(feature_description: str, security_requiremen ) result = component_manager.install_component(component, install_options) if not result.success: - raise ComponentInstallationError(f"Failed to install {component}") + print(f"Installation failed for {component}: {result.error}") + return False # Exit workflow on installation failure # Step 2: Create task context task_context = TaskContext( @@ -2617,7 +2600,8 @@ async def implement_secure_feature(feature_description: str, security_requiremen activation_result = agent_manager.activate_agents(agent_ids, task_context) if not activation_result.success: - raise AgentCoordinationError("Failed to activate required agents") + print(f"Agent coordination failed: {activation_result.error}") + return False # Exit workflow on agent coordination failure print(f"Activated agents with {activation_result.coordination_pattern} pattern") diff --git a/Docs/User-Guide/commands.md b/Docs/User-Guide/commands.md index 6ee06d5..42c50d3 100644 --- a/Docs/User-Guide/commands.md +++ b/Docs/User-Guide/commands.md @@ -536,19 +536,6 @@ export MORPH_API_KEY="your_key" # For Morphllm killall node # Reset MCP servers ``` -### Error Code Reference - -| Code | Meaning | Quick Fix | -|------|---------|-----------| -| **E001** | Command syntax error | Check command spelling and `/sc:` prefix | -| **E002** | Flag not recognized | Verify flag with `/sc:help flags` | -| **E003** | MCP server connection failed | Check Node.js and run `npm cache clean --force` | -| **E004** | Permission denied | Check file permissions or run with appropriate access | -| **E005** | Timeout exceeded | Reduce scope with `--scope file` or increase `--timeout` | -| **E006** | Memory limit exceeded | Use `--memory-limit` or `--scope module` | -| **E007** | Invalid project structure | Verify you're in a valid project directory | -| **E008** | Dependency missing | Check installation with `SuperClaude --version` | - ### Progressive Support Levels **Level 1: Quick Fix (< 2 min)** @@ -585,14 +572,14 @@ lsof | grep SuperClaude After applying fixes, test with: - [ ] `python3 -m SuperClaude --version` (should show version) - [ ] `/sc:analyze README.md` (should complete without errors) -- [ ] Check MCP servers respond: `SuperClaude status --mcp` +- [ ] Check MCP servers installed: `SuperClaude install --list-components | grep mcp` - [ ] Verify flags work: `/sc:help flags` - [ ] Test basic workflow: `/sc:brainstorm "test"` → should ask questions ## Quick Troubleshooting (Legacy) - **Command not found** → Check installation: `SuperClaude --version` - **Flag error** → Verify against [FLAGS.md](flags.md) -- **MCP error** → Check server configuration: `SuperClaude status --mcp` +- **MCP issue** → Check MCP server installation: `SuperClaude install --components mcp --dry-run` - **No output** → Restart Claude Code session - **Slow performance** → Use `--scope file` or `--no-mcp`