Files

T

Lucas Berger 4eeed1d9e1 docs(10.1-06): complete matching extraction plan

2026-02-08 18:56:44 -05:00

6.4 KiB

Raw Permalink Blame History

phase, plan, subsystem, tags, requires, provides, affects, tech-stack, key-files, key-decisions, patterns-established, duration, completed

phase

plan

subsystem

tags

requires

provides

affects

tech-stack

key-files

key-decisions

patterns-established

duration

completed

10.1-aggressive-workflow-modularization

workflow

n8n

sub-workflow

matching

disambiguation

fuzzy-matching

phase	provides
10.1-01	Domain analysis identifying matching/disambiguation as 4th extractable domain

phase	provides
10.1-04	Main workflow at 168 nodes baseline

n8n-matching.json sub-workflow (23 nodes)

Matching/disambiguation domain extracted from main workflow

All 4 viable domains now extracted

10.1-07

deployment

added

patterns

Action-based sub-workflow return pattern for matching results

Prepare Execution node to transform sub-workflow output to downstream format

created

modified

n8n-matching.json

n8n-workflow.json.backup-matching

n8n-workflow.json

DEPLOY-SUBWORKFLOWS.md

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

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)

16min

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:

Task 1: Create n8n-matching.json - e86941c (feat)
Task 2: Update main workflow - de64d1b (feat)
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

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.
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.
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

6.4 KiB Raw Permalink Blame History