docs(10.1-06): complete matching extraction plan
This commit is contained in:
Lucas Berger
@@ -59,7 +59,7 @@ 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: Extract Matching/Disambiguation sub-workflow
|
||||
- [x] 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:**
|
||||
|
||||
+22
-9
@@ -4,9 +4,9 @@
|
||||
|
||||
- **Milestone:** v1.2 — Modularization & Polish
|
||||
- **Phase:** 10.1 of 13 (Aggressive Workflow Modularization)
|
||||
- **Plan:** 5 of 5 complete
|
||||
- **Status:** Complete
|
||||
- **Last activity:** 2026-02-05 — Completed 10.1-05 (Integration Verification)
|
||||
- **Plan:** 6 of 7 complete (plan 07 remaining: documentation)
|
||||
- **Status:** Gap closure in progress
|
||||
- **Last activity:** 2026-02-08 — Completed 10.1-06 matching extraction + deployment
|
||||
|
||||
## Progress
|
||||
|
||||
@@ -17,7 +17,7 @@ v1.1: [██████████] 100% SHIPPED
|
||||
v1.2: [███████░░░] 65%
|
||||
|
||||
Phase 10: Workflow Modularization [██████████] 100% COMPLETE (+ 10-07 UAT fixes)
|
||||
Phase 10.1: Aggressive Modularization [██████████] 100% COMPLETE (5/5 plans)
|
||||
Phase 10.1: Aggressive Modularization [████████░░] 86% Gap Closure (6/7 plans)
|
||||
Phase 10.2: Better Logging & Log Management [ ] Pending (INSERTED)
|
||||
Phase 11: Update All & Callback Limits [ ] Pending
|
||||
Phase 12: Polish & Audit [ ] Pending
|
||||
@@ -101,6 +101,9 @@ Phase 13: Documentation Overhaul [ ] Pending
|
||||
| 10.1-03 | Minimal net node reduction due to integration overhead | Removed 10 nodes but added 9 integration nodes; value is complexity reduction |
|
||||
| 10.1-04 | Return confirm_update action to main workflow | Update flow tightly integrated with existing update sub-workflow |
|
||||
| 10.1-04 | Call n8n-actions.json for stop execution | Reuse existing action execution instead of duplicating Docker API calls |
|
||||
| 10.1-06 | Downstream nodes reference original parse nodes for action type | Sub-workflow doesn't carry user's requested action (stop/start) through return data |
|
||||
| 10.1-06 | Text-mode status needs keyboard strip + messageId routing | Pre-existing bug exposed by testing; text commands have no message to edit |
|
||||
| 10.1-06 | Batch text needs Prepare Batch Execution transform | Sub-workflow returns matchedContainers/batch_matched, downstream expects allMatched/stop |
|
||||
|
||||
## Phase 10.1 Progress
|
||||
|
||||
@@ -111,33 +114,43 @@ Phase 13: Documentation Overhaul [ ] Pending
|
||||
| 10.1-03 | Container Status Sub-workflow (Wave 2) | Complete |
|
||||
| 10.1-04 | Confirmation Sub-workflow (Wave 3) | Complete |
|
||||
| 10.1-05 | Integration Verification | Complete |
|
||||
| 10.1-06 | Matching Sub-workflow Extraction | Complete |
|
||||
|
||||
**Node count progress:**
|
||||
- Start: 192 nodes
|
||||
- After 10.1-02: 179 nodes (-13)
|
||||
- After 10.1-03: 178 nodes (-1)
|
||||
- After 10.1-04: 168 nodes (-10)
|
||||
- After 10.1-06: 168 nodes (net 0: -12 extracted, +9 integration, +3 fix nodes)
|
||||
- Target: 115-125 nodes
|
||||
|
||||
**Extraction complete:**
|
||||
- Batch UI: -13 nodes (16 nodes in sub-workflow)
|
||||
- Container Status: -1 net (11 nodes in sub-workflow, complexity reduction)
|
||||
- Confirmation: -10 nodes (16 nodes in sub-workflow)
|
||||
- Matching: net 0 (23 nodes in sub-workflow, complexity reduction)
|
||||
- Total reduction: 24 nodes (192 -> 168)
|
||||
|
||||
## Phase 10.1 Complete
|
||||
## Phase 10.1 Sub-workflows
|
||||
|
||||
All 6 sub-workflows deployed and operational:
|
||||
All 7 sub-workflows deployed and operational:
|
||||
- n8n-update.json — `7AvTzLtKXM2hZTio92_mC`
|
||||
- n8n-actions.json — `fYSZS5PkH0VSEaT5`
|
||||
- n8n-logs.json — `oE7aO2GhbksXDEIw`
|
||||
- n8n-batch-ui.json — Deployed
|
||||
- n8n-batch-ui.json — `ZJhnGzJT26UUmW45`
|
||||
- n8n-status.json — `lqpg2CqesnKE2RJQ`
|
||||
- n8n-confirmation.json — Deployed
|
||||
- n8n-confirmation.json — `fZ1hu8eiovkCk08G`
|
||||
- n8n-matching.json — `kL4BoI8ITSP9Oxek`
|
||||
|
||||
## Next Step
|
||||
|
||||
Plan Phase 10.2 (Better Logging & Log Management) or Phase 11 (Update All & Callback Limits).
|
||||
Execute plan 10.1-07 (Code node classification + contract documentation).
|
||||
|
||||
## Session Continuity
|
||||
|
||||
Last session: 2026-02-08
|
||||
Stopped at: Completed 10.1-06, executing 10.1-07 next
|
||||
Resume file: None
|
||||
|
||||
---
|
||||
*Auto-maintained by GSD workflow*
|
||||
|
||||
@@ -0,0 +1,140 @@
|
||||
---
|
||||
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*
|
||||
@@ -6,7 +6,7 @@ Phase 10.1 (Aggressive Workflow Modularization) reduced the main workflow from 1
|
||||
|
||||
**Final State:**
|
||||
- Main workflow: 168 nodes (reduced by 24 nodes, -12.5%)
|
||||
- Total sub-workflows: 6 (3 pre-existing + 3 new)
|
||||
- Total sub-workflows: 7 (3 pre-existing + 4 new)
|
||||
|
||||
## Sub-workflows
|
||||
|
||||
@@ -17,7 +17,8 @@ Phase 10.1 (Aggressive Workflow Modularization) reduced the main workflow from 1
|
||||
| n8n-logs.json | Container log retrieval | 9 | Deployed (ID: `oE7aO2GhbksXDEIw`) |
|
||||
| n8n-batch-ui.json | Batch selection UI | 16 | Deployed |
|
||||
| n8n-status.json | Container list/status | 11 | Deployed (ID: `lqpg2CqesnKE2RJQ`) |
|
||||
| n8n-confirmation.json | Confirmation dialogs | 16 | Deployed |
|
||||
| n8n-confirmation.json | Confirmation dialogs | 16 | Deployed (ID: `fZ1hu8eiovkCk08G`) |
|
||||
| n8n-matching.json | Container matching/disambiguation | 23 | Deployed (ID: `kL4BoI8ITSP9Oxek`) |
|
||||
|
||||
## Deployment Status
|
||||
|
||||
@@ -45,7 +46,10 @@ To redeploy after changes:
|
||||
| Execute Select Status | n8n-status.json | `lqpg2CqesnKE2RJQ` |
|
||||
| Execute Paginate Status | n8n-status.json | `lqpg2CqesnKE2RJQ` |
|
||||
| Execute Batch Cancel Status | n8n-status.json | `lqpg2CqesnKE2RJQ` |
|
||||
| Execute Confirmation | n8n-confirmation.json | Deployed |
|
||||
| Execute Confirmation | n8n-confirmation.json | `fZ1hu8eiovkCk08G` |
|
||||
| Execute Action Match | n8n-matching.json | `kL4BoI8ITSP9Oxek` |
|
||||
| Execute Update Match | n8n-matching.json | `kL4BoI8ITSP9Oxek` |
|
||||
| Execute Batch Match | n8n-matching.json | `kL4BoI8ITSP9Oxek` |
|
||||
|
||||
## Rollback
|
||||
|
||||
|
||||
Reference in New Issue
Block a user