# Agent Guidelines for n8n Debugger

Guidelines for AI assistants using n8n-debugger to autonomously debug workflows.

## Available Commands

```
n8n-debug init                                    Initialize directory with guidelines and .env template
n8n-debug list                                    List all workflows
n8n-debug search <term>                           Search workflows by name
n8n-debug errors <workflow-id> [limit]            Show recent errors for a workflow
n8n-debug health <workflow-id>                    Check workflow health and execution stats
n8n-debug validate <file.json>                    Validate workflow JSON before pushing
n8n-debug activate <id> [<id> ...]                Activate one or more workflows
n8n-debug deactivate <id> [<id> ...]              Deactivate one or more workflows
n8n-debug diff <id1> <id2>                        Compare two workflows and show differences
n8n-debug compare-executions <wf-id> <ok> <fail>  Compare successful vs failed executions
n8n-debug retry <execution-id> [--load-workflow]  Retry a failed execution
n8n-debug pull [workflow-id|all]                  Pull workflow(s) to local JSON files
n8n-debug pull-executions <id> [limit]            Pull execution data for a workflow
n8n-debug push <file.json>                        Push local workflow changes to n8n
n8n-debug clean [all|workflows|executions]        Remove downloaded files
n8n-debug help                                    Show help

Flags:
  --json                                          Output in JSON format (for agent use)
```

## Critical Rules

### Never Auto-Push Workflows

You MUST NOT execute `n8n-debug push` without explicit user confirmation.

**Correct workflow:**
1. Analyze errors and identify fix
2. Edit workflow JSON
3. Run `n8n-debug validate workflows/file.json`
4. **Ask user**: "Should I push this fix to n8n?"
5. Only after confirmation: `n8n-debug push workflows/file.json`

### Workflow Field Restrictions

**Important:** Only core workflow fields can be updated via push:

- `name` - Workflow name
- `nodes` - Workflow nodes and their configuration
- `connections` - Node connections
- `settings` - Workflow settings
- `staticData` - Static workflow data

Read-only fields (like `active`, `tags`, timestamps) are filtered out and must be changed in the n8n UI.

### Always Validate Before Committing

Always validate workflows before suggesting commits or pushes.

```bash
# After editing any workflow JSON:
n8n-debug validate workflows/filename.json

# Or with structured output:
n8n-debug validate workflows/filename.json --json
```

## Recommended Agent Workflow

### 1. Diagnostic Phase
```bash
# Find the failing workflow
n8n-debug search "workflow name" --json

# Check overall health
n8n-debug health <workflow-id> --json

# Get detailed error information
n8n-debug errors <workflow-id> --json
```

### 2. Analysis Phase
```bash
# Pull workflow and executions
n8n-debug pull <workflow-id>
n8n-debug pull-executions <workflow-id>

# Analyze the workflow JSON and execution data
# Identify the root cause
```

### 3. Fix Phase
```bash
# Edit the workflow JSON
# Make targeted fixes based on error analysis

# ALWAYS validate
n8n-debug validate workflows/<file>.json --json
```

### 4. Deployment Phase
```bash
# Point out the issue and explain your fix to the user
# Show validation results

# ASK FOR PERMISSION:
# "I've identified the issue: [explanation]
#  I've made the following fix: [changes]
#  Validation passed. Should I push this to n8n?"

# Only after user confirms:
n8n-debug push workflows/<file>.json

# Remind user to test manually:
# "Fix pushed. Please test the workflow in n8n to verify it works."
```

### 5. Cleanup Phase
```bash
# After user confirms fix works:
n8n-debug clean workflows
```

## Using JSON Output

All commands support `--json` flag for structured, parseable output:

```bash
n8n-debug list --json
n8n-debug search "term" --json
n8n-debug errors <id> --json
n8n-debug health <id> --json
n8n-debug validate <file> --json
```

**Why use JSON:**
- Structured data for programmatic analysis
- Clear success/failure signals
- Easy to extract specific fields
- Better for reasoning about complex errors

## Testing Limitations

**Important:** Workflows cannot be tested locally before pushing.

- Validation only checks JSON structure, not execution logic
- Must push to n8n to test actual workflow behavior
- Always inform user to manually test after pushing

## Common Patterns

### Quick Health Check
```bash
n8n-debug health <workflow-id> --json
```
Returns: status, success rate, recent errors, error patterns

### Batch Operations
```bash
# Activate multiple workflows
n8n-debug activate <id1> <id2> <id3>

# Deactivate workflows
n8n-debug deactivate <id1> <id2>
```

### Compare Workflow Versions
```bash
n8n-debug diff <workflow-id-1> <workflow-id-2> --json
```

## Error Handling

When encountering errors:
1. Use `n8n-debug errors <id> --json` for structured error data
2. Check error patterns in health check output
3. Compare failed vs successful executions if available
4. Look for common issues: missing credentials, invalid node configs, connection problems

### Retrying Failed Executions

Use the `retry` command to re-run a failed execution:

```bash
# Retry with the original workflow version (as it was when execution failed)
n8n-debug retry <execution-id>

# Retry with the latest workflow version (if workflow was fixed since failure)
n8n-debug retry <execution-id> --load-workflow

# JSON output for programmatic use
n8n-debug retry <execution-id> --json
```

**When to use `--load-workflow`:**
- Use it when the workflow has been updated/fixed since the execution failed
- Without this flag, n8n retries using the exact workflow version from the original execution

**Example workflow:**
```bash
# 1. Find failed executions
n8n-debug errors <workflow-id> --json

# 2. Retry a specific failed execution
n8n-debug retry 439587 --json

# Output:
# {
#   "originalExecutionId": "439587",
#   "newExecution": {
#     "id": "475983",
#     "status": "running",
#     "mode": "retry",
#     "workflowId": "WuJWbw4jWqbVuYXc"
#   }
# }
```

## Best Practices

- **Always explain your changes** before asking to push
- **Validate immediately** after editing workflow JSON
- **Ask before pushing** - never assume permission
- **Use JSON output** for programmatic analysis
- **Clean up after** - remove downloaded files when done
- **Inform about testing** - remind user to verify fixes manually