@awesomate/hosting-mcp 0.12.0 → 0.13.0

package/skill/awesomate-n8n/references/vendor/validation/SKILL.md

@@ -0,0 +1,414 @@
+<!--
+  VENDORED from n8n-builder@d293559 (n8n-validation-expert/SKILL.md) — DO NOT EDIT HERE.
+  Edit the source in ~/Projects/n8n-builder, then re-run:
+    node mcp/scripts/sync-n8n-references.mjs --write
+
+  Awesomate platform overrides — where this file conflicts with
+  ../platform-notes.md, platform-notes wins:
+    - $env is BLOCKED fleet-wide → use {{ $vars.key || 'fallback' }}
+    - Task runners are ON → no $helpers in Code nodes; use HTTP Request nodes
+    - Webhook payloads live at $json.body
+    - saveExecutionProgress must stay false
+-->
+
+# n8n Validation Expert
+
+Expert guide for interpreting n8n editor warnings and execution errors, and reviewing workflow JSON for configuration mistakes.
+
+---
+
+## How This Works
+
+You don't have direct access to the user's n8n instance. The user pastes:
+
+- **Editor warnings** - red/yellow indicators on nodes, "Problem in node" messages
+- **Execution errors** - error output from a failed run
+- **Workflow JSON** - exported or hand-written, to review before import
+
+Your job: interpret the message, identify the node and field at fault, and propose an exact fix the user applies in their n8n editor.
+
+---
+
+## Debugging Philosophy
+
+**Fix early, recheck often**
+
+Debugging is typically iterative:
+- Expect feedback loops
+- Usually 2-3 fix → recheck cycles
+- One error being fixed often reveals the next one
+
+**Key insight**: Fixing errors is an iterative process, not one-shot!
+
+---
+
+## Error Severity Levels
+
+### 1. Errors (Must Fix)
+**Blocks workflow execution** - Must be resolved before activation
+
+**Types**:
+- `missing_required` - Required field not provided
+- `invalid_value` - Value doesn't match allowed options
+- `type_mismatch` - Wrong data type (string instead of number)
+- `invalid_reference` - Referenced node doesn't exist
+- `invalid_expression` - Expression syntax error
+
+**Example** (editor message):
+```
+Problem in node 'Slack'
+Channel name is required
+```
+**Fix**: Provide a channel name (lowercase, no spaces, 1-80 characters)
+
+### 2. Warnings (Should Fix)
+**Doesn't block execution** - Workflow can be activated but may have issues
+
+**Types**:
+- `best_practice` - Recommended but not required
+- `deprecated` - Using old API/feature
+- `performance` - Potential performance issue
+
+**Example**: Slack API can have rate limits → suggest `onError: 'continueRegularOutput'` with Retry On Fail enabled.
+
+### 3. Suggestions (Optional)
+**Nice to have** - Improvements that could enhance workflow
+
+**Types**:
+- `optimization` - Could be more efficient
+- `alternative` - Better way to achieve same result
+
+---
+
+## The Fix-and-Recheck Loop
+
+```
+1. User pastes error / warning
+   ↓
+2. Identify the node and field at fault
+   ↓
+3. Read the error message carefully - it usually names the fix
+   ↓
+4. Propose the exact change (field, value, expression)
+   ↓
+5. User applies it, re-opens the node in the editor or re-executes
+   ↓
+6. Confirm the warning is gone - or interpret the next error
+   ↓
+7. Repeat until clean (usually 2-3 iterations)
+```
+
+### Example
+
+```
+// Iteration 1
+User: "Problem in node 'Slack': Missing required field 'name'"
+Fix:  Set Channel Name (e.g. "general") in the node panel.
+
+// Iteration 2 - user re-opens node, new warning appears
+User: "Missing required field 'text'"
+Fix:  Set Message Text (e.g. "Hello!").
+
+// Iteration 3 - user re-executes
+User: "It ran!"  ✅
+```
+
+**This is normal!** Don't be discouraged by multiple iterations - fixing one required field often surfaces the next.
+
+---
+
+## Review Methodology
+
+When reviewing workflow JSON or a node configuration, check in this order:
+
+### 1. Required fields first
+Most errors are missing required fields. For each node, confirm the fields its operation needs are present (e.g. HTTP Request needs `url`; Slack post needs `channel` + `text`).
+
+### 2. Value validity
+Enum values (`resource`, `operation`, `method`) must match allowed options exactly - they are case-sensitive. Check formats (channel names, emails, URLs).
+
+### 3. Data types
+Numbers as numbers, booleans as booleans - not `"100"` or `"true"`.
+
+### 4. Expressions
+`{{}}` wrapping (with leading `=` in JSON), correct node names in `$node[...]` references, webhook data under `$json.body`.
+
+### 5. Connections and structure
+No connections to nodes that don't exist, Switch rules match output count, no accidentally disconnected nodes.
+
+**Calibrate depth to stakes**: a quick required-fields pass is fine for dev/test workflows; production workflows deserve the full pass including error handling, retries, and rate limiting.
+
+---
+
+## Common Error Types
+
+### 1. missing_required
+**What it means**: A required field is not provided
+
+**How to fix**:
+1. Open the node in the editor - required fields are marked and highlighted when empty
+2. Fill in the missing field with an appropriate value
+
+**Example**:
+```
+Error: "Channel name is required" (property: channel)
+Fix:   Set Channel to "#general"
+```
+
+### 2. invalid_value
+**What it means**: Value doesn't match allowed options
+
+**How to fix**:
+1. Check the error message for allowed values
+2. Check the node's dropdown in the editor for valid options
+3. Update to a valid value (match case exactly)
+
+**Example**:
+```
+Error: "Operation must be one of: post, update, delete" (current: "send")
+Fix:   Set Operation to "post"
+```
+
+### 3. type_mismatch
+**What it means**: Wrong data type for field
+
+**How to fix**:
+1. Check expected type in error message
+2. Convert value to correct type
+
+**Example**:
+```
+Error: "Expected number, got string" (property: limit, current: "100")
+Fix:   limit: 100 (number, not string - remove the quotes in JSON)
+```
+
+### 4. invalid_expression
+**What it means**: Expression syntax error
+
+**How to fix**:
+1. Use the n8n Expression Syntax skill
+2. Check for missing `{{}}` or typos
+3. Verify node/field references
+
+**Example**:
+```
+Error: "Invalid expression: $json.name" (property: text)
+Fix:   "={{$json.name}}" - add the ={{}} wrapper
+```
+
+### 5. invalid_reference
+**What it means**: Referenced node doesn't exist
+
+**How to fix**:
+1. Check node name spelling
+2. Verify node exists in workflow
+3. Update reference to correct name
+
+**Example**:
+```
+Error: "Node 'HTTP Requets' does not exist"
+Fix:   "={{$node['HTTP Request'].json.data}}" - correct the typo
+```
+
+---
+
+## Operator Structure (IF/Switch)
+
+The n8n editor normalizes condition operator structures when you save a node. This matters mainly when **hand-writing workflow JSON for import** - get the structure right so conditions behave correctly:
+
+### 1. Binary Operators (Two Values)
+**Operators**: equals, notEquals, contains, notContains, greaterThan, lessThan, startsWith, endsWith
+
+**Rule**: No `singleValue` property (binary operators compare two values)
+
+```javascript
+{
+  "type": "boolean",
+  "operation": "equals"
+  // no singleValue ✅
+}
+```
+
+### 2. Unary Operators (One Value)
+**Operators**: isEmpty, isNotEmpty, true, false
+
+**Rule**: Must have `singleValue: true` (unary operators check a single value)
+
+```javascript
+{
+  "type": "boolean",
+  "operation": "isEmpty",
+  "singleValue": true  // ✅ Required
+}
+```
+
+### 3. IF/Switch Metadata
+IF v2.2+ and Switch v3.2+ expect complete `conditions.options` metadata. The editor adds it on save - if reviewing JSON that was built in the editor, incomplete metadata will be filled in when the user opens and saves the node.
+
+### What the Editor Cannot Fix
+
+#### 1. Broken Connections
+References to non-existent nodes in the `connections` object
+
+**Solution**: Remove the stale entry from `connections` (or delete and re-draw the connection in the editor)
+
+#### 2. Branch Count Mismatches
+3 Switch rules but only 2 output connections
+
+**Solution**: Add missing connections or remove extra rules
+
+---
+
+## False Positives
+
+### What Are They?
+Warnings that are technically "wrong" but acceptable - or plain incorrect - in your use case.
+
+### Structural False Positives (Ignore)
+
+#### 1. Community/custom nodes reported as "unknown"
+Nodes from community packages (e.g. `CUSTOM.*`, `n8n-nodes-*`) show as unknown node types when reviewing JSON outside the instance that has them installed. If the target instance has the package, this is not an error.
+
+#### 2. Cycles flagged in polling workflows
+Loop-back connections (e.g. Wait → check status → loop back) get flagged as circular dependencies. Cycle-based polling is a legitimate pattern - a cycle is only a bug if there's no exit condition.
+
+### Context-Dependent Warnings
+
+#### 1. "Missing error handling"
+**When acceptable**: Simple workflows, testing/development, non-critical notifications
+**When to fix**: Production workflows handling important data
+
+#### 2. "No retry logic"
+**When acceptable**: APIs with their own retry logic, idempotent operations, manual trigger workflows
+**When to fix**: Flaky external services, production automation
+
+#### 3. "Missing rate limiting"
+**When acceptable**: Internal APIs with no limits, low-volume workflows
+**When to fix**: Public APIs, high-volume workflows
+
+#### 4. "Unbounded query"
+**When acceptable**: Small known datasets, aggregation queries, development/testing
+**When to fix**: Production queries on large tables
+
+Full guide: **[FALSE_POSITIVES.md](FALSE_POSITIVES.md)**
+
+---
+
+## Reviewing Workflow JSON Before Import
+
+When the user pastes a full workflow, check:
+
+1. **Node configurations** - each node valid (required fields, values, types)
+2. **Connections** - no broken references, counts match branch rules
+3. **Expressions** - syntax and node references valid
+4. **Flow** - logical workflow structure, triggers wired correctly
+
+### Common Workflow-Level Errors
+
+#### 1. Broken Connections
+```
+Connection from 'Transform' to 'NonExistent' - target node not found
+```
+**Fix**: Remove stale connection or create the missing node
+
+#### 2. Circular Dependencies
+```
+Circular dependency detected: Node A → Node B → Node A
+```
+**Fix**: Restructure to remove the loop - unless it's intentional cycle-based polling with an exit condition (see False Positives)
+
+#### 3. Multiple Start Nodes
+```
+Multiple trigger nodes found
+```
+**Fix**: Fine if intentional (e.g. webhook + schedule); otherwise remove extras or split into separate workflows
+
+#### 4. Disconnected Nodes
+```
+Node 'Transform' is not connected to workflow flow
+```
+**Fix**: Connect node or remove if unused
+
+---
+
+## Recovery Strategies
+
+### Strategy 1: Start Fresh
+**When**: Configuration is severely broken
+
+**Steps**:
+1. Note the required fields from a fresh node of the same type in the editor
+2. Create minimal valid configuration
+3. Add features incrementally
+4. Re-execute after each addition
+
+### Strategy 2: Binary Search
+**When**: Workflow looks valid but executes incorrectly
+
+**Steps**:
+1. Disable half the nodes
+2. Execute and observe
+3. If works: problem is in disabled nodes
+4. If fails: problem is in remaining nodes
+5. Repeat until problem isolated
+
+### Strategy 3: Clean Stale Connections
+**When**: "Node not found" errors after renaming/deleting nodes
+
+**Steps**:
+1. In the editor: delete and re-draw the affected connections
+2. In JSON: remove entries in the `connections` object whose keys or targets name nodes that no longer exist (connections are keyed by node **name** - renames break them)
+
+---
+
+## Best Practices
+
+### ✅ Do
+
+- Recheck after every significant change (re-open node / re-execute)
+- Read error messages completely - they contain fix guidance
+- Fix errors iteratively (one at a time)
+- Fix errors before worrying about warnings
+- Check required fields first when reviewing JSON
+- Recognize structural false positives (community nodes, polling cycles)
+- Document false positives you accept
+
+### ❌ Don't
+
+- Activate a workflow with unresolved errors
+- Try to fix all errors at once
+- Ignore error messages
+- Assume a fix worked - confirm the warning is gone
+- Hand-fix operator structures the editor normalizes on save
+- Ignore all warnings (some are important!)
+
+---
+
+## Detailed Guides
+
+For comprehensive error catalogs and false positive examples:
+
+- **[ERROR_CATALOG.md](ERROR_CATALOG.md)** - Complete list of error types with examples
+- **[FALSE_POSITIVES.md](FALSE_POSITIVES.md)** - When warnings are acceptable
+
+---
+
+## Summary
+
+**Key Points**:
+1. **Debugging is iterative** (usually 2-3 fix → recheck cycles)
+2. **Errors must be fixed**, warnings are optional
+3. **The editor normalizes operator structures** on save
+4. **Check required fields first**, then values, types, expressions, connections
+5. **False positives exist** - learn to recognize them
+6. **Read error messages** - they contain fix guidance
+
+**Debugging Process**:
+1. Interpret error → propose fix → user applies → recheck
+2. Repeat until clean (usually 2-3 iterations)
+3. Review warnings and decide if acceptable
+4. Activate with confidence
+
+**Related Skills**:
+- n8n Expression Syntax - Fix expression errors
+- n8n Node Configuration - Understand required fields