N8N Agent Gap Analysis vs. Performance Report

Date: 2025-11-12
Agent: /n8n (N8N Workflow Expert)
Reference: AGENT_PERFORMANCE_SELF_ANALYSIS_2025-11-12.md (exe-build session)
Purpose: Identify communication/strategic action gaps in current /n8n agent configuration

🎯 CRITICAL INSIGHT FROM PERFORMANCE REPORT

User's Desired Behavioral Pattern:

User request
  ↓
Gather available evidence IMMEDIATELY (files, logs, existing workflows)
  ↓
Analyze evidence AUTONOMOUSLY (no permission asking)
  ↓
Present findings + root causes + recommendations
  ↓
User decides next action

Current `/n8n` Agent Pattern (PROBLEMATIC):

User request
  ↓
Identify which phase/framework applies
  ↓
Ask clarifying questions
  ↓
Present plan to user
  ↓
Ask for approval
  ↓
Execute framework

GAP: Agent prioritizes framework presentation over evidence analysis

🚨 IDENTIFIED GAPS IN CURRENT `/n8n` AGENT

Gap #1: "Ask User First" Default (CRITICAL)

Current Protocol (Lines 39-46):

2. **Ask clarifying questions:**
   Q: What triggers this workflow? (webhook, schedule, manual)
   Q: What data do you have at the start?
   Q: What's the desired output?
   Q: Any integrations needed?
   Q: Do you have an existing workflow JSON to fix?

Problem: Agent asks questions BEFORE analyzing available evidence

Performance Report Learning:
- ❌ "Don't ask user 'what's broken?' when logs show exactly what's broken"
- ❌ Agent asked "What symptoms?" when logs contained answers
- ✅ Should: Read workflow JSON FIRST, analyze FIRST, present findings FIRST

Impact on N8N Agent:
When user says: /n8n This workflow has errors: C:\path\to\workflow.json

Current behavior (WRONG):
1. Agent asks: "What symptoms are you experiencing?"
2. Agent asks: "When did this break?"
3. Agent asks: "What's your immediate goal?"

Should be (RIGHT):
1. Agent reads workflow.json immediately
2. Agent validates JSON syntax
3. Agent checks node structure, connections, credentials
4. Agent presents: "Found 3 issues: duplicate IDs, invalid connections, missing credentials"

Gap #2: Framework-First vs. Evidence-First (CRITICAL)

Current Protocol (Phase 1-7 structure):
- Phase 1: Discovery → Ask questions
- Phase 2: Diagnosis/Design → Plan approach
- Phase 3: Implementation → Build/fix
- Phase 4: Validation → Check
- Phase 5: Testing Guidance → Explain
- Phase 6: Optimization → Improve
- Phase 7: Handover → Deliver

Problem: Framework presented/discussed before evidence analyzed

Performance Report Learning:
- ❌ Agent offered "Option A/B/C - which diagnostic path?" when user wanted direct action
- ❌ Agent said "Here's what the 5-pass diagnostic will cover..." instead of analyzing
- ✅ Should: Analyze FIRST, present findings FIRST, recommend frameworks AFTER

Impact on N8N Agent:
When user says: /n8n Fix this workflow: workflow.json

Current behavior (WRONG):
1. "I'll follow the 7-phase workflow..."
2. "Phase 1: Discovery - I need to ask some questions..."
3. "Phase 2: Diagnosis - I'll check these aspects..."
4. "Shall I proceed?"

Should be (RIGHT):
1. [Reads workflow.json immediately]
2. [Analyzes JSON structure, nodes, connections]
3. "Found 3 issues: [lists issues with line numbers]"
4. "Root cause: Invalid node references at lines 45, 78, 92"
5. "Shall I fix these now?"

Gap #3: "Documentation Alignment" Misinterpretation (MEDIUM)

Current Protocol: No specific handling for "documentation alignment" or "current state" triggers

Performance Report Learning:
- User says "documentation alignment" = Sync documented knowledge with actual reality
- NOT: Document the diagnostic process
- Agent should: Check actual state → Compare to documented state → Present gaps

Impact on N8N Agent:
When user says: /n8n Document the current state of my workflows

Current behavior (LIKELY WRONG):
1. "I'll create documentation about how to document workflows..."
2. "Which workflows do you want documented?"

Should be (RIGHT):
1. [Scans C:\Users\total\n8n-workflows]
2. [Reads each workflow JSON]
3. [Checks INVENTORY.md]
4. "Found 15 workflows in folder, but INVENTORY.md only lists 8"
5. "7 workflows not documented: [lists them]"
6. "Shall I update INVENTORY.md with all workflows?"

Gap #4: Workflow File Path Assumption (MEDIUM)

Current Protocol: Expects user to provide file path

Line 74: 1. **Read the workflow JSON** (user provides file path)

Problem: If user says "fix my workflow" without path, agent asks for path instead of searching

Performance Report Learning:
- Logs exist? Read them FIRST
- Files exist? Check them FIRST
- Only ask when data genuinely unavailable

Impact on N8N Agent:
When user says: /n8n My content-generator workflow is broken

Current behavior (WRONG):
1. "What's the file path to the workflow?"

Should be (RIGHT):
1. [Searches C:\Users\total\n8n-workflows\ for "content-generator.json"]
2. [Finds content-generator-v1.json]
3. [Reads and analyzes it]
4. "Found content-generator-v1.json. Analyzing..."
5. [Presents findings]

Gap #5: Collaborative Questioning vs. Autonomous Diagnosis (HIGH)

Current Protocol (Line 15):
- ✅ "Work collaboratively (pair programming)"

Problem: "Collaborative" interpreted as "ask lots of questions"

Performance Report Learning:
- Agent's "conversational design prioritized user input over autonomous investigation"
- User wanted autonomous analysis, not conversation
- Questions should be RARE, not DEFAULT

Impact on N8N Agent:
When fixing workflows, agent asks:
- ❌ "What triggers this workflow?" → Read JSON, node type shows it's webhook
- ❌ "What's the desired output?" → Read JSON, connections show output node
- ❌ "Any integrations needed?" → Read JSON, node types show Google Sheets, LinkedIn

Should be:
- ✅ Read JSON → Extract all configuration → Present findings → Ask ONLY if ambiguous

📊 SPECIFIC PROTOCOL ADDITIONS NEEDED

Addition #1: Evidence-First Protocol (CRITICAL)

Add to n8n_expert_protocol.md BEFORE Phase 1:

## 🔴 EVIDENCE-FIRST PROTOCOL (MANDATORY - READ THIS FIRST)

**Before any questioning, planning, or framework presentation:**

### Step 1: Gather Available Evidence IMMEDIATELY
- User mentioned workflow file? → READ IT NOW (don't ask questions)
- User said "my workflows"? → SCAN C:\Users\total\n8n-workflows\ NOW
- User said "fix this"? → ANALYZE the JSON structure NOW
- User referenced error? → LOOK for error patterns NOW

**DO NOT:**
- ❌ Ask "What's the file path?" when you can search for it
- ❌ Ask "What's broken?" when you can read JSON and find issues
- ❌ Ask "What's the trigger?" when JSON shows node type
- ❌ Present diagnostic frameworks before analyzing evidence

**DO:**
- ✅ Read workflow JSON files immediately
- ✅ Validate JSON syntax first
- ✅ Analyze node structure, connections, credentials
- ✅ Present findings BEFORE asking questions

### Step 2: Analyze Evidence AUTONOMOUSLY
- What does the JSON show? (nodes, connections, parameters)
- What's broken? (syntax errors, invalid references, missing config)
- What's the root cause? (duplicate IDs, wrong node types, credential issues)
- What's the impact? (workflow won't import, execution fails, data loss)

### Step 3: Present Findings FIRST
**Format:**

Analysis Complete

Workflow: [name from JSON]
Nodes: [count] nodes found
Issues Found: [count]

Issue #1: [Type]

Location: Node "[name]" (line X)
Problem: [specific issue]
Root Cause: [why it happened]
Fix: [what needs to change]

[Repeat for each issue]

Recommendation: [what to do next]

**THEN and ONLY THEN:** Ask clarifying questions if needed

### When to Ask Questions (RARE)
- ✅ Multiple valid interpretations (user's intent unclear)
- ✅ Business logic unknown (user's specific requirements)
- ✅ Credential choice (which API key to use)
- ✅ After presenting findings, ask which fix to apply first

### Anti-Pattern Example (NEVER DO THIS)
❌ User: "/n8n Fix workflow.json"
❌ Agent: "What symptoms are you experiencing?"

✅ User: "/n8n Fix workflow.json"
✅ Agent: [Reads workflow.json] → "Found 3 issues: [lists them]"

Addition #2: Autonomous Diagnosis Mode

Add to n8n_expert_protocol.md after Evidence-First Protocol:

## 🤖 AUTONOMOUS DIAGNOSIS MODE

When user provides workflow file path OR name:
1. **Immediate Actions (NO ASKING):**
   - Read the workflow JSON
   - Validate syntax (check for JSON errors)
   - Check node structure (IDs, names, types, positions)
   - Validate connections (source/destination exist)
   - Check credentials (referenced correctly)
   - Analyze expressions (syntax correct)
   - Check TypeVersions (match node capabilities)

2. **Present Diagnosis Report:**
```markdown
## Workflow Diagnosis: [workflow-name]

**File:** [path]
**Status:** [✅ Valid / ⚠️ Issues Found / ❌ Critical Errors]

### Summary
- Total Nodes: [count]
- Connections: [count]
- Credentials: [count]
- Issues: [count]

### Issues Found
[List each issue with location, cause, fix]

### Root Cause Analysis
[Why these issues occurred]

### Recommended Actions
1. [Priority fixes]
2. [Optional improvements]

THEN Ask User:
"Shall I fix these issues now?"
"Would you like me to optimize while I'm at it?"

NOT:
- "What symptoms are you experiencing?"
- "When did this break?"
- "What's your goal with this workflow?"

---

### Addition #3: Workflow Search Intelligence

**Add to `n8n_expert_protocol.md` in Phase 2:**

```markdown
## 🔍 INTELLIGENT WORKFLOW LOCATION

**When user references workflow by name (not full path):**

1. **Automatic Search Pattern:**
```bash
# Search workflow directory
Search: C:\Users\total\n8n-workflows\*{workflow-name}*.json

# If found → Read immediately
# If multiple found → List options, let user choose
# If not found → Search Downloads, Desktop, then ask

Examples:

User: "/n8n Fix my content-generator workflow"
Agent:
- [Searches for content-generator.json]
- [Finds: content-generator-v1.json, content-generator-v2.json]
- "Found 2 versions: v1 (2025-10-12), v2 (2025-11-05). Which to analyze?"

User: "/n8n My lead-scoring workflow is broken"
Agent:
- [Searches for lead-scoring.json]
- [Finds: lead-scoring-v1.json]
- [Reads and analyzes immediately]
- "Analyzing lead-scoring-v1.json..."
- [Presents findings]

NOT:
- "What's the full file path?" (search first!)

---

### Addition #4: "Current State" Trigger

**Add to `n8n_expert_protocol.md` in Phase 1:**

```markdown
## 📊 CURRENT STATE AWARENESS MODE

**When user says:**
- "Document current state of my workflows"
- "What workflows do I have?"
- "Show me my workflow inventory"
- "Sync workflow documentation"

**This means:** Scan actual workflows + compare to documented state

**Immediate Actions:**
1. **Scan workflow directory:**
   - List all .json files in C:\Users\total\n8n-workflows\
   - Read each workflow (name, nodes, trigger type, status)

2. **Check existing documentation:**
   - Read C:\Users\total\n8n-workflows\INVENTORY.md (if exists)
   - Compare: What's documented vs. What actually exists

3. **Present Current State Report:**
```markdown
## Workflow Inventory Report

**Total Workflows Found:** [count]

### Active Workflows
1. [name] - [trigger type] - [node count] nodes - Last modified: [date]
2. [...]

### Undocumented Workflows (Not in INVENTORY.md)
1. [name] - [trigger type] - Status: Unknown

### Documented but Missing (In INVENTORY.md but file not found)
1. [name] - Status: File missing

**Recommendation:** Update INVENTORY.md with current state?

NOT:
- Present framework for how to document
- Ask "Which workflows do you want documented?"

---

### Addition #5: Reduce Questioning in Phase 1

**REPLACE Phase 1 Discovery questions section with:**

```markdown
### Phase 1: Discovery 🔍 (REVISED)

**Goal:** Understand what the user needs

**STEP 1: Check for Immediate Evidence (MANDATORY)**
- User provided file path? → READ IT NOW
- User mentioned workflow name? → SEARCH for it NOW
- User said "my workflows"? → SCAN directory NOW
- User said "current state"? → ANALYZE inventory NOW

**STEP 2: Analyze Evidence First**
If evidence found:
- Read workflow JSON
- Analyze structure
- Identify issues
- Present findings
- SKIP to Phase 2 with analysis complete

**STEP 3: Ask Questions ONLY IF Evidence Unavailable**

Ask ONLY these questions if truly needed:
- Q: Building new workflow or fixing existing? (if unclear from request)
- Q: Which workflow? (if multiple found and name ambiguous)
- Q: Which version? (if v1, v2, v3 all exist)

**DO NOT ASK:**
- ❌ "What triggers this workflow?" → JSON shows node type
- ❌ "What data do you have?" → JSON shows input structure
- ❌ "What's the desired output?" → JSON shows output nodes
- ❌ "What symptoms?" → Analyze JSON to find issues

✅ IMMEDIATE ACTIONS REQUIRED

Priority 1: Update `n8n_expert_protocol.md`

✅ Add "Evidence-First Protocol" section (BEFORE Phase 1)
✅ Add "Autonomous Diagnosis Mode" section
✅ Add "Intelligent Workflow Location" section
✅ Add "Current State Awareness Mode" section
✅ REVISE Phase 1 Discovery (reduce questions)

Priority 2: Update `/n8n` slash command

✅ Add prominent "I analyze workflows autonomously" statement
✅ Add "I read files BEFORE asking questions" principle
✅ Remove/reduce "I ask clarifying questions" emphasis

Priority 3: Add Anti-Pattern Examples

✅ Document what NOT to do (from performance report)
✅ Show wrong vs. right response patterns
✅ Emphasize autonomous analysis over conversation

📊 BEHAVIOR CHANGE SUMMARY

FROM (Current - WRONG):

User: /n8n Fix my workflow
Agent: "What's the file path?"
User: "workflow.json"
Agent: "What symptoms are you experiencing?"
User: [frustrated] "Just read the file!"
Agent: [reads file] "Oh, I see the issues..."

TO (Desired - RIGHT):

User: /n8n Fix my workflow
Agent: [Searches n8n-workflows folder]
Agent: [Finds workflow.json]
Agent: [Reads and analyzes immediately]
Agent: "Analysis complete. Found 3 issues:
       1. Duplicate node ID at line 45
       2. Invalid connection at line 78
       3. Missing credential reference at line 92

       Root cause: Manual editing introduced errors.

       Shall I fix these now?"

🎯 PHILOSOPHICAL SHIFT REQUIRED

Current Philosophy:
- "I'm collaborative, I ask questions to understand your needs"
- "Let me present my diagnostic framework"
- "Tell me what you want me to do"

Required Philosophy:
- "I'm autonomous, I analyze evidence immediately"
- "Here's what I found [already analyzed]"
- "Tell me if you want me to fix what I found"

Key Difference:
- FROM: "May I help you?" (ask permission, then act)
- TO: "Here's what I found." (act first, present results)

🔍 TESTING CHECKLIST (Post-Update)

After implementing protocol updates, test these scenarios:

Test 1: Fix Workflow Without Questioning

User: /n8n Fix workflow.json

Expected:
✅ Agent reads workflow.json immediately (no questions)
✅ Agent presents diagnosis report
✅ Agent asks ONLY: "Shall I fix these issues?"

NOT:
❌ "What's the file path?"
❌ "What symptoms?"
❌ "When did it break?"

Test 2: Search Workflow by Name

User: /n8n My content-generator is broken

Expected:
✅ Agent searches n8n-workflows folder
✅ Agent finds content-generator-v1.json
✅ Agent reads and analyzes immediately
✅ Agent presents findings

NOT:
❌ "What's the full file path?"
❌ "Which workflow exactly?"

Test 3: Current State Documentation

User: /n8n Document current state of my workflows

Expected:
✅ Agent scans n8n-workflows folder
✅ Agent reads INVENTORY.md
✅ Agent compares actual vs. documented
✅ Agent presents discrepancies report

NOT:
❌ "Which workflows do you want documented?"
❌ "Here's how to document workflows..." (process explanation)

Test 4: Autonomous Diagnosis

User: /n8n Analyze all my workflows

Expected:
✅ Agent scans folder immediately
✅ Agent reads each workflow
✅ Agent validates each (syntax, structure, connections)
✅ Agent presents summary report

NOT:
❌ "Which workflows should I analyze?"
❌ "Shall I run diagnostic?"

💡 ADDITIONAL ENHANCEMENTS (Optional but Valuable)

Enhancement 1: Proactive Error Detection

When reading workflow JSON, automatically check common errors:
- Duplicate node IDs
- Missing credentials
- Invalid expressions
- Orphaned nodes
- TypeVersion mismatches

Present: "Proactive scan found 0 issues" or "Found 3 potential issues"

Enhancement 2: Workflow Health Score

After analysis, present health score:

## Workflow Health: 7/10

✅ JSON syntax valid
✅ All nodes connected
⚠️  Missing error handling (reduce to 6/10)
⚠️  Hardcoded values detected (reduce to 5/10)
✅ Credentials referenced correctly

Enhancement 3: Auto-Fix Capability

For simple issues (duplicate IDs, missing commas), offer instant fix:

Found 2 simple issues I can auto-fix:
1. Duplicate node ID → Generate new UUID
2. Missing comma at line 45 → Add comma

Shall I auto-fix these now? (Complex issues require manual review)

📋 SUMMARY OF GAPS

Gap	Severity	Current Behavior	Required Behavior
Ask-First Default	CRITICAL	Asks questions before reading files	Reads files first, asks only if needed
Framework-First	CRITICAL	Presents diagnostic plans	Presents diagnostic findings
No Auto-Search	MEDIUM	Asks for file path	Searches by workflow name
No Current State Mode	MEDIUM	No specific handling	Scans & compares actual vs. documented
Over-Questioning	HIGH	Many clarifying questions	Minimal questions, evidence-based

✅ IMPLEMENTATION PRIORITY

CRITICAL (Do Now):
Add Evidence-First Protocol
Revise Phase 1 Discovery (reduce questions)
Add Autonomous Diagnosis Mode
HIGH (Do Soon):
Add Intelligent Workflow Location
Add Current State Awareness Mode
Update slash command messaging
MEDIUM (Do Later):
Add anti-pattern examples throughout
Add proactive error detection
Add workflow health scoring

End of Gap Analysis

Meta-Note: The /n8n agent was built with comprehensive knowledge (5 files, 1,700+ lines) but inherited the same "ask-first, plan-first" pattern that the performance report identified as problematic. These protocol updates will align /n8n agent behavior with user's desired autonomous analysis pattern.