// You see a variable used in a filter
"where": "@contains(item(), 'keyword')"

// And you ASSUME it's an array of objects, so you write:
"value": "@items('Loop')?['PropertyName']"  // ← WRONG!

// item() without property → Array of STRINGS!
// Correct usage:
"value": "@items('Loop')"  // ← RIGHT!

Use Task tool with subagent_type="Explore" and thoroughness="very thorough"

Prompt: "Research [PLATFORM] best practices and optimization guidelines for workflow refactoring, focusing on [CONNECTORS/NODES USED].

Platform: [Power Automate / n8n / Make / Zapier / Other]

Search in Docs/ directory for:
1. Platform best practices documentation (Docs/{Platform}_Documentation/)
2. Connector/node-specific optimization guidelines
3. Data structure specifications (what properties exist, array vs object)
4. Common performance anti-patterns
5. Error handling best practices
6. API rate limit optimization strategies
7. Expression/formula optimization patterns
8. Security best practices

Focus on finding:
- **DATA STRUCTURE DETAILS** (output schemas, property names, data types)
- Performance optimization opportunities
- Reliability improvements (error handling, retry logic)
- Maintainability enhancements (naming, structure, comments)
- Security improvements (credential handling, input validation)
- API efficiency (batching, filtering, pagination)
- Platform-specific recommendations

For each connector/node in the flow, find:
- Output schema/structure (CRITICAL!)
- Recommended configuration patterns
- Known limitations to consider
- Optimization techniques
- Common mistakes to avoid

Return specific file paths, sections, and exact recommendations."

Use WebSearch tool with targeted queries:

Examples:
- "Power Automate GetFileItems output schema properties"
- "Power Automate array of strings vs array of objects filter syntax"
- "n8n HTTP Request node output structure"
- "Make iterator data structure format"

Search for:
- Official Microsoft Learn documentation
- Platform-specific forums (Power Users Community)
- Official API documentation
- Verified Stack Overflow answers (check dates!)

Use AskUserQuestion tool with specific questions:

Example:
{
  "questions": [{
    "question": "Your flow uses `contains(item(), 'CNESST')`. Can you confirm what type of data is in your variable?",
    "header": "Data Type",
    "options": [
      {
        "label": "Array of strings",
        "description": "Like ['CNESST 2025-01', 'INVALIDITÉ 2025-02']"
      },
      {
        "label": "Array of objects",
        "description": "Like [{'Nom': 'CNESST 2025-01'}, {'Nom': 'INVALIDITÉ 2025-02'}]"
      }
    ],
    "multiSelect": false
  }]
}

Use Task tool with subagent_type="general-purpose"

Prompt: "Generate complete refactored workflow JSON for [PLATFORM] with the following requirements:

Platform: [Power Automate / n8n / Make / Zapier / Other]
Original Flow: [ORIGINAL_JSON]
User Requirements: [USER_REFACTORING_REQUEST]
Best Practices Found: [RESEARCH_FINDINGS]
Improvements to Implement: [CHANGE_PLAN]

Create a complete, valid workflow JSON that:
1. Maintains 100% functional equivalence to original (unless user requested changes)
2. Implements all high-priority improvements
3. Adds comprehensive error handling (platform-specific)
4. Optimizes for performance (batching, filtering, concurrency)
5. Follows platform best practices from documentation
6. Includes clear, descriptive action names
7. Adds comments explaining complex logic
8. Uses valid IDs/GUIDs as required by platform
9. Has correct dependencies/execution order
10. Is ready for copy-paste into platform's import/code feature
11. Respects API limits with appropriate delays/batching
12. Includes proper initialization of all variables
13. Validates inputs before processing
14. Implements retry logic for transient failures

Platform-specific requirements:
- Power Automate: Use Scopes for error handling, proper runAfter chains
- n8n: Use Error Trigger nodes, proper node connections
- Make: Use error handlers, proper routing
- Zapier: Use error paths, filters

Return ONLY the complete JSON with no placeholders or TODOs."

undefined

undefined

{
  "comment": "Refactored workflow - [Date] - Implements [key improvements]",
  "definition": {
    // Complete, valid, platform-specific JSON
    // Ready for copy-paste/import
    // No placeholders or TODOs
  }
}

{
  "Apply_to_each": {
    "foreach": "@body('Get_all_items')?['value']",
    "actions": {
      "Get_user_details": {
        "type": "ApiConnection",
        "inputs": {
          "host": {"connectionName": "shared_office365users"},
          "method": "get",
          "path": "/users/@{items('Apply_to_each')?['Email']}"
        }
      }
    }
  }
}

{
  "Get_all_items_with_users": {
    "type": "ApiConnection",
    "inputs": {
      "host": {"connectionName": "shared_sharepointonline"},
      "method": "get",
      "path": "/datasets/@{parameters('site')}/tables/@{parameters('list')}/items",
      "queries": {
        "$expand": "Author,Editor",
        "$select": "Id,Title,Author/DisplayName,Author/Email"
      }
    }
  }
}

{
  "Send_email": {
    "type": "ApiConnection",
    "inputs": {
      "host": {"connectionName": "shared_office365"},
      "method": "post",
      "path": "/Mail"
    }
  }
}

{
  "Try_Send_Email": {
    "type": "Scope",
    "actions": {
      "Send_email": {
        "type": "ApiConnection",
        "inputs": {
          "host": {"connectionName": "shared_office365"},
          "method": "post",
          "path": "/Mail"
        }
      }
    }
  },
  "Catch_Email_Error": {
    "type": "Scope",
    "runAfter": {
      "Try_Send_Email": ["Failed", "TimedOut"]
    },
    "actions": {
      "Log_Error": {
        "type": "Compose",
        "inputs": {
          "error": "@result('Try_Send_Email')",
          "timestamp": "@utcNow()"
        }
      },
      "Notify_Admin": {
        "type": "ApiConnection",
        "inputs": {
          "host": {"connectionName": "shared_office365"},
          "method": "post",
          "path": "/Mail",
          "body": {
            "To": "admin@company.com",
            "Subject": "Flow Error: Email Send Failed",
            "Body": "@body('Log_Error')"
          }
        }
      }
    }
  }
}

{
  "Apply_to_each": {
    "foreach": "@body('Get_items')?['value']",
    "actions": {
      "Independent_HTTP_Call": {
        "type": "Http",
        "inputs": {
          "method": "POST",
          "uri": "https://api.example.com/process",
          "body": "@item()"
        }
      }
    }
  }
}

{
  "Apply_to_each": {
    "foreach": "@body('Get_items')?['value']",
    "runtimeConfiguration": {
      "concurrency": {
        "repetitions": 10
      }
    },
    "actions": {
      "Independent_HTTP_Call": {
        "type": "Http",
        "inputs": {
          "method": "POST",
          "uri": "https://api.example.com/process",
          "body": "@item()"
        }
      }
    }
  }
}

{
  "actions": {
    "Compose": {
      "type": "Compose",
      "inputs": "@body('HTTP')?['data']"
    },
    "Compose_2": {
      "type": "Compose",
      "inputs": "@first(body('Compose'))"
    },
    "HTTP_2": {
      "type": "Http",
      "inputs": {
        "uri": "https://api.example.com/send",
        "body": "@body('Compose_2')"
      }
    }
  }
}

{
  "actions": {
    "Extract_User_Data_From_API_Response": {
      "type": "Compose",
      "inputs": "@body('Get_Users_From_External_API')?['data']"
    },
    "Get_First_Active_User": {
      "type": "Compose",
      "inputs": "@first(body('Extract_User_Data_From_API_Response'))"
    },
    "Send_Welcome_Email_To_User": {
      "type": "Http",
      "inputs": {
        "uri": "https://api.example.com/send",
        "body": "@body('Get_First_Active_User')"
      }
    }
  }
}

{
  "HTTP_Call": {
    "type": "Http",
    "inputs": {
      "uri": "https://api.example.com/data",
      "headers": {
        "Authorization": "Bearer sk-1234567890abcdef"
      }
    }
  }
}

{
  "Initialize_API_Key": {
    "type": "InitializeVariable",
    "inputs": {
      "variables": [{
        "name": "APIKey",
        "type": "String",
        "value": "@parameters('SecureAPIKey')"
      }]
    }
  },
  "HTTP_Call": {
    "type": "Http",
    "inputs": {
      "uri": "https://api.example.com/data",
      "authentication": {
        "type": "Raw",
        "value": "@concat('Bearer ', variables('APIKey'))"
      }
    },
    "runAfter": {
      "Initialize_API_Key": ["Succeeded"]
    }
  }
}

Task tool, subagent_type="Explore", thoroughness="very thorough"

Task tool, subagent_type="general-purpose"

{
  "Filtrer_dossier_CNESST": {
    "type": "Query",
    "inputs": {
      "from": "@variables('ListeDesDossier')",
      "where": "@contains(toLower(item()), 'cnesst')"  // ← item() without property!
    }
  },
  "LoopCNESST": {
    "foreach": "@body('Filtrer_dossier_CNESST')",
    "actions": {
      "DossierPlusRécent_CNESST": {
        "type": "SetVariable",
        "inputs": {
          "name": "DossierPlusRecent",
          "value": "@items('LoopCNESST')?['Nom']"  // ← BUG: Accessing 'Nom' property!
        }
      }
    }
  }
}