By Monday, November 10, I had documentation that taught thinking instead of prescribing steps. Time to get back to the workflow itself.
Tuesday and Wednesday, November 11-12, I’d discover that coordinator complexity was my bottleneck.
Fresh Eyes
Tuesday morning, I opened the workflow instructions for the first time in a week.
The coordinator’s loop looked like this:
Step 5: Invoke tool worker to check for issues.
Step 6: Read the raw output from the tool worker.
Step 7: Parse the output to extract issue counts.
Step 8: Categorize issues by type.
Step 9: Group issues by file.
Step 10: Sort by priority.
Step 11: Decide which worker to invoke next based on the categorized issues.
Every iteration: parse, categorize, group, sort, decide.
The tool worker’s job was simple. Invoke a skill. Return the raw output. That’s it.
All the cognitive work happened in the coordinator.
The Cognitive Load Problem
I traced through a typical workflow run.
Loop 1: Invoke tool worker. Parse raw output. Categorize 47 issues. Group by 12 files. Sort. Decide what to fix. Invoke fixing workers.
Loop 2: Invoke tool worker again. Parse raw output again. Categorize 23 remaining issues. Group by 8 files. Sort. Decide what to fix. Invoke fixing workers.
Loop 3: Invoke tool worker again. Parse, categorize, group, sort. 5 issues left.
Every single loop, the coordinator did the same parsing and categorization work. Reading raw output. Extracting counts. Categorizing issue types. Grouping by file.
The worker knew the output format. The worker invoked the skill. But the worker just handed back raw text and made the coordinator figure out what it meant.
This was backwards.
The Fix
Wednesday, I rewrote the tool workers.
Old approach:
Worker invokes skill. Returns raw output. Coordinator parses it every loop.
New approach:
Worker invokes skill. Parses output. Categorizes issues. Groups by file. Returns clean structured data.
The coordinator’s new loop:
Step 5: Invoke tool worker to check for issues.
Step 6: Read the structured data from the tool worker.
Step 7: If issues exist, invoke appropriate fixing workers.
Step 8: Loop back to Step 5.
From 11 steps to 4 steps. No parsing. No categorization. No grouping. Just orchestration.
The Merge Worker
I had two different tools checking for issues. Both now returned structured data. But the coordinator still had to merge their outputs.
That’s still cognitive load.
So I added a merge worker. Its job: take outputs from multiple tool workers, consolidate them, remove duplicates, sort by file path, return one clean list.
Now the coordinator receives one merged list. Already deduplicated. Already sorted. Ready to use.
The coordinator just decides: issues exist? Fix them. No issues? Done.
Why This Matters
Coordinator instructions are the bottleneck. When coordinators have to parse and categorize and group, they’re doing work that distracts from orchestration.
Workers know their output format. They invoked the skill. They understand what the raw output means. They should transform it into clean structured data before handing it back.
Parse at the source. Format where you have context. Return clean data to the coordinator.
This keeps coordinator instructions simple. When instructions are simple, they’re easier to understand, easier to debug, easier to modify.
The Pattern
Tool workers should follow this pattern:
1. Invoke the skill that uses the tool
2. Parse the raw output
3. Transform into structured format
4. Return clean data
Coordinators should follow this pattern:
1. Invoke workers
2. Read structured data
3. Make orchestration decisions
4. Loop until exit condition
Workers handle transformation. Coordinators handle orchestration. Clean separation.
Testing the Pattern
I ran the workflow again with the new structure.
Same functionality. Same results. But the coordinator instructions were dramatically simpler. No parsing logic. No categorization rules. No grouping algorithms.
Just: invoke workers, check for issues, decide what to do next, loop until clean.
The cognitive load moved from the coordinator (where it ran every loop) to the workers (where it runs once per invocation).
Wednesday Night
Wednesday, November 12, around 1 AM, I merged the changes.
Two days. Complete restructuring. Coordinator complexity cut by more than half.
Workers now format their own output. Coordinators receive clean structured data. Parsing happens at the source, not in every loop iteration.
The lesson: reduce coordinator cognitive load. Move parsing and formatting into workers who know the output format. Keep coordinator instructions focused on orchestration.
I had established patterns: flat coordination, workers handling their own responsibilities, coordinators focused on orchestration. Three weeks of discovery, refinement, and cleanup. The first workflow was finally solid.
The real test would come the next day: could these patterns work for a completely different workflow?