hallucination-detector

<objective>
The hallucination-detector skill prevents hallucinated technical decisions by validating all technology choices, API suggestions, database schemas, and architectural patterns against the project's documented tech stack and existing codebase.

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.
</objective>

<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
```markdown
# 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>

<workflow>
<step number="1">
**Load project's tech stack** (single source of truth)

Read and parse docs/project/tech-stack.md:

```markdown
# Technology Stack

## Frontend
- **Framework**: React 18.2
- **State Management**: Zustand 4.4
- **Routing**: React Router 6.x
- **HTTP Client**: Native fetch with custom wrapper
- **UI Library**: Tailwind CSS 3.x
- **Form Handling**: React Hook Form 7.x

## Backend
- **Runtime**: Node.js 20.x
- **Framework**: Express 4.18
- **Database**: PostgreSQL 15.2
- **ORM**: Prisma 5.x
- **Authentication**: JWT (jsonwebtoken)
- **Validation**: Zod 3.x

## Infrastructure
- **Cloud**: AWS
- **Hosting**: Vercel (frontend), Railway (backend)
- **Storage**: AWS S3
- **Database**: Supabase (managed PostgreSQL)
```

Parse into structured data:
```typescript
const techStack = {
  frontend: {
    framework: { name: 'React', version: '18.2' },
    stateManagement: { name: 'Zustand', version: '4.4' },
    routing: { name: 'React Router', version: '6.x' },
    // ...
  },
  backend: {
    runtime: { name: 'Node.js', version: '20.x' },
    framework: { name: 'Express', version: '4.18' },
    database: { name: 'PostgreSQL', version: '15.2' },
    // ...
  },
  infrastructure: {
    cloud: 'AWS',
    hosting: { frontend: 'Vercel', backend: 'Railway' },
    // ...
  }
};
```
</step>

<step number="2">
**Detect technical suggestion in conversation**

Pattern matching for technical claims:

**Framework/library suggestions**:
```
- "use React" → Extract: { type: 'framework', name: 'React' }
- "install redux" → Extract: { type: 'library', name: 'redux', category: 'state-management' }
- "import axios" → Extract: { type: 'library', name: 'axios', category: 'http-client' }
```

**API endpoint suggestions**:
```
- "call GET /api/users" → Extract: { type: 'api-endpoint', method: 'GET', path: '/api/users' }
- "Stripe API: createPaymentIntent" → Extract: { type: 'external-api', service: 'Stripe', method: 'createPaymentIntent' }
```

**Database schema suggestions**:
```
- "create User model" → Extract: { type: 'model