← nyxcore-systems
5 min read

Taming the AI Dragon: From Hallucinations to Controlled Dreams

We faced a critical blocker: our AI workflow engine was hallucinating irrelevant content. This post details the deep dive, the systemic fixes, and how a bug unexpectedly sparked a new feature idea.

AILLMWorkflowEngineDebuggingTypeScriptPrismaSystemDesignDeveloperExperience

Every developer knows the thrill of shipping a new feature, but also the unique challenge of hunting down a critical bug. Recently, our team encountered a particularly thorny issue: our AI-powered workflow engine started... well, hallucinating. Instead of generating targeted code prompts, it began spouting generic scenarios involving healthcare and e-commerce, completely unrelated to the actual task. This wasn't just a quirky bug; it was a BLOCKER, threatening the integrity of our AI-driven processes.

This post chronicles the journey from a bewildering AI "dream" to a robust system, and how this very bug has inspired an exciting new feature: controlled AI ideation.

The Mystery of the Misguided AI

Our core mission was clear: investigate and resolve these hallucinated prompts, then fix the systemic root cause within our workflow engine. The initial symptoms were baffling: why would an AI focused on code generation suddenly pivot to medical appointments or online shopping carts?

The culprit, as it often is, lay in a subtle but critical misconfiguration. We traced the issue to a specific workflow, "nyxCore - Hetzner Deployment," and its Step 2, "Generate Code Prompts." This step was attempting to reference {{steps.Extract Features.content}}. The problem? No step with the label "Extract Features" actually existed in that workflow.

The Revelation: Without a valid reference, the resolvePrompt() function in our workflow engine was silently failing, resulting in an empty prompt being fed to the Large Language Model (LLM). An LLM, when given an empty or extremely vague prompt, will often fall back on its general training data and the persona's specialization to "fill in the blanks." In this case, our personas (Sasha Lindqvist/Engineering, Noor Okafor/Security, Lee DaSilva/DSGVO) had broad specializations, leading the LLM to creatively generate generic collaboration scenarios based on common enterprise domains like healthcare and e-commerce. It wasn't malice; it was an LLM trying its best with insufficient information!

Fortifying the Workflow Engine: A Two-Pronged Attack

Understanding the root cause allowed us to implement a comprehensive fix, tackling both the immediate symptoms and preventing future occurrences.

1. Systemic Robustness in src/server/services/workflow-engine.ts

Our first major overhaul focused on making the workflow engine more resilient to broken references:

  • detectMissingStepRefs(): We introduced a new helper function to proactively scan for {{steps.X.content}} patterns where 'X' doesn't correspond to an existing step label.
  • Intelligent resolvePrompt() Fallback: Instead of silently returning an empty string, resolvePrompt() now has a fallback mechanism. If step references are broken, it intelligently injects the outputs of all previous steps into the prompt. This ensures the LLM always has relevant context, even if a specific reference is missing.
  • Explicit Warnings: Silent failures are the bane of debugging. We changed the behavior for missing step labels to return a clear [WARNING: Step "X" not found. Available steps: ...] message.
  • Progress Event Emissions: To provide real-time feedback, we added warning yields before both execution paths (review steps and LLM steps). This means users now receive progress events detailing any missing reference issues before the LLM even runs, improving transparency and debugging.

2. Proactive Validation in src/server/trpc/routers/workflows.ts

Preventing bad data from entering the system is always better than fixing it later. We enhanced our workflow creation process:

  • Cross-Reference Validation on create: When a new workflow is submitted, our create mutation now performs a rigorous scan of all step prompts. It verifies that every {{steps.X.content}} reference points to an existing step label.
  • TRPCError BAD_REQUEST: If broken references are detected during creation, we now throw a TRPCError BAD_REQUEST with detailed information. This immediately informs the user about the issue, preventing the creation of a malformed workflow.

These changes ensure that our workflow engine is not only more robust in handling existing issues but also prevents new ones from being introduced.

Lessons Learned: Navigating the Dev Landscape

The debugging process always comes with its own set of challenges, and this session was no exception. Here are a few key takeaways:

  • Prisma Query Scaffolding: For non-trivial database queries, especially those involving select or complex where clauses, inline npx tsx -e '...' commands proved cumbersome due to shell escaping issues. The more reliable approach was to write temporary .ts script files within the project (to ensure correct module resolution), execute them with npx tsx scripts/file.ts, and then delete them. This saves significant headache!
  • Deep Dive into the Schema: We encountered mismatches between perceived and actual schema fields. For instance, templateId isn't directly on the Workflow model (it lives on WorkflowTemplate), and compareOutputs was actually the alternatives field (a JSON type) while checkpoint held review data. These moments serve as a reminder to always consult the Prisma schema or generated types when in doubt about data models.

The Unexpected Feature: Controlled Hallucination (/init-dream)

Perhaps the most exciting outcome of this "bug hunt" was the realization that the very behavior we were trying to fix – the AI generating creative, unexpected scenarios from a vague prompt – could be incredibly useful when intentionally controlled.

This led to the conceptual design of an /init-dream feature:

  • Purpose: To leverage the LLM's creative capacity for ideation and brainstorming.
  • Concept: Intentionally give a set of personas a vague or even empty prompt to generate novel collaboration scenarios.
  • Parameters: Users could specify a persona set, optional domain hints (e.g., "fintech," "logistics"), a "creativity temperature," and the desired output format.
  • Implementation: This could manifest as a new step type (dream), a dedicated workflow template, or a standalone feature.

The "bug" of AI hallucination, when harnessed, transforms into a powerful tool for generating innovative ideas, acting as a digital brainstorming partner. It's a testament to how often problems, when deeply understood, can reveal opportunities.

What's Next?

With the critical bugs resolved and a clear path forward for /init-dream, our immediate next steps include:

  • Designing /init-dream: Formalizing the feature specification and API.
  • Expanding Validation: Adding step cross-reference validation to the updateStep mutation as well, not just create.
  • UI Feedback: Implementing a UI indicator in the workflow builder to visually flag broken step references, enhancing the developer experience.
  • Workflow Refresh: Notifying users that existing workflows with broken references (like our 5d30703a-... example) will now benefit from the auto-context fallback, encouraging them to re-run for improved results.

This journey from a perplexing AI hallucination to a robust, self-correcting system, and ultimately to the exciting prospect of controlled AI creativity, has been a fantastic learning experience. It underscores the dynamic nature of working with AI and the constant evolution required to build intelligent, reliable systems.