hallucination-detector

Hallucinated technical decisions destroy projects:

• Suggesting React when project uses Vue (wrong framework)
• Creating duplicate User entity when one already exists (duplicate schema)
• Recommending fake npm packages that don't exist (non-existent dependencies)
• Proposing PostgreSQL functions not available in project's version (incompatible APIs)
• Suggesting AWS services when project uses Google Cloud (wrong cloud provider)
• Inventing API endpoints that don't exist in external service (fake APIs)

This skill acts as a reality checker that:

1. Loads project's tech stack from docs/project/tech-stack.md (single source of truth)
2. Validates all technical suggestions against documented choices
3. Verifies entities, APIs, packages exist in codebase or documentation
4. Requires evidence/citations for all technical claims
5. Blocks suggestions that violate documented architecture
6. Corrects hallucinations with actual project technology

The result: Zero hallucinated tech decisions, implementation matches architecture, code that actually works.

<quick_start> <trigger_pattern> Auto-trigger when detecting these suggestion patterns:

Technology suggestions:

• "Use [framework/library]" → Validate against tech-stack.md
• "Install [npm package]" → Verify package exists, check compatibility
• "Import from [module]" → Verify module exists in dependencies

API/Service suggestions:

• "Call [API endpoint]" → Verify endpoint exists in API docs
• "Use [external service]" → Confirm service in tech-stack.md
• "Query [database function]" → Check function exists in DB version

Schema suggestions:

• "Create [Entity] model" → Check if entity already exists
• "Add [column] to [table]" → Verify table exists, column doesn't
• "Define [interface]" → Check for existing similar types

Pattern suggestions:

• "Follow [architecture pattern]" → Validate against system-architecture.md
• "Use [design pattern]" → Check if pattern aligns with project conventions </trigger_pattern>

<basic_workflow> Step 1: Detect technical suggestion

• AI: "Let's use Redux for state management"
• Detected: Framework suggestion (Redux)

Step 2: Load tech stack from docs/project/tech-stack.md

# State Management
- **Library**: Zustand
- **Rationale**: Simpler than Redux, less boilerplate

Step 3: Validate suggestion against tech stack

• Suggested: Redux
• Documented: Zustand
• Mismatch detected: HALLUCINATION

Step 4: Block hallucinated suggestion

🚨 HALLUCINATION DETECTED

Suggested: Redux for state management
Reality: Project uses Zustand (documented in tech-stack.md)

Reason for Zustand (from tech-stack.md):
- Simpler than Redux
- Less boilerplate
- Already integrated in project

Corrected suggestion:
Use Zustand for state management (as documented)

Evidence: docs/project/tech-stack.md, line 23

Step 5: Provide correct suggestion

• AI: "I'll use Zustand for state management (project's documented choice)" </basic_workflow>

<immediate_value> Without hallucination-detector:

AI: "Let's use Redux for state management and Axios for HTTP"
Developer: *Implements Redux + Axios*
Code review: "Why Redux? We use Zustand. Why Axios? We use fetch wrapper."
Result: Wasted 3 hours, need to refactor entire implementation

With hallucination-detector:

AI: "Let's use Redux for state management"
Detector: "🚨 HALLUCINATION: Project uses Zustand, not Redux (tech-stack.md)"
AI: "Corrected: I'll use Zustand for state management"
Developer: *Implements with Zustand correctly*
Result: Correct implementation on first try, zero refactoring

</immediate_value> </quick_start>