From 6442e7ffd0ca9a05f4aaf142c9696a405c602451 Mon Sep 17 00:00:00 2001 From: Backtalk6858 Date: Fri, 26 Jun 2026 13:45:06 -0500 Subject: [PATCH] docs: add structural wrap-up design principle to both builder playbooks --- .../.claude/playbook_agent_builder_agent.md | 17 +++++++++++++++++ .../.claude/playbook_n8n_builder_agent.md | 17 +++++++++++++++++ 2 files changed, 34 insertions(+) diff --git a/agent-builder/.claude/playbook_agent_builder_agent.md b/agent-builder/.claude/playbook_agent_builder_agent.md index 4b6a4e9..b9a7f66 100644 --- a/agent-builder/.claude/playbook_agent_builder_agent.md +++ b/agent-builder/.claude/playbook_agent_builder_agent.md @@ -181,6 +181,23 @@ User must explicitly approve before any production deployment. No auto-promotion Set builder_status = 'approved', then 'deployed' after production deployment completes. Update automation_ideas status = 'deployed'. +## Design Principle: Structural Wrap-up + +Wrap-up steps must be **structural constraints**, not prompt instructions. An agent instructed to "remember to wrap up" will skip those steps under context pressure, error conditions, or LLM divergence. Structural enforcement means the workflow cannot physically reach completion without passing through each wrap-up step. + +**Required wrap-up sequence (every automation must include these):** +1. DB status update — set builder_status to final state (deployed / failed / awaiting_approval) +2. NTFY notification — send final status to user +3. Error log — write execution summary to agent_test_results (even on success) + +**For N8N workflows:** These must be three separate nodes wired in sequence before the End node. The workflow graph enforces them — they cannot be skipped. + +**For claude_agent type:** The system prompt must list these as required FINAL TOOL CALLS in the output format definition — not as "remember to" instructions. Example: "Your final response MUST include: (1) a DB status update, (2) an NTFY notification, (3) a final status JSON. Do not stop before completing all three." + +**For script type:** Wrap-up must be in a `finally:` block — never in the main `try:` body where an exception can skip it. + +**The test:** If you can imagine the automation completing its main task and then stopping before wrap-up, the wrap-up is not structural. Fix it before shipping. + ## Error handling - Any unhandled exception: set builder_status = 'failed', log to agent_test_results with test_level=0 and status='fail', send NTFY alert - Always release the claim (reset builder_status to 'not_started') if failing before Step 3 so another run can retry diff --git a/agent-builder/.claude/playbook_n8n_builder_agent.md b/agent-builder/.claude/playbook_n8n_builder_agent.md index 2ab53ad..9feee1b 100644 --- a/agent-builder/.claude/playbook_n8n_builder_agent.md +++ b/agent-builder/.claude/playbook_n8n_builder_agent.md @@ -211,6 +211,23 @@ User must explicitly approve before production import. No auto-promotion in v1. 3. Set builder_status = 'deployed' 4. Update automation_ideas status = 'deployed' +## Design Principle: Structural Wrap-up + +Wrap-up steps must be **structural constraints**, not prompt instructions. An agent instructed to "remember to wrap up" will skip those steps under context pressure, error conditions, or LLM divergence. Structural enforcement means the workflow cannot physically reach completion without passing through each wrap-up step. + +**Required wrap-up sequence (every automation must include these):** +1. DB status update — set builder_status to final state (deployed / failed / awaiting_approval) +2. NTFY notification — send final status to user +3. Error log — write execution summary to agent_test_results (even on success) + +**For N8N workflows:** These must be three separate nodes wired in sequence before the End node. The workflow graph enforces them — they cannot be skipped. + +**For claude_agent type:** The system prompt must list these as required FINAL TOOL CALLS in the output format definition — not as "remember to" instructions. Example: "Your final response MUST include: (1) a DB status update, (2) an NTFY notification, (3) a final status JSON. Do not stop before completing all three." + +**For script type:** Wrap-up must be in a `finally:` block — never in the main `try:` body where an exception can skip it. + +**The test:** If you can imagine the automation completing its main task and then stopping before wrap-up, the wrap-up is not structural. Fix it before shipping. + ## Error handling - Any unhandled exception: set builder_status = 'failed', log to agent_test_results (test_level=0, status='fail'), send NTFY alert - Always release the claim (reset to 'not_started') if failing before Step 5 so another run can retry