---
phase: 10.1-aggressive-workflow-modularization
plan: 06
type: execute
wave: 1
depends_on: []
files_modified: [n8n-matching.json, n8n-workflow.json]
autonomous: true
gap_closure: true
must_haves:
truths:
- "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: "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"
---
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: 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: n8n-matching.json sub-workflow + updated n8n-workflow.json
@/home/luc/.claude/get-shit-done/workflows/execute-plan.md
@/home/luc/.claude/get-shit-done/templates/summary.md
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.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-actions.json
Task 1: Create n8n-matching.json sub-workflow
n8n-matching.json
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).
**Sub-workflow structure:**
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
3. **Route Action** (Switch node) — Routes by action field to appropriate matching logic
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.
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
n8n-matching.json exists with 14-16 nodes (12 logic + trigger + router + any merge nodes), valid JSON, all matching logic transplanted from main workflow
Task 2: Update main workflow to call matching sub-workflow
n8n-workflow.json, n8n-workflow.json.backup-matching
**Step 1: Create backup**
Copy n8n-workflow.json to n8n-workflow.json.backup-matching before any modifications.
**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
**Step 3: Add integration nodes**
The matching domain has 3 distinct entry points. Create integration for each:
**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)
**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)
**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.
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)
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
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
- 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