---
phase: 10.1-aggressive-workflow-modularization
plan: 06
subsystem: workflow
tags: [n8n, sub-workflow, matching, disambiguation, fuzzy-matching]

# Dependency graph
requires:
  - phase: 10.1-01
    provides: Domain analysis identifying matching/disambiguation as 4th extractable domain
  - phase: 10.1-04
    provides: Main workflow at 168 nodes baseline
provides:
  - n8n-matching.json sub-workflow (23 nodes)
  - Matching/disambiguation domain extracted from main workflow
  - All 4 viable domains now extracted
affects: [10.1-07, deployment]

# Tech tracking
tech-stack:
  added: []
  patterns:
    - "Action-based sub-workflow return pattern for matching results"
    - "Prepare Execution node to transform sub-workflow output to downstream format"

key-files:
  created:
    - n8n-matching.json
    - n8n-workflow.json.backup-matching
  modified:
    - n8n-workflow.json
    - DEPLOY-SUBWORKFLOWS.md

key-decisions:
  - "Matching sub-workflow returns action field but not the user's requested action (stop/start/etc) — downstream nodes read action from Parse Action Command or Detect Batch Command directly"
  - "Text-mode status needs keyboard stripped — added Strip Status Keyboard node"
  - "Batch text commands need data transformation — added Prepare Batch Execution node to map matchedContainers to allMatched"

patterns-established:
  - "When sub-workflow replaces inline logic, downstream nodes may need to reference original data sources (e.g., Parse Action Command) instead of sub-workflow output for fields not passed through"
  - "Text vs callback mode routing via messageId check (Has Status Message ID pattern)"

# Metrics
duration: 16min
completed: 2026-02-08
---

# Phase 10.1 Plan 06: Matching/Disambiguation Sub-workflow Summary

**Extracted matching/disambiguation domain into n8n-matching.json sub-workflow (23 nodes), deployed via API, fixed 3 data flow issues found during runtime verification**

## Performance

- **Duration:** ~16 min
- **Started:** 2026-02-08T13:30:00Z
- **Completed:** 2026-02-08T14:05:26Z
- **Tasks:** 3 (2 auto + 1 checkpoint)
- **Files modified:** 3

## Accomplishments

- Created n8n-matching.json sub-workflow with 23 nodes (12 logic + 1 trigger + 1 router + 9 format-return)
- Three matching paths: action match, update match, batch match
- Deployed via n8n API (ID: `kL4BoI8ITSP9Oxek`)
- All 6 Telegram response nodes preserved in main workflow per locked decision
- Fixed pre-existing text-mode status routing bug (editMessageText with messageId 0)
- Main workflow: 168 nodes (net 0 change due to fix nodes added during verification)

## Task Commits

Each task was committed atomically:

1. **Task 1: Create n8n-matching.json** - `e86941c` (feat)
2. **Task 2: Update main workflow** - `de64d1b` (feat)
3. **Task 3: Deploy and verify** - `fc955e6` (fix: deploy IDs), `22638fd` (fix: action passthrough + status routing), `11365b8` (fix: strip status keyboard), `cccf455` (fix: batch data flow)

## Files Created/Modified

- `n8n-matching.json` - New sub-workflow: fuzzy container matching, disambiguation, suggestion building (23 nodes)
- `n8n-workflow.json` - Main workflow with matching extracted and integration fixes (168 nodes)
- `n8n-workflow.json.backup-matching` - Pre-extraction backup

## Decisions Made

1. **Action passthrough pattern:** The matching sub-workflow doesn't carry the user's requested action (stop/start/restart) through its return data. Downstream nodes reference the original parse node (`Parse Action Command` or `Detect Batch Command`) directly for the action type. This avoids expanding the sub-workflow's input/output contract.

2. **Text-mode status routing:** Added `Has Status Message ID` If node to route `status_direct` results — messageId > 0 goes to `Edit Container List` (callback), messageId == 0 goes to text send via `Strip Status Keyboard` → `Send Container Submenu Direct`.

3. **Batch data transformation:** Added `Prepare Batch Execution` Code node to map `matchedContainers` → `allMatched` and inject the real batch action from `Detect Batch Command`, since downstream nodes expect different field names than the sub-workflow returns.

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 1 - Bug] Action type not passed through matching sub-workflow**
- **Found during:** Task 3 (runtime verification)
- **Issue:** `Prepare Text Action Input` read `data.actionType` which resolved to `"action"` (a routing label) instead of `"stop"`
- **Fix:** Changed to read `$('Parse Action Command').item.json.action` directly
- **Files modified:** n8n-workflow.json
- **Verification:** "stop booklore" correctly executes stop
- **Committed in:** `22638fd`

**2. [Rule 1 - Bug] Text-mode status sent to editMessageText with messageId 0**
- **Found during:** Task 3 (runtime verification)
- **Issue:** Pre-existing bug — "status book" routed to `Edit Container List` (editMessageText) which fails with messageId 0. Also showed inline keyboard buttons for text commands.
- **Fix:** Added `Has Status Message ID` If node and `Strip Status Keyboard` Code node for text-mode routing
- **Files modified:** n8n-workflow.json
- **Verification:** "status book" sends plain text without buttons
- **Committed in:** `22638fd`, `11365b8`

**3. [Rule 1 - Bug] Batch text commands: wrong field names and action**
- **Found during:** Task 3 (runtime verification)
- **Issue:** Downstream nodes expected `allMatched` but sub-workflow returned `matchedContainers`. `Route Batch Action` got `action: "batch_matched"` instead of `"stop"`.
- **Fix:** Added `Prepare Batch Execution` Code node to transform data
- **Files modified:** n8n-workflow.json
- **Verification:** "stop plex dup" correctly executes batch stop
- **Committed in:** `cccf455`

---

**Total deviations:** 3 auto-fixed (3 bugs)
**Impact on plan:** All bugs were data flow mismatches caused by the sub-workflow returning different field names/values than what downstream nodes expected. The matching logic itself worked correctly. Node count is 168 instead of planned 165 due to 3 additional fix nodes (Has Status Message ID, Strip Status Keyboard, Prepare Batch Execution).

## Issues Encountered

None beyond the deviations above — all resolved during runtime verification.

## User Setup Required

None — deployed via n8n API during execution.

## Next Phase Readiness

- Matching sub-workflow created and deployed (7th sub-workflow)
- All 4 viable extraction domains complete
- Ready for plan 10.1-07: Code node classification and contract documentation

---
*Phase: 10.1-aggressive-workflow-modularization*
*Completed: 2026-02-08*