Hallucination Triage & Root Cause

1. Concept Overview & Systemic Problem

When an agent outputs a non-existent method or uses a library not present in the project, the typical reaction of an inexperienced vibe coder is anger and emotional outbursts in chat: "Are you stupid?! I said to use Drizzle, not Prisma!"

• This leads to the accumulation of emotional clutter in the chat context.
• The model starts apologizing but continues to make mistakes since the root cause has not been addressed.

Hallucination Triage is a cold engineering approach: treating the model's hallucination not as "AI stupidity," but as a context delivery defect (Context Delivery Bug) that requires classification and systematic correction.

2. Architectural Taxonomy & Mental Model

┌─────────────────────────────────────────────────────────────┐
│                 HALLUCINATION TRIAGE MATRIX                 │
├─────────────────────────────────────────────────────────────┤
│ 1. DETECTION: The model issued a fabricated method or type  │
│    • Example: `db.user.findFirstOrThrow()` in Drizzle ORM   │
├─────────────────────────────────────────────────────────────┤
│                          │                                  │
│                          ▼ ROOT CAUSE DIAGNOSIS            │
│    ┌───────────────────────────────────────────────────┐    │
│    │ Type A: Missing file? ➔ The model did not see schema │    │
│    │ Type B: Rule conflict? ➔ Rules mention Prisma        │    │
│    │ Type C: Outdated weights? ➔ Model knowledge from 2023 │    │
│    └───────────────────────────────────────────────────┘    │
│                          │                                  │
│                          ▼ SYSTEMIC REMEDIATION            │
│ 1. Add the exact types file to the prompt                  │
│ 2. Enforce a rule in rules: "NEVER use Prisma syntax"      │
│ 3. Add validation with the compiler `tsc --noEmit`         │
└─────────────────────────────────────────────────────────────┘

3. Technical Pipeline & Internal Mechanics

01. Eliminating Hallucinations via Declaration Files

An agent continuously fabricated props for an internal button component. Instead of explanations, the developer created a file src/components/ui/button.d.ts with clear TypeScript types and added it to the automatic context list. Errors disappeared by 100%.

02. Post-Mortem Protocol for AI Bugs

After resolving a complex bug, the engineer spends 2 minutes updating .agents/rules/learnings.md:
"In this project, the Next.js router uses Server Actions without manual fetch calls. Do not generate unnecessary route handlers for simple mutations."

4. Production Engineering Scenarios

• Over-Correction: Attempting to fix one minor hallucination, an engineer writes a massive 50-line rule in all caps that prohibits the model from using useful auxiliary patterns. Rules must be surgically precise.
• Ignoring Model Versions: If the model has too low reasoning capability (e.g., an outdated 3B model), no triage will help it solve complex tasks. Sometimes the only remedy is to switch to a more powerful model.

5. Pitfalls, Common Mistakes & Security

Hallucination is a mirror of the quality of your engineering documentation. If the model hallucinates, it means your system has been insufficiently deterministic. Systematic triage transforms each error into a building block in the foundation of your repository's reliability.