luckberg/unraid-docker-manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(10.1): create gap closure plans (06-07)

Browse Source
This commit is contained in:
Lucas Berger
2026-02-08 08:13:14 -05:00
parent 1337f89114
commit c437aa534f
3 changed files with 370 additions and 155 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.planning/ROADMAP.md
+5 -6
View File
@@ -51,7 +51,7 @@ Plans:
**Requirements:** MOD-03 (new)
**Plans:** 6 plans
**Plans:** 7 plans
Plans:
- [x] 10.1-01-PLAN.md — Rename sub-workflows, analyze domain boundaries, get user approval
@@ -59,18 +59,17 @@ Plans:
- [x] 10.1-03-PLAN.md — Extract Container Status sub-workflow (~10-15 nodes)
- [x] 10.1-04-PLAN.md — Extract Confirmation sub-workflow (~15-20 nodes)
- [x] 10.1-05-PLAN.md — Integration verification and UAT
- [ ] 10.1-06-PLAN.md — Gap closure: document contracts, analyze Code nodes, decide on remaining gaps
- [ ] 10.1-06-PLAN.md — Gap closure: Extract Matching/Disambiguation sub-workflow
- [ ] 10.1-07-PLAN.md — Gap closure: Code node classification + contract documentation
**Success Criteria:**
1. Main workflow contains only: trigger, auth, keyword routing, sub-workflow dispatch
2. UX/Keyboard sub-workflow handles all batch selection UI and pagination
3. Container Status sub-workflow handles list and status display
4. Confirmation sub-workflow handles all confirmation dialogs
5. Main workflow reduced to ~50-80 nodes (from 192) — *Revised: 115-125 realistic target*
5. Main workflow reduced to ~50-80 nodes (from 192)
6. All sub-workflows have clean input/output contracts
**Note:** Original 50-80 target was unrealistic (58 Telegram response nodes locked to main). Revised target 115-125. Current: 168 nodes after 3 domain extractions. Gap closure plan addresses remaining verification gaps.
---
### Phase 10.2: Better Logging and Log Management (INSERTED)
@@ -172,4 +171,4 @@ Plans:
**v1.2 Coverage:** 12+ requirements mapped across 7 phases
---
*Updated: 2026-02-05 — Phase 10.1 gap closure plan added (10.1-06)*
*Updated: 2026-02-08 — Phase 10.1 gap closure plans added (plans 06-07)*
.planning/phases/10.1-aggressive-workflow-modularization/10.1-06-PLAN.md
+164 -149
View File
@@ -4,31 +4,42 @@ plan: 06
type: execute
wave: 1
depends_on: []
files_modified:
- .planning/phases/10.1-aggressive-workflow-modularization/10.1-SUB-WORKFLOW-CONTRACTS.md
- .planning/phases/10.1-aggressive-workflow-modularization/10.1-CODE-NODE-ANALYSIS.md
autonomous: false
files_modified: [n8n-matching.json, n8n-workflow.json]
autonomous: true
gap_closure: true
must_haves:
truths:
- "All sub-workflow input/output contracts are documented"
- "Code nodes are categorized as orchestration vs domain logic"
- "User has made decision on node count gap closure approach"
- "Matching/disambiguation logic is encapsulated in a dedicated sub-workflow"
- "Container name matching works for text commands (action, update)"
- "Batch container matching works for batch operations"
- "Disambiguation, suggestion, and not-found flows work correctly"
- "Main workflow node count is reduced after extraction"
artifacts:
- path: ".planning/phases/10.1-aggressive-workflow-modularization/10.1-SUB-WORKFLOW-CONTRACTS.md"
provides: "Input/output contract documentation for all 6 sub-workflows"
- path: ".planning/phases/10.1-aggressive-workflow-modularization/10.1-CODE-NODE-ANALYSIS.md"
provides: "Classification of 62 Code nodes by purpose"
key_links: []
- path: "n8n-matching.json"
provides: "Container matching and disambiguation sub-workflow"
contains: "Execute Workflow Trigger"
- path: "n8n-workflow.json"
provides: "Main workflow with matching extracted"
- path: "n8n-workflow.json.backup-matching"
provides: "Pre-extraction backup"
key_links:
- from: "n8n-workflow.json"
to: "n8n-matching.json"
via: "Execute Workflow nodes"
pattern: "Execute.*Match"
- from: "n8n-matching.json"
to: "main workflow routing"
via: "action return field"
pattern: "action"
---
<objective>
Close verification gaps from Phase 10.1 by documenting sub-workflow contracts, analyzing Code nodes, and obtaining user decision on node count gap.
Extract the Matching/Disambiguation domain (12 logic nodes) from the main workflow into a new n8n-matching.json sub-workflow. This is the 4th extractable domain identified in the 10.1-01 domain analysis that was deferred during initial extraction.
Purpose: VERIFICATION.md identified 3 gaps - this plan addresses Gap 2 (Code node analysis incomplete), Gap 3 (contract consistency uncertain), and presents options for Gap 1 (node count target not met).
Purpose: Close Gap 1 from VERIFICATION.md (node count target). While the 115-125 target is structurally unachievable (86 nodes are locked to main), extracting matching completes the extraction of all viable domains and reduces main workflow complexity.
Output: Documentation artifacts and user decision on whether to proceed with additional extraction or accept current state.
Output: n8n-matching.json sub-workflow + updated n8n-workflow.json
</objective>
<execution_context>
@@ -40,175 +51,179 @@ Output: Documentation artifacts and user decision on whether to proceed with add
@.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-02-SUMMARY.md
@.planning/phases/10.1-aggressive-workflow-modularization/10.1-04-SUMMARY.md
@n8n-workflow.json
@n8n-batch-ui.json
@n8n-status.json
@n8n-confirmation.json
@n8n-update.json
@n8n-actions.json
@n8n-logs.json
</context>
<tasks>
<task type="auto">
<name>Task 1: Document Sub-workflow Input/Output Contracts</name>
<files>.planning/phases/10.1-aggressive-workflow-modularization/10.1-SUB-WORKFLOW-CONTRACTS.md</files>
<name>Task 1: Create n8n-matching.json sub-workflow</name>
<files>n8n-matching.json</files>
<action>
Create comprehensive documentation of input/output contracts for all 6 sub-workflows by inspecting:
Create a new n8n-matching.json sub-workflow that encapsulates container matching and disambiguation logic. Follow the exact same patterns used in n8n-confirmation.json, n8n-batch-ui.json, and n8n-status.json (action-based return pattern).
1. Each sub-workflow's Execute Workflow Trigger node (input fields)
2. Each sub-workflow's terminal nodes (output structure)
3. Main workflow's Prepare* nodes that build inputs for Execute Workflow calls
4. Main workflow's Route* nodes that handle sub-workflow outputs
**Sub-workflow structure:**
Document for each sub-workflow:
- **Input contract:** All expected fields, types, and which are required vs optional
- **Output contract:** The `action` field values and associated data fields
- **Caller nodes:** Which Execute Workflow nodes in main workflow call this sub-workflow
- **Prepare nodes:** Which Code nodes prepare the input data
1. **Execute Workflow Trigger** — Entry point receiving inputs
2. **Input contract:**
- `action`: one of "match_action", "match_update", "match_batch"
- `containerList`: JSON array of containers from Docker API
- `searchTerm`: container name to match (for action/update)
- `selectedContainers`: CSV of selected containers (for batch)
- `chatId`, `messageId`: for context passing
Sub-workflows to document:
1. n8n-update.json (Container Update) - ID: 7AvTzLtKXM2hZTio92_mC
2. n8n-actions.json (Container Actions) - ID: fYSZS5PkH0VSEaT5
3. n8n-logs.json (Container Logs) - ID: oE7aO2GhbksXDEIw
4. n8n-batch-ui.json (Batch UI) - ID: ZJhnGzJT26UUmW45
5. n8n-status.json (Container Status) - ID: lqpg2CqesnKE2RJQ
6. n8n-confirmation.json (Confirmation Dialogs) - ID: fZ1hu8eiovkCk08G
3. **Route Action** (Switch node) — Routes by action field to appropriate matching logic
Format as markdown with tables showing field name, type, required, and description.
4. **Logic nodes to include (extract from main workflow):**
- `Match Container` (code) — Fuzzy matches container name against list for action commands
- `Match Update Container` (code) — Fuzzy matches for update commands
- `Match Batch Containers` (code) — Matches batch-selected containers against Docker list
- `Check Match Count` (switch) — Routes by match count (0, 1, 2+)
- `Check Update Match Count` (switch) — Routes by update match count
- `Find Closest Match` (code) — Finds closest match for suggestions
- `Check Suggestion` (if) — Checks if suggestion is close enough
- `Build Suggestion Keyboard` (code) — Builds inline keyboard for suggestion
- `Build Disambiguation Message` (code) — Builds disambiguation text
- `Build Not Found Message` (code) — Builds not-found message text
- `Needs Disambiguation` (if) — Checks if batch has ambiguous matches
- `Has Not Found` (if) — Checks if batch has not-found containers
5. **Return pattern (action-based, like other sub-workflows):**
Each exit path returns a JSON object with an `action` field that the main workflow routes on:
- `action: "matched"` + `containerId`, `containerName` — Single match found
- `action: "matched_update"` + `containerId`, `containerName` — Single update match found
- `action: "multiple_update"` + `matches` — Multiple update matches (for Handle Update Multiple)
- `action: "suggestion"` + `keyboard`, `text` — Close match suggestion to display
- `action: "no_match"` — No match and no suggestion
- `action: "disambiguation"` + `text` — Disambiguation message to display
- `action: "not_found"` + `text`, `keyboard` — Batch not-found message
- `action: "batch_matched"` + `matchedContainers` — Batch containers matched successfully
- `action: "error"` + `errorMessage` — Docker list error
- `action: "no_match_update"` — No update match found
**CRITICAL:** Copy the actual JavaScript code from each Code node in n8n-workflow.json. Do NOT rewrite or approximate the logic. Read the `jsCode` property from each node's parameters and transplant it exactly, adjusting only input references (change `$json` or `$('Node Name').item.json` references to use the sub-workflow's input data).
**Follow existing sub-workflow patterns:**
- Use typeVersion that matches existing sub-workflows (check n8n-confirmation.json for reference)
- Include proper metadata (name: "Container Matching", tags, etc.)
- Position nodes in a readable layout (increment x/y coordinates)
**Do NOT include Telegram response nodes** — per locked decision, Send Disambiguation, Send Suggestion, Send No Match, Send Not Found Message, Send Update No Match, and Delete Suggestion Message stay in main workflow.
</action>
<verify>File exists at .planning/phases/10.1-aggressive-workflow-modularization/10.1-SUB-WORKFLOW-CONTRACTS.md with documented contracts for all 6 sub-workflows</verify>
<done>All 6 sub-workflows have documented input/output contracts with field-level detail</done>
<verify>
Verify with Python script:
1. n8n-matching.json is valid JSON
2. Has Execute Workflow Trigger node
3. Has Switch/Route node for action routing
4. Contains all 12 logic nodes (Match Container, Match Update Container, Match Batch Containers, Check Match Count, Check Update Match Count, Find Closest Match, Check Suggestion, Build Suggestion Keyboard, Build Disambiguation Message, Build Not Found Message, Needs Disambiguation, Has Not Found)
5. All Code nodes have non-empty jsCode
6. No Telegram/HTTP Send nodes in sub-workflow
</verify>
<done>n8n-matching.json exists with 14-16 nodes (12 logic + trigger + router + any merge nodes), valid JSON, all matching logic transplanted from main workflow</done>
</task>
<task type="auto">
<name>Task 2: Analyze and Classify Code Nodes</name>
<files>.planning/phases/10.1-aggressive-workflow-modularization/10.1-CODE-NODE-ANALYSIS.md</files>
<name>Task 2: Update main workflow to call matching sub-workflow</name>
<files>n8n-workflow.json, n8n-workflow.json.backup-matching</files>
<action>
Analyze all 62 Code nodes in the main workflow and classify each as one of:
**Step 1: Create backup**
Copy n8n-workflow.json to n8n-workflow.json.backup-matching before any modifications.
1. **ORCHESTRATION** - Must stay in main workflow
- Prepare* nodes that build sub-workflow inputs
- Route/Handle nodes that process sub-workflow outputs
- Parse* nodes that interpret user input for routing
**Step 2: Remove extracted nodes**
Remove the 12 matching logic nodes from n8n-workflow.json:
- Match Container, Match Update Container, Match Batch Containers
- Check Match Count, Check Update Match Count
- Find Closest Match, Check Suggestion
- Build Suggestion Keyboard, Build Disambiguation Message, Build Not Found Message
- Needs Disambiguation, Has Not Found
2. **PRESENTATION** - Locked to main per Telegram decision
- Build* nodes that construct Telegram messages/keyboards
- Format* nodes that prepare display data
**Step 3: Add integration nodes**
3. **DOMAIN_LOGIC** - Potentially extractable
- Match* nodes (container matching logic)
- Find* nodes (search/filter logic)
- Check* nodes with business logic (not routing switches)
The matching domain has 3 distinct entry points. Create integration for each:
4. **HYBRID** - Partially extractable
- Nodes that mix orchestration with domain logic
**Entry 1: Action matching (text command like "stop nginx")**
- Add `Prepare Action Match Input` (Code node) — Takes output from `Docker List for Action`, prepares: action="match_action", containerList, searchTerm from parsed command, chatId, messageId
- Add `Execute Action Match` (Execute Workflow node) — Calls n8n-matching.json with TODO_DEPLOY_MATCHING_WORKFLOW placeholder. Use typeVersion 1.2 with `workflowId: { "__rl": true, "mode": "list", "value": "TODO_DEPLOY_MATCHING_WORKFLOW" }`
- Add `Route Action Match Result` (Switch node) — Routes by returned action field:
- "matched" -> `Prepare Text Action Input` (existing)
- "suggestion" -> `Send Suggestion` (existing Telegram node)
- "no_match" -> `Send No Match` (existing Telegram node)
- "disambiguation" -> `Send Disambiguation` (existing HTTP node)
- "error" -> `Send Docker Error` (existing)
Create table with columns:
- Node name
- Category (ORCHESTRATION/PRESENTATION/DOMAIN_LOGIC/HYBRID)
- Rationale (why this classification)
- Extraction potential (YES/NO/PARTIAL with explanation)
**Entry 2: Update matching (text command like "update nginx")**
- Add `Prepare Update Match Input` (Code node) — Takes output from `Docker List for Update`, prepares: action="match_update", containerList, searchTerm, chatId, messageId
- Add `Execute Update Match` (Execute Workflow node) — Calls n8n-matching.json
- Add `Route Update Match Result` (Switch node) — Routes by returned action:
- "matched_update" -> `Prepare Text Update Input` (existing)
- "multiple_update" -> `Handle Update Multiple` (existing)
- "no_match_update" -> `Send Update No Match` (existing)
- "error" -> `Send Update Error` (existing)
Summarize:
- Count by category
- Total extractable nodes (DOMAIN_LOGIC + partial HYBRID)
- Estimated node reduction if extracted
**Entry 3: Batch matching**
- Add `Prepare Batch Match Input` (Code node) — Takes output from `Get Containers for Batch`, prepares: action="match_batch", containerList, selectedContainers, chatId, messageId
- Add `Execute Batch Match` (Execute Workflow node) — Calls n8n-matching.json
- Add `Route Batch Match Result` (Switch node) — Routes by returned action:
- "batch_matched" -> `Build Batch Keyboard` (existing) or equivalent downstream
- "disambiguation" -> `Send Disambiguation` (existing)
- "not_found" -> `Send Not Found Message` (existing) then -> `Route Batch Action` (existing)
**Step 4: Rewire connections**
- `Docker List for Action` -> `Prepare Action Match Input` -> `Execute Action Match` -> `Route Action Match Result` -> (existing targets)
- `Docker List for Update` -> `Prepare Update Match Input` -> `Execute Update Match` -> `Route Update Match Result` -> (existing targets)
- `Get Containers for Batch` -> `Prepare Batch Match Input` -> `Execute Batch Match` -> `Route Batch Match Result` -> (existing targets)
- Remove old connections from Docker List nodes to removed matching nodes
- Preserve all connections from Telegram response nodes (Send Disambiguation, etc.) to their downstream targets
**Step 5: Update Answer Action Query connection**
Currently `Answer Action Query` -> `Delete Suggestion Message`. This connection stays as-is since Delete Suggestion Message remains in main workflow.
**Node count verification:**
- Removed: 12 nodes
- Added: 9 nodes (3 Prepare + 3 Execute + 3 Route)
- Net reduction: 3 nodes (168 -> ~165)
- 6 Telegram response nodes remain in main (as required by locked decision)
**IMPORTANT:** Maintain exact connection format used in existing workflow. Check existing Execute Workflow nodes (e.g., Execute Confirmation, Execute Batch UI) for correct connection structure, parameter format, and typeVersion.
</action>
<verify>File exists at .planning/phases/10.1-aggressive-workflow-modularization/10.1-CODE-NODE-ANALYSIS.md with all 62 Code nodes classified</verify>
<done>All 62 Code nodes classified with extraction potential assessment</done>
</task>
<task type="checkpoint:decision" gate="blocking">
<decision>How to address Gap 1 (node count: 168 current vs 115-125 target)?</decision>
<context>
Phase 10.1 reduced main workflow from 192 to 168 nodes (12.5% reduction) through extraction of:
- Batch UI (16 nodes in sub-workflow)
- Container Status (11 nodes in sub-workflow)
- Confirmation Dialogs (16 nodes in sub-workflow)
The 115-125 target assumed extracting 4 domains, but Matching/Disambiguation was deferred.
Analysis shows:
- 18 Matching/Disambiguation nodes exist in main workflow
- Extracting could reduce by ~10-15 nodes (net after integration overhead)
- Would bring main to ~153-158 nodes (still 30+ nodes above 115-125 target)
- Reaching 115-125 would require reconsidering the locked decision about Telegram responses staying in main workflow
The verification also notes:
- UAT passed with all functionality working
- 13/16 must-haves verified
- MOD-01 and MOD-02 requirements satisfied
</context>
<options>
<option id="option-a">
<name>Accept Current State</name>
<pros>
- Phase functionally complete (UAT passed)
- 12.5% reduction achieved (192 -> 168)
- 6 sub-workflows deployed and working
- Requirements MOD-01/MOD-02 satisfied
- Can move on to Phase 10.2/11
</pros>
<cons>
- Gap 1 remains unresolved
- Original 115-125 target not met
- Matching logic remains in main workflow
</cons>
</option>
<option id="option-b">
<name>Extract Matching Domain</name>
<pros>
- Addresses Matching extraction that was deferred
- ~10-15 node reduction (168 -> ~153-158)
- Cleaner separation of concerns
- Matching logic reusable if needed elsewhere
</pros>
<cons>
- Still won't reach 115-125 target
- Additional integration complexity
- More Execute Workflow nodes needed
- Diminishing returns on effort
</cons>
</option>
<option id="option-c">
<name>Revisit Telegram Decision</name>
<pros>
- Could achieve 115-125 target
- Maximum modularization
- Single response handler pattern
</pros>
<cons>
- Reverses locked architectural decision
- Significant refactoring effort
- Adds complexity to sub-workflow contracts
- Risk of breaking working system
</cons>
</option>
</options>
<resume-signal>Select: option-a (accept), option-b (extract matching), or option-c (revisit telegram)</resume-signal>
<verify>
Verify with Python script:
1. n8n-workflow.json is valid JSON
2. Backup file exists at n8n-workflow.json.backup-matching
3. Node count is 165 or fewer (168 - 12 removed + 9 added = 165)
4. None of the 12 removed nodes exist in main workflow
5. 3 Execute Workflow nodes reference TODO_DEPLOY_MATCHING_WORKFLOW (or actual ID)
6. All 6 Telegram response nodes (Send Disambiguation, Send Suggestion, Send No Match, Send Not Found Message, Send Update No Match, Delete Suggestion Message) still exist
7. No orphan nodes (every node has at least one connection in or out, except trigger)
8. All existing Execute Workflow nodes for other sub-workflows still present (14 original)
</verify>
<done>Main workflow updated with matching sub-workflow calls, 12 logic nodes removed, 9 integration nodes added, 6 Telegram response nodes preserved, backup created, all connections properly wired</done>
</task>
</tasks>
<verification>
- [ ] SUB-WORKFLOW-CONTRACTS.md documents all 6 sub-workflows
- [ ] CODE-NODE-ANALYSIS.md classifies all 62 Code nodes
- [ ] User has selected gap closure approach
- [ ] If option-b selected, plan 10.1-07 will be created for Matching extraction
1. `python3 -c "import json; wf=json.load(open('n8n-matching.json')); print(f'Matching nodes: {len(wf[\"nodes\"])}')"` shows 14-16 nodes
2. `python3 -c "import json; wf=json.load(open('n8n-workflow.json')); print(f'Main nodes: {len(wf[\"nodes\"])}')"` shows ~165 nodes
3. Both files are valid JSON
4. No matching logic nodes remain in main workflow
5. All Telegram response nodes preserved in main workflow
6. Execute Workflow connections properly structured
</verification>
<success_criteria>
1. Gap 3 closed: Sub-workflow contracts documented with field-level detail
2. Gap 2 closed: Code nodes analyzed and classified
3. Gap 1 addressed: User decision recorded on approach
- n8n-matching.json exists with all 12 matching logic nodes transplanted
- Main workflow reduced from 168 to ~165 nodes
- All 3 matching entry paths (action, update, batch) routed through sub-workflow
- 6 Telegram response nodes remain in main workflow per locked decision
- Backup file created before modification
- Both workflow files are valid JSON with no orphan nodes
</success_criteria>
<output>
After completion, create `.planning/phases/10.1-aggressive-workflow-modularization/10.1-06-SUMMARY.md`
If user selects option-b, additional gap closure plan 10.1-07 will be needed for Matching domain extraction.
</output>
.planning/phases/10.1-aggressive-workflow-modularization/10.1-07-PLAN.md
+201
View File
@@ -0,0 +1,201 @@
---
phase: 10.1-aggressive-workflow-modularization
plan: 07
type: execute
wave: 1
depends_on: []
files_modified: [DEPLOY-SUBWORKFLOWS.md]
autonomous: true
gap_closure: true
must_haves:
truths:
- "All 62+ Code nodes in main workflow are classified as orchestration or domain logic"
- "All 7 sub-workflow input/output contracts are formally documented"
- "Node count target is updated with evidence-based rationale"
- "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
</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
@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
</context>
<tasks>
<task type="auto">
<name>Task 1: Classify all Code nodes and document contracts</name>
<files>DEPLOY-SUBWORKFLOWS.md</files>
<action>
Read the existing DEPLOY-SUBWORKFLOWS.md and significantly expand it with two new sections.
**Section 1: Code Node Classification**
Analyze every Code node in n8n-workflow.json (62 nodes currently, may be ~50 after plan 06 extraction). 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 matching domain.
**Section 2: Sub-workflow Input/Output Contracts**
For each of the 6 (or 7 after plan 06) 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 (if plan 06 complete, otherwise note as pending)
**Section 3: Revised Node Count Rationale**
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 "Code Node Classification" section with table covering all Code nodes
2. DEPLOY-SUBWORKFLOWS.md contains "Input/Output Contract" section for each sub-workflow
3. Each sub-workflow contract lists all input fields with types
4. Each sub-workflow contract lists all output actions with fields
5. DEPLOY-SUBWORKFLOWS.md contains "Node Count Analysis" section with revised rationale
6. All Code node categories sum to total Code node count in main workflow
</verify>
<done>All Code nodes classified with evidence, all sub-workflow contracts documented with field-level detail, node count rationale updated with structural analysis proving current count is near-minimal</done>
</task>
</tasks>
<verification>
1. DEPLOY-SUBWORKFLOWS.md exists and contains all three new sections
2. Code node classification covers every Code node in main workflow (verify count matches)
3. Sub-workflow contracts cover all 6-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>