docs(09): create phase plan

Phase 09: Batch Operations - 4 plans in 4 waves - 3 autonomous, 1 with checkpoint - Ready for execution Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-03 21:01:06 -05:00
parent 3ca89c3815
commit a409671dc6
5 changed files with 817 additions and 4 deletions
@@ -0,0 +1,251 @@
+---
+phase: 09-batch-operations
+plan: 02
+type: execute
+wave: 2
+depends_on: [09-01]
+files_modified: [n8n-workflow.json]
+autonomous: true
+
+must_haves:
+  truths:
+    - "Batch operations execute sequentially, not in parallel"
+    - "Each container shows progress as it completes"
+    - "One container failure does not abort remaining batch"
+    - "Final message shows summary with failures emphasized"
+  artifacts:
+    - path: "n8n-workflow.json"
+      provides: "Sequential batch execution with error handling"
+      contains: "Loop Over Items"
+  key_links:
+    - from: "Loop Over Items node"
+      to: "Execute Container Action"
+      via: "Single item per iteration (batch size 1)"
+      pattern: "batchSize.*1"
+    - from: "Error handler"
+      to: "Continue loop"
+      via: "Log failure, increment counter, proceed"
+      pattern: "failureCount"
+    - from: "Batch summary"
+      to: "Telegram editMessageText"
+      via: "Formatted result with failure details"
+      pattern: "Failed.*reason"
+---
+
+<objective>
+Implement sequential batch execution with per-container progress, error isolation, and failure-emphasized summaries.
+
+Purpose: Enable multi-container operations that don't fail entirely when one container has issues.
+Output: Loop Over Items execution pattern with progress updates and actionable error reporting.
+</objective>
+
+<execution_context>
+@/home/luc/.claude/get-shit-done/workflows/execute-plan.md
+@/home/luc/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/09-batch-operations/09-CONTEXT.md
+@.planning/phases/09-batch-operations/09-RESEARCH.md
+@.planning/phases/09-batch-operations/09-01-SUMMARY.md
+@n8n-workflow.json
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Add Loop Over Items for sequential batch execution</name>
+  <files>n8n-workflow.json</files>
+  <action>
+Implement the sequential execution loop for batch operations.
+
+1. After "Route Batch Action" (from Plan 01), add Code node "Initialize Batch State":
+   - Input: matched containers array, action type, chat_id, message_id (for editing)
+   - Output batch state object:
+     ```javascript
+     return {
+       json: {
+         containers: $json.allMatched, // Array of container objects
+         action: $json.action, // 'update', 'start', 'stop', 'restart'
+         totalCount: $json.allMatched.length,
+         successCount: 0,
+         failureCount: 0,
+         warningCount: 0,
+         results: [], // Array of { name, status: 'success'|'error'|'warning', reason? }
+         chatId: $json.chatId,
+         messageId: $json.messageId,
+         currentIndex: 0
+       }
+     };
+     ```
+
+2. Add HTTP node "Send Batch Start Message":
+   - POST to Telegram sendMessage (new message, not edit - we'll edit this one during progress)
+   - Text: "Starting batch {action} for {N} containers..."
+   - Save message_id from response for progress edits
+
+3. Add Loop Over Items node "Batch Loop":
+   - Input: containers array
+   - Batch Size: 1 (critical - sequential execution)
+   - Output: Single container per iteration
+
+4. For each iteration, the loop should:
+   - Edit progress message with current container name
+   - Execute the action (reuse existing action execution nodes where possible)
+   - Handle success or error
+   - Update counters and results array
+   - Continue to next item
+
+5. Important: Use n8n's "Continue On Fail" option on HTTP Request nodes within the loop so one failure doesn't abort the whole batch.
+
+Note from RESEARCH: n8n Loop Over Items with "Continue (using error output)" has known issues. Use HTTP Request's "Continue On Fail" and check status code in subsequent Code node instead.
+  </action>
+  <verify>
+Test with mock batch of 3 containers:
+- Loop executes 3 times (one per container)
+- Batch state tracks progress correctly
+- Initial message is sent before loop starts
+  </verify>
+  <done>Sequential loop executes containers one at a time with batch state tracking</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Add per-container progress updates and action execution</name>
+  <files>n8n-workflow.json</files>
+  <action>
+Wire action execution within the loop with progress feedback.
+
+1. Inside the loop, add Code node "Build Progress Message":
+   - Input: current container, batch state
+   - Output message text:
+     ```
+     Batch {action} in progress...
+
+     Current: {containerName}
+     Progress: {current}/{total}
+
+     Success: {successCount}
+     Failed: {failureCount}
+     ```
+   - Rate limit consideration: Only edit message every container (small batches <5). For larger batches, research suggests editing every 3-5 items, but since typical batch is 2-5 containers, edit every time is fine.
+
+2. Add HTTP node "Edit Progress Message":
+   - POST to Telegram editMessageText
+   - Use saved progress_message_id from batch start
+   - parse_mode: HTML
+
+3. Add Switch node "Route Batch Loop Action" (within loop):
+   - update: Execute full update flow (pull image, check digest, stop, remove, create, start)
+   - start: Execute container start
+   - stop: Execute container stop
+   - restart: Execute container restart
+
+4. For each action type, wire to existing action execution nodes where possible:
+   - Start: Can reuse "Execute Immediate Action" from Phase 8 or create dedicated "Execute Batch Start"
+   - Stop/Restart: Similar reuse pattern
+   - Update: This is complex - need to execute the full update sequence per container
+
+5. Add Code node "Handle Action Result" after each action execution:
+   - Check HTTP response status or exec output
+   - Determine success/error/warning:
+     - Success: Container action completed normally
+     - Warning: "Already stopped", "No update available", "Already running"
+     - Error: Network error, timeout, pull failed, etc.
+   - Update batch state: increment appropriate counter, add to results array
+   - Output updated batch state for next iteration
+
+6. Key pattern for continue-on-error:
+   - HTTP nodes: Enable "Continue On Fail"
+   - After HTTP node, Code node checks `$json.error` or `$json.statusCode >= 400`
+   - Log failure to results array but don't throw - return updated state to continue loop
+  </action>
+  <verify>
+Test batch update with 2 containers where one has no update available:
+- First container: pulls, updates, succeeds
+- Second container: "No update available" -> warning
+- Progress message updates for each container
+- Both counted in results (1 success, 1 warning)
+  </verify>
+  <done>Per-container progress shown during execution; actions execute correctly; errors logged but don't abort batch</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Add batch summary with failure emphasis</name>
+  <files>n8n-workflow.json</files>
+  <action>
+Create the final summary message after batch completes.
+
+1. After Loop Over Items completes, add Code node "Build Batch Summary":
+   - Input: final batch state with all results
+   - Build summary following pattern from CONTEXT: "Summary emphasizes failures over successes"
+   - Format:
+     ```html
+     <b>Batch {action} Complete</b>
+
+     {if errors exist:}
+     <b>Failed ({errorCount}):</b>
+     - {containerName}: {reason}
+     - {containerName}: {reason}
+
+     {if warnings exist AND Claude's discretion to show them:}
+     <b>Warnings ({warningCount}):</b>
+     - {containerName}: {reason}
+
+     <b>Successful:</b> {successCount}/{totalCount}
+     ```
+   - Per CONTEXT, Claude's discretion on warnings. Recommendation: Show warning count but not individual warnings unless there are few: `Warnings: 2 (containers already in desired state)`
+
+2. Add HTTP node "Send Batch Summary":
+   - POST to Telegram editMessageText
+   - Edit the progress message to show final summary
+   - Add inline keyboard with "Back to List" button
+
+3. Error classification in the result handler (Task 2):
+   - ERROR (red, show in summary):
+     - HTTP status 4xx/5xx from Docker API
+     - "image pull failed", "timeout", "permission denied"
+     - Container not found during execution
+   - WARNING (yellow, optional in summary):
+     - "Already stopped" (for stop action)
+     - "Already running" (for start action)
+     - "No update available" (for update action)
+     - HTTP 304 Not Modified
+
+4. Summary should be actionable - if something failed, user knows what and why, not just a count.
+  </action>
+  <verify>
+Test batch with mixed results:
+- 2 success, 1 error, 1 warning
+- Summary shows: "Failed (1): containerX: Connection timeout"
+- Summary shows: "Warnings: 1"
+- Summary shows: "Successful: 2/4"
+- "Back to List" button works
+  </verify>
+  <done>Final summary shows after batch; failures emphasized with names and reasons; warnings handled per discretion; navigation button returns to list</done>
+</task>
+
+</tasks>
+
+<verification>
+1. Workflow imports successfully in n8n
+2. "update plex sonarr radarr" executes all three sequentially
+3. Progress message updates for each container
+4. One failure doesn't abort remaining containers
+5. Final summary shows clear failure/success breakdown
+6. Errors include container name and reason
+</verification>
+
+<success_criteria>
+- Batch of 3 containers executes sequentially (not parallel)
+- Each container shows progress as it completes
+- If container 2 fails, container 3 still attempts
+- Summary: "Failed (1): sonarr: image pull timeout" + "Successful: 2/3"
+- User can navigate back to container list after batch
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/09-batch-operations/09-02-SUMMARY.md`
+</output>