Precision in AI Workflows: Unleashing Fan-Out Prompts and Guarding Against Stack Pollution

Developing complex software, especially in a team setting, often means breaking down large goals into smaller, manageable tasks. When you bring AI into the mix to assist with code generation and task execution, the challenge shifts: how do you ensure the AI understands the context for each sub-task, and more importantly, how do you prevent it from getting "confused" by irrelevant information?

This past session, we tackled these very problems head-on, deploying two critical enhancements to our AI workflow engine: fan-out implementation prompts for group workflows and a wisdom filter to prevent wrong-stack code pattern pollution. The outcome? A much smarter, more precise, and ultimately more useful AI assistant.

The Power of Fan-Out: Deconstructing Group Workflows

Our primary goal was to enhance how our system handles "group workflows." Imagine you have a high-level task that involves creating multiple, similar components or features. Previously, our AI might generate a single, monolithic implementation prompt – a daunting task for any developer to parse and execute.

The solution was to implement a "fan-out" mechanism. This means:

1. Detecting Group Workflows: Our workflow-engine.ts now identifies group-oriented tasks through a group-analysis step.
2. Per-Item Prompt Generation: Instead of one big prompt, the engine intelligently loops over each individual item within the group, generating a separate, highly focused implementation prompt for each. These are delivered as subOutputs, making the AI's guidance granular and actionable.
3. Contextual Prompting: The implementation-prompt-generator.ts was upgraded with buildGroupItemPromptInput() and a dedicated GROUP_ITEM_IMPLEMENTATION_SYSTEM to ensure each sub-prompt receives the precise context it needs.

This transformation means that for a task like "implement 10 new API endpoints," the system now provides 10 distinct, detailed implementation prompts, each tailored to a specific endpoint. This not only makes the AI's output easier to consume but also facilitates parallel development and faster iteration.

The Silent Threat: Wisdom Pollution and Stack Mismatch

As our AI system grows, it accumulates "project wisdom" – a rich repository of code patterns, best practices, and architectural insights drawn from our codebase. While invaluable, this wisdom can become a liability if applied indiscriminately.

We discovered a critical issue: our system was inadvertently "polluting" implementation prompts for a specific target stack (e.g., Python) with irrelevant or even incorrect wisdom from other stacks (e.g., Go). The root cause was traced to our code_patterns table, which contained over 232 Go entries from an older repository. These Go patterns were being loaded unfiltered into our note-enrichment.ts and workflow-engine.ts:loadProjectWisdom() functions, effectively drowning out relevant Python file references and leading the AI astray. Imagine asking for Python code and getting suggestions heavily biased towards Go syntax!

Our Multi-Layered Defense: The Wisdom Filter

To combat this, we implemented a robust, multi-layered wisdom filter:

1. Stack Detection: A brand new stack-detector.ts was introduced, capable of detectRepoStack() from file paths and, crucially, formatCodePatternsWithStack(). This function now labels code patterns with their respective stacks (e.g., [Go], [Python]) and adds an advisory note.
2. Enrichment-Level Filtering: Both note-enrichment.ts and workflow-engine.ts:loadProjectWisdom() now utilize this stack-aware formatting, ensuring that project wisdom is loaded with clear stack labels.
3. Prompt-Level Suppression: The most critical layer lives in implementation-prompt-generator.ts:buildGroupItemPromptInput(). If the target stack for an implementation prompt (e.g., Python) does not match the overall codebase stack (e.g., a project predominantly in Go, or vice versa), the system takes drastic action:
   • It strips out irrelevant context like claudeMd and fileTree.
   • It adds a prominent WARNING to the prompt.
   • It keeps only truncated, highly relevant projectWisdom to minimize cross-contamination.

This ensures that the AI receives only the most pertinent information, drastically reducing the chances of generating code in the wrong language or style.

The Proof is in the Prompts: Verification Results

The impact of these changes was immediately apparent in our verification runs across three workflow versions:

The results speak for themselves:

• More Granular Tasks: "Action Points" increased, indicating better task decomposition.
• Focused Guidance: "Impl Prompts" went from a single block to 15 distinct tabs, each for a specific sub-task.
• Elimination of Contamination: Most dramatically, "Go blocks" in our Python-targeted workflow dropped from a misleading 8 (and then 5) to a perfect 0. Simultaneously, relevant "Python blocks" surged from 0 to 55.

This data conclusively demonstrates that our fan-out mechanism creates more detailed, actionable guidance, and our wisdom filter successfully eradicates cross-stack contamination.

Lessons Learned & Challenges Overcome

Development is rarely without its bumps. One minor hiccup involved a function naming collision (extractOutputContent vs extractStepContent), which was quickly resolved by creating a new, dedicated helper getOutputContent(). These small refinements are part of the iterative process of building robust systems.

The journey to trace and fix the Go contamination was a significant challenge. It required diving deep into our data sources and understanding how project wisdom was loaded and applied at every stage of the workflow. The solution, applied at three distinct levels (enrichment, workflow steps, and implementation prompt generation), highlights the importance of layered defenses in complex AI systems.

What's Next?

With these critical features deployed and verified, our system is now live and assisting developers with unprecedented precision. Our immediate next steps involve a thorough consistency check against original requirements and further refinements to ensure maximum efficiency and accuracy.

This session marks a significant milestone in our quest for intelligent, context-aware AI-assisted development. By breaking down complex tasks and guarding against irrelevant information, we're empowering developers to build faster, smarter, and with greater confidence.