---
description: Find solutions for common .NET/Next.js development errors with root-cause analysis
argument-hint: "[error-message]"
allowed-tools: Read, Bash, Glob, Grep
---

# Troubleshoot - Find Solutions for Errors

Find solutions for common .NET/Next.js development errors and problems.

## Usage

```
/morph-troubleshoot <error description or keywords>
```

## Examples

```bash
/morph-troubleshoot DbContext second operation
/morph-troubleshoot Include returns empty
/morph-troubleshoot PendingModelChanges
/morph-troubleshoot next/navigation error
```

## 3-Level Workflow

### Level 1: Search Standards (Primary)

Search the known problems and standards files for matching patterns:

```bash
# Search in framework standards
Grep: "{keywords}" in framework/standards/ (glob: "*.md")
Grep: "{keywords}" in .morph/framework/standards/ (glob: "*.md")
```

Read matching files and extract the relevant solution sections.

### Level 2: Search Codebase (Automatic)

If standards don't cover the issue, search the codebase for the error pattern:

```bash
Grep: "{error pattern}" in src/ (glob: "*.cs,*.tsx,*.ts")
```

Check if similar patterns exist elsewhere in the codebase that work correctly.

### Level 3: Web Search (If needed)

**IMPORTANT:** If levels 1 and 2 don't find a solution, use Claude Code's native **WebSearch** tool to search the following sources:

**Recommended queries:**

```
# GitHub Issues (.NET)
site:github.com/dotnet/aspnetcore {error}
site:github.com/dotnet/efcore {error}

# Stack Overflow
site:stackoverflow.com [entity-framework-core] {error}
site:stackoverflow.com [next.js] {error}

# Microsoft Documentation
site:learn.microsoft.com {error}
```

**WebSearch usage example:**

If the user asks about a SignalR error:
1. First: search standards/codebase via Grep
2. If not found: WebSearch with `site:github.com/dotnet/aspnetcore SignalR connection closed`
3. Return formatted relevant links

## Available Categories

| Category | Description |
|-----------|-----------|
| `efcore` | Entity Framework Core, DbContext, migrations, queries |
| `nextjs` | Next.js App Router, pages, components, routing |
| `auth` | Authentication, authorization, tokens, claims |
| `deploy` | Deployment, CI/CD, pipelines, containers |

## Output Format

When finding a solution, present in the following format:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔴 CRITICAL: {problem title}

📁 File: {path to file with solution}
📂 Section: {specific section}

❌ Error:
   {error pattern that identifies the problem}

💡 Cause:
   {root cause explanation}

✅ Solution:
   {code or steps to resolve}

📚 See full: open {file}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

## Quick Troubleshooting

### Most Common Problems

| Error | Quick Fix |
|------|----------------|
| `PendingModelChangesWarning` | `dotnet ef migrations add <Name>` before update |
| `DbContext second operation` | Use `IDbContextFactory` for background tasks |
| `Include()` empty | Use `HasMany(x => x.Nav)` instead of `HasMany<T>()` |
| `next/navigation error` | Check App Router vs Pages Router usage |

---

**Input:** $ARGUMENTS