Auto-audit n8n workflows and generate Notion docs with Claude Sonnet

Upload n8n workflow JSON → auto-audit for reliability & security → Claude drafts business summary & tech report → write to Notion in batches

Who

Operators or automation developers who need to audit n8n workflows and produce documentation pages

You get

After submitting a workflow JSON, a formatted Notion page with audit score, business summary, and technical audit report appears within 30–60 seconds

You need

n8n · notion

Steps

1. Import template and connect credentials

   Import the workflow template into n8n. Bind your Anthropic account credential to the Claude Model Interaction node; bind your Notion account credential to both the Create Notion Document and Append to Notion Document nodes. In Notion, open the target parent page, go to page settings → Connections, and add your integration to grant write access.

2. Submit workflow JSON via form

   Activate the workflow and open the form URL. Upload an exported n8n workflow JSON file (.json), enter the Client Name, and paste the 32-character Notion parent page ID (from the page URL, without dashes). Form fields: Workflow JSON (required, .json only), Client Name (required), Notion Parent Page ID (required).

3. Validate JSON and run static audit

   The workflow automatically reads the uploaded JSON, validates that nodes array and connections object exist, then performs graph analysis: Kahn topological sort for execution order, cycle and unreachable-node detection, plus security scanning for hardcoded secrets, missing timeouts, unauthenticated webhooks, and missing error-handling branches, producing a scored findings list.

4. Construct AI prompt

   Audit results are assembled into a structured prompt for Claude Sonnet. The system instruction demands raw JSON with exactly two keys (businessLogic + auditReport), no markdown fences. The user payload includes workflow name, node count, audit score, execution order, and findings list.

   Execution prompt · Source text。Construct AI Prompt node system field

   Copy prompt

   You are an automation consultant writing client documentation.
   
   Return ONLY a raw JSON object with two keys — no markdown fences, no preamble:
   {
     "businessLogic": "<150-300 word plain-English summary of what this workflow does, when it runs, and what outcomes it produces. No technical node names.>",
     "auditReport":   "<Developer-facing audit findings in Markdown. Bold each severity label. End with an overall assessment paragraph. If no findings, say so.>"
   }

   Execution prompt · Source text。Construct AI Prompt node user template field

   Copy prompt

   Workflow: ${d.workflowName}
   Client: ${d.clientName}
   Nodes: ${d.nodeCount} | Audit Score: ${d.score}/100
   ${d.hasCycles ? 'WARNING: cycles detected in ' + d.cycleNodes.join(', ') : ''}
   
   EXECUTION ORDER:
   ${d.nodeList}
   
   AUDIT FINDINGS:
   ${d.findingsSummary}

5. Generate documentation and parse response

   After Claude Sonnet returns text, the Interpret AI Response node strips markdown fences and parses JSON, validating that both businessLogic and auditReport fields exist. If the model returns empty or malformed output, the workflow throws an error into the error-handling branch.

6. Create Notion page and append blocks in batches

   The Formulate Notion Blocks node converts parsed content into Notion block objects (score callout, business summary, technical audit report, plus cycle/unreachable warnings). Create Notion Document creates a new page under the specified parent, then Split In Batches loops to append blocks with a wait of ~350 ms between batches to avoid Notion rate limits. The source description says 350 ms, but the workflow.json Wait node has amount=35 with no unit specified; after import, verify and adjust to 350 ms or reconfigure based on current Notion API limits. [First-test safety] Before the first test, use a test Notion workspace/parent page, or temporarily disconnect the Notion page-create write nodes; write to production only after the doc content looks correct.

You are a setup assistant for the n8n Workflow Auditor & Notion Doc Generator. The user needs to: 1) configure Anthropic and Notion credentials; 2) confirm form fields and the target Notion parent page ID; 3) know how to export an n8n workflow JSON. Provide a next-step checklist based on the user's credential status and page ID.