unraid-docker-manager/.planning/phases/10.1-aggressive-workflow-modularization/10.1-07-PLAN.md

---
phase: 10.1-aggressive-workflow-modularization
plan: 07
type: execute
wave: 2
depends_on: ["10.1-06"]
files_modified: [DEPLOY-SUBWORKFLOWS.md]
autonomous: true
gap_closure: true

must_haves:
  truths:
    - "All Code nodes in main workflow are classified as orchestration or domain logic with evidence"
    - "All 7 sub-workflow input/output contracts are formally documented"
    - "Node count target is updated with evidence-based rationale showing current count is near-minimal"
    - "Each Execute Workflow node's input mapping is verified against sub-workflow expectations"
  artifacts:
    - path: "DEPLOY-SUBWORKFLOWS.md"
      provides: "Sub-workflow architecture documentation with contracts and node analysis"
      contains: "Input/Output Contract"
  key_links:
    - from: "DEPLOY-SUBWORKFLOWS.md"
      to: "n8n-workflow.json"
      via: "documents contracts used by Execute Workflow nodes"
      pattern: "Execute Workflow"
---

<objective>
Close Gaps 2 and 3 from VERIFICATION.md: (1) Classify all Code nodes in main workflow as orchestration vs domain logic, proving which must stay and why. (2) Document input/output contracts for all sub-workflows with verification that Execute Workflow nodes pass correct data.

Purpose: The verification found that 62 Code nodes were unanalyzed (Gap 2) and sub-workflow contracts were undocumented (Gap 3). This plan provides the evidence needed to close both gaps and formally documents the architecture.

Output: Updated DEPLOY-SUBWORKFLOWS.md with Code node classification, I/O contracts, and revised node count rationale

Note: This plan depends on 10.1-06 because it documents the n8n-matching.json sub-workflow contract. If 10.1-06 is not yet complete, document the matching sub-workflow contract as "pending extraction" and fill in after 10.1-06 finishes.
</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-VERIFICATION.md
@.planning/phases/10.1-aggressive-workflow-modularization/10.1-01-domain-analysis.md
@.planning/phases/10.1-aggressive-workflow-modularization/10.1-06-SUMMARY.md
@DEPLOY-SUBWORKFLOWS.md
@n8n-workflow.json
@n8n-batch-ui.json
@n8n-status.json
@n8n-confirmation.json
@n8n-update.json
@n8n-actions.json
@n8n-logs.json
@n8n-matching.json
</context>

<tasks>

<task type="auto">
  <name>Task 1: Classify all Code nodes in main workflow</name>
  <files>DEPLOY-SUBWORKFLOWS.md</files>
  <action>
Read the existing DEPLOY-SUBWORKFLOWS.md and add a new "Code Node Classification" section.

Analyze every Code node in n8n-workflow.json (should be ~50 after plan 06 extraction removes some). For each Code node, read its `jsCode` parameter content and classify it into one of these categories:

| Category | Definition | Should Stay in Main? |
|----------|-----------|---------------------|
| `prepare-input` | Prepares input data for a sub-workflow Execute Workflow call | YES - glue between routing and sub-workflow |
| `route-result` | Processes sub-workflow return data for routing/display | YES - glue between sub-workflow and Telegram response |
| `parse-command` | Parses user text input into structured command data | YES - part of keyword routing infrastructure |
| `build-response` | Builds Telegram response text/keyboards from data | YES - tightly coupled to Telegram response nodes |
| `orchestration` | Batch loop control, state management, result aggregation | YES - main workflow orchestration logic |
| `domain-logic` | Pure domain computation that could theoretically live in sub-workflow | CANDIDATE - but assess extraction overhead |

For each Code node, produce a row in a table:
```
| Node Name | Category | Lines | Stays in Main? | Reason |
```

At the bottom, add a summary:
```
Total Code nodes: NN
  prepare-input: NN (must stay)
  route-result: NN (must stay)
  parse-command: NN (must stay)
  build-response: NN (must stay)
  orchestration: NN (must stay)
  domain-logic: NN (extraction candidates)

Extractable domain logic: NN nodes
Extraction overhead per domain: ~3 nodes (Prepare + Execute + Route)
Net reduction potential: NN nodes
```

This proves whether any further extraction is viable beyond the matching domain.
  </action>
  <verify>
1. DEPLOY-SUBWORKFLOWS.md contains "Code Node Classification" section with table
2. Table row count matches actual Code node count in n8n-workflow.json (verify with: `python3 -c "import json; wf=json.load(open('n8n-workflow.json')); print(sum(1 for n in wf['nodes'] if n['type']=='n8n-nodes-base.code'))"`)
3. All 6 categories are represented in the summary
4. Category counts sum to total Code node count
  </verify>
  <done>Every Code node in main workflow classified with category, line count, and rationale. Summary shows breakdown by category and quantifies remaining extraction potential.</done>
</task>

<task type="auto">
  <name>Task 2: Document sub-workflow contracts and node count analysis</name>
  <files>DEPLOY-SUBWORKFLOWS.md</files>
  <action>
Add two more sections to DEPLOY-SUBWORKFLOWS.md (after the Code Node Classification from Task 1).

**Section: Sub-workflow Input/Output Contracts**

For each of the 7 sub-workflows, document:

1. **Input contract** - Read the Execute Workflow Trigger node and the Prepare *Input Code nodes that feed it. Document every field:
   ```
   ## n8n-update.json (Container Update)

   ### Input Contract
   | Field | Type | Required | Source |
   |-------|------|----------|--------|
   | containerId | string | yes | Docker API container ID |
   | containerName | string | yes | Display name |
   | chatId | number | yes | Telegram chat ID |
   | messageId | number | yes | Telegram message ID |
   | responseMode | string | yes | "text" or "callback" |

   ### Output Contract
   | Action | Fields | Routed To |
   |--------|--------|-----------|
   | (no action field) | result, success | Handle Update Result |
   ```

2. **Output contract** - Read the sub-workflow's exit nodes and document what it returns. Include the `action` field values and associated data fields.

3. **Verification** - For each Execute Workflow node in main workflow, verify that the preceding Prepare *Input node produces all required fields. Document any mismatches.

Sub-workflows to document:
- n8n-update.json (Container Update) -- called by 3 Execute nodes
- n8n-actions.json (Container Actions) -- called by 3 Execute nodes
- n8n-logs.json (Container Logs) -- called by 2 Execute nodes
- n8n-batch-ui.json (Batch UI) -- called by 1 Execute node
- n8n-status.json (Container Status) -- called by 4 Execute nodes
- n8n-confirmation.json (Confirmation Dialogs) -- called by 1 Execute node
- n8n-matching.json (Container Matching) -- called by 3 Execute nodes (use 10.1-06-SUMMARY.md for reference)

Also verify the total Execute Workflow node count: should be 17 (14 original + 3 from matching extraction).

**Section: Node Count Analysis**

Add a section that explains the final node count with evidence:

```
## Node Count Analysis

### Current State
- Main workflow: NNN nodes (after matching extraction)
- 7 sub-workflows: total NNN nodes

### Why 115-125 Target Is Not Achievable
Based on Code node classification:
- NN nodes are locked infrastructure (trigger, auth, routing, switches)
- NN nodes are Telegram responses (locked per design decision)
- NN nodes are Execute Workflow dispatch
- NN nodes are Prepare Input (sub-workflow glue)
- NN nodes are Parse/Build/Handle (orchestration, too small to extract)
- NN nodes are domain logic candidates
  - Of these, NN have been extracted (matching domain)
  - Remaining NN nodes: extraction overhead exceeds reduction benefit

### Revised Realistic Baseline
Minimum viable main workflow: NN nodes (all categories that must stay)
Current: NNN nodes
Gap: NN nodes of domain logic where extraction overhead (~3 nodes per domain) makes extraction net-negative or marginal
```

**Formatting:**
- Use the existing DEPLOY-SUBWORKFLOWS.md structure and add new sections
- Keep the existing deployment instructions intact
- Add the new sections after the existing content
  </action>
  <verify>
1. DEPLOY-SUBWORKFLOWS.md contains "Input/Output Contract" section for each of the 7 sub-workflows
2. Each sub-workflow contract lists all input fields with types
3. Each sub-workflow contract lists all output actions with fields
4. DEPLOY-SUBWORKFLOWS.md contains "Node Count Analysis" section with revised rationale
5. Execute Workflow node count documented (should be 17 total)
6. Spot-check: For n8n-status.json, verify the input contract fields match what `Prepare Status Input` Code nodes actually produce (read the jsCode)
  </verify>
  <done>All 7 sub-workflow contracts documented with field-level input/output detail. Execute Workflow node mappings verified. Node count analysis provides structural evidence that current count is near-minimal.</done>
</task>

</tasks>

<verification>
1. DEPLOY-SUBWORKFLOWS.md exists and contains all three new sections (Code Classification, Contracts, Node Count)
2. Code node classification covers every Code node in main workflow (verify count matches)
3. Sub-workflow contracts cover all 7 sub-workflows
4. Each contract has input fields table and output actions table
5. Node count analysis shows evidence-based rationale
6. No factual errors in classification (spot-check 5 random Code nodes)
</verification>

<success_criteria>
- Every Code node in main workflow is classified with category and rationale
- Every sub-workflow has documented input contract (all fields, types, required flag)
- Every sub-workflow has documented output contract (all action values, return fields)
- Node count rationale provides clear evidence that further extraction yields diminishing returns
- All three verification gaps (node count, Code analysis, contract consistency) have documented closure evidence
</success_criteria>

<output>
After completion, create `.planning/phases/10.1-aggressive-workflow-modularization/10.1-07-SUMMARY.md`
</output>