docs(10.1): create UAT gap closure plans (08-09)

2026-02-08 09:35:34 -05:00
parent b74fb3c19c
commit f3ab7cf312
3 changed files with 370 additions and 3 deletions
@@ -0,0 +1,153 @@
+---
+phase: 10.1-aggressive-workflow-modularization
+plan: 08
+type: execute
+wave: 1
+depends_on: []
+files_modified: [n8n-actions.json]
+autonomous: true
+gap_closure: true
+
+must_haves:
+  truths:
+    - "Stopping an already-stopped container returns helpful 'already stopped' message"
+    - "Starting an already-started container returns helpful 'already started' message"
+    - "Container not found returns clear error message"
+    - "Server errors are handled gracefully with descriptive messages"
+  artifacts:
+    - path: "n8n-actions.json"
+      provides: "Format Stop Result, Format Start Result, Format Restart Result nodes with statusCode handling"
+      contains: "statusCode"
+  key_links:
+    - from: "n8n-actions.json Format Stop Result"
+      to: "HTTP 304/404/500 detection"
+      via: "response.statusCode check"
+      pattern: "statusCode.*304|404|500"
+---
+
+<objective>
+Fix container action result formatting to properly handle Docker API HTTP status codes (304, 404, 500) in addition to existing message-based detection.
+
+Purpose: Close UAT gap where stopping an already-stopped container showed a failure message instead of "already stopped"
+Output: Updated n8n-actions.json with comprehensive status code handling
+</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/10.1-aggressive-workflow-modularization/10.1-UAT.md
+@.planning/phases/10.1-aggressive-workflow-modularization/10.1-CONTEXT.md
+@n8n-actions.json
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Add statusCode checks to Format Stop/Start/Restart Result nodes</name>
+  <files>n8n-actions.json</files>
+  <action>
+Update three Code nodes in n8n-actions.json:
+- **Format Stop Result** (id: code-format-stop-result)
+- **Format Start Result** (id: code-format-start-result)
+- **Format Restart Result** (id: code-format-restart-result)
+
+Each node currently checks `response.message` and `response.error` patterns. Add statusCode checks BEFORE the existing checks:
+
+```javascript
+const response = $input.item.json;
+const containerName = response.containerName;
+
+// Check HTTP status codes first (Docker API with onError:continueRegularOutput)
+if (response.statusCode) {
+  if (response.statusCode === 304) {
+    // Already in desired state
+    return {
+      success: true,
+      message: `✅ ${containerName} is already {stopped|started}`
+    };
+  } else if (response.statusCode === 404) {
+    return {
+      success: false,
+      message: `❌ Container ${containerName} not found`
+    };
+  } else if (response.statusCode >= 500) {
+    return {
+      success: false,
+      message: `❌ Server error {stopping|starting|restarting} ${containerName}: ${response.statusMessage || 'Unknown error'}`
+    };
+  }
+}
+
+// Then fall through to existing message-based checks...
+```
+
+**Per-action text variations:**
+- Stop: "already stopped", "stopping"
+- Start: "already started", "starting"
+- Restart: "already started" (Docker restart endpoint returns 304 for already-running containers)
+
+**Note:** HTTP 204 is handled by existing `!response.message && !response.error` success check.
+  </action>
+  <verify>
+1. Read n8n-actions.json and verify all three Format nodes have statusCode checks
+2. Verify 304 returns success: true with "already {state}" message
+3. Verify 404 returns success: false with "not found" message
+4. Verify >= 500 returns success: false with "server error" message
+  </verify>
+  <done>All three Format Result nodes check response.statusCode for 304, 404, and 500+ before falling through to existing message-based checks. Status code checks use appropriate per-action messaging.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Deploy updated sub-workflow via n8n API</name>
+  <files>n8n-actions.json</files>
+  <action>
+Deploy updated n8n-actions.json to n8n instance:
+
+```bash
+source .env.n8n-api
+curl -X PUT "$N8N_HOST/api/v1/workflows/fYSZS5PkH0VSEaT5" \
+  -H "X-N8N-API-KEY: $N8N_API_KEY" \
+  -H "Content-Type: application/json" \
+  --data @n8n-actions.json
+```
+
+Verify deployment success (returns 200 with workflow object).
+  </action>
+  <verify>
+curl returns 200 status code and JSON response containing workflow ID fYSZS5PkH0VSEaT5
+  </verify>
+  <done>Updated n8n-actions.json deployed to n8n instance successfully</done>
+</task>
+
+</tasks>
+
+<verification>
+## Manual Test Cases
+
+After deployment, test using Telegram bot:
+
+1. **Already stopped:** Find a stopped container → send "stop {name}" → expect "✅ {name} is already stopped" (not failure message)
+2. **Already started:** Find a running container → send "start {name}" → expect "✅ {name} is already started"
+3. **Not found:** Send "stop nonexistent123" → expect "❌ Container nonexistent123 not found"
+
+All three should show success/error indicators instead of generic failure messages.
+</verification>
+
+<success_criteria>
+- Format Stop/Start/Restart Result nodes check response.statusCode before message patterns
+- HTTP 304 treated as success with "already {stopped|started}" message
+- HTTP 404 returns clear "not found" error
+- HTTP 500+ returns clear "server error" message
+- Updated sub-workflow deployed via n8n API
+- UAT gap "Stopping an already-stopped container returns helpful message" is closed
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/10.1-aggressive-workflow-modularization/10.1-08-SUMMARY.md`
+</output>