hermes-detective/docs/chosen-detective-game.md

# Project: Hermes Detective Agency

**Chosen Concept:** 033v2 Detective  
**Date:** 2026-04-19  
**Status:** Concept Finalized  
**Tags:** hermes-agent, kimi-vision, game, multi-agent, open-ended, community

---

## Concept Summary

A mystery investigation game where a human (Chief) directs two AI agents — a **Witness** (powered by Kimi Vision) and a **Detective** (powered by Hermes) — to investigate visual cases.

**Core philosophy:** Open-ended solving. No single truth. Evidence guides, but multiple theories are valid.

---

## Elevator Pitch

> *"You're the Chief. Your Witness sees everything. Your Detective connects the dots. Build YOUR theory. See how it aligns with others."*

---

## The Story

You run a small detective agency. Your two AI assistants have superhuman abilities:

- **Witness** can look at any image and describe it perfectly — every detail, every inconsistency, every hidden clue.
- **Detective** can take those observations and build theories, spot patterns, and identify suspects.

Your job? **Direct the investigation.** Tell them what to look at. Ask the right questions. Build your theory.

**Key difference:** There's no single "right answer." The creator has an intended story, but your theory is valid if evidence supports it.

---

## Game Roles

### Chief (Human)
The player. You run the investigation.

| Action | Effect |
|--------|--------|
| Examine evidence | Witness + Kimi analyze |
| Question suspects | Detective probes, Witness watches |
| Compare items | Kimi highlights differences |
| Build theory | Cite evidence, form conclusion |
| Request truth | See creator's intended story (optional) |

### Witness (Agent A + Kimi)
The eyes. Analyzes visual evidence. Appears based on triggers.

| Input | Output |
|-------|--------|
| Crime scene photo | "I see glass shards, muddy footprints, a broken frame..." |
| Suspect photo | "This person has paint on their sleeve..." |
| Document | Extracts text, notes inconsistencies |
| Item close-up | Identifies details Chief might miss |

**Dynamic Appearance:** In harder cases, Witness doesn't appear until triggered.

### Detective (Agent B)
The brain. Builds theories, responds to questions.

| Input | Output |
|-------|--------|
| Witness observations | "Based on evidence, the thief entered through..." |
| Suspect profiles | "Suspect A has motive: insurance fraud..." |
| Human questions | "Good question, Chief. Let me look into that..." |
| Theory building | Helps Chief cite evidence for their theory |

---

## Difficulty System

### Difficulty Levels

| Difficulty | Description | Evidence | Suspects | Red Herrings | Plot Twist |
|-----------|-------------|----------|----------|---------------|------------|
| **Easy** | Obvious clues, clear path | 4-5 | 2 | ❌ | ❌ |
| **Medium** | Requires comparison | 6-7 | 3 | ❌ | ❌ |
| **Hard** | Red herrings present | 8-9 | 4 | ✅ | ❌ |
| **Hardcore** | Plot twist mid-case | 10-11 | 4 | ✅ | ✅ |
| **Impossible** | All elements, complex | 12+ | 5 | ✅ | ✅ |

### Daily Structure

```
One case per day, everyone gets the same case
Same difficulty for all players
Different case each day
```

### Starter Pack (5 Cases)

| Week | Difficulty | Theme |
|------|------------|-------|
| 1 | Easy | Simple theft |
| 2 | Medium | Missing person |
| 3 | Hard | Corporate fraud |
| 4 | Hardcore | Art heist (plot twist) |
| 5 | Impossible | Multi-layered conspiracy |

**Approach:** Add cases incrementally during development.

---

## Evidence System

### Evidence Types

| Type | What Kimi Sees | Example Clue |
|------|---------------|--------------|
| **Crime scene** | Scene layout, objects, anomalies | "Window was broken from inside" |
| **Surveillance** | People, actions, timestamps | "Person lingered at door for 3 minutes" |
| **Documents** | Text, handwriting, context | "Letter mentions 'meeting at midnight'" |
| **Photos** | People, items, locations | "Suspect's shoes match the footprint" |
| **Maps** | Routes, access points, exits | "Only one entrance visible to street" |
| **Items** | Condition, marks, connections | "Key is copy — grooves don't match original" |

### Evidence Citation

Evidence helps build theory. Not all evidence is required.

```
Chief's Theory: "I think Suspect B did it."

📎 Cited Evidence:
- Evidence #3: Crime scene photo
- Evidence #5: Security footage
- Evidence #8: Witness testimony
→ 3/10 evidence cited (30%)

💬 Detective: "That's a solid theory. The evidence 
supports B, but have you considered Evidence #7?"
```

### Hints Embedded in Evidence

Not a separate button. Hints are part of the evidence design.

| Level | Visibility | Example |
|-------|-----------|---------|
| **Too obvious** | Easy to find | "Letter saying 'I did it'" |
| **Barely obvious** | Check certain places | "Muddy shoes near suspect's home" |
| **Not too obvious** | Requires attention | "Timeline inconsistency in letter" |

### Witness Trigger System

In harder cases, Witness appears based on triggers.

```
Trigger Example:
Turn 1: Chief examines crime scene photo
Turn 2: Chief finds a hair sample on the floor
   ↓ [Trigger activated]
Turn 3: 👁️ Witness appears
   ↓ "I recognize this hair... it belongs to Suspect B's dog"
Turn 4: Chief examines suspect's home
Turn 5: 👁️ Witness appears again (new trigger)
   ↓ "I saw Suspect B leaving the gallery at midnight..."
```

**Indicator:** Each piece of evidence has a note indicating if it triggers Witness appearance.

---

## Open-Ended Solving

### Core Philosophy

> **No single truth. Multiple valid theories.**

| Before | After |
|--------|-------|
| One correct answer | Multiple valid theories |
| Wrong accusation = Fail | Theory valid if evidence supports |
| One winner | Everyone discusses |
| Truth ends game | Truth is guidance, not mandate |

### Theory Building

```
👤 Chief builds theory:
"I think Suspect B did it, with help from Suspect A.
B had access (night guard), A had keys (curator).
They split the insurance money."

📎 Chief cites evidence:
- Evidence #3: Crime scene (window not broken)
- Evidence #5: Security footage (B was inside)
- Evidence #7: A has master keys
- Evidence #9: Financial records (recent debt)

💬 Detective responds:
"That's a coherent theory. Your cited evidence
supports collaboration between A and B."
```

### Truth Reveal

**Available anytime. Does NOT end the game.**

| When | Why |
|------|-----|
| After building theory | "Did I get it right?" |
| When stuck | "Give me guidance" |
| Never | "I want to figure it out myself" |
| After solving | "See how close I was" |

```
📜 THE TRUTH (Creator's Intended)

The case was designed as:
"A and B collaborated. A had keys, B had access.
But C was the real mastermind, funding the whole thing."

👤 Your theory:
"Suspect B acted alone."

💬 Comparison:
- Your theory missed the collaboration element
- You correctly identified B as main actor
- Evidence you cited: 80% relevant
- 🎯 65% alignment with intended truth

💬 But: Your theory is still valid based on evidence!
Discussion continues. Truth is guidance, not mandate.
```

---

## Scoring System

### Per Case Statistics

| Metric | Calculation |
|--------|-------------|
| **Time** | Turns × 10 min (simplified) |
| **Evidence** | Evidence cited / Total evidence |
| **Alignment** | How close to creator's intended story |
| **Coherence** | Theory makes sense based on evidence |

### Statistics Display

```
┌─────────────────────────────────────┐
│ 📊 CASE STATISTICS                  │
├─────────────────────────────────────┤
│ ⏱️ Time: 6 turns × 10 min = 60 min │
│ 📎 Evidence: 7/10 cited (70%)       │
│ 🎯 Alignment: 85% with creator     │
│ 💬 Theory coherence: Strong        │
├─────────────────────────────────────┤
│ ⭐ Rating: Sharp Detective           │
└─────────────────────────────────────┘
```

### Rating Tiers

| Alignment | Rating |
|-----------|--------|
| 90-100% | Master Detective |
| 75-89% | Sharp Detective |
| 50-74% | Promising Detective |
| 25-49% | Apprentice |
| 0-24% | Rookie |

---

## Retry & Journal System

### Multiple Attempts

User can solve same case multiple times.

```
Case #47 — The Hartwell Heist

Your Attempts:
├── Attempt #1: 85% alignment, 6 turns 📖
├── Attempt #2: 92% alignment, 4 turns 📖
├── Attempt #3: In progress...
└── Best: 92% alignment
```

### Journal Documentation

Every attempt is documented (solve or not).

```
Attempt #1: April 19, 2026
├── Status: Solved
├── Evidence cited: 7/10
├── Alignment: 85%
├── Theory: "Suspect B acted alone"
└── Notes: "Missed the A-B collaboration"
```

### Privacy Settings

| Setting | Description |
|---------|-------------|
| **Private** | Only you see your attempts |
| **Publish stats** | Everyone sees your stats (default) |
| **Publish journal** | Anyone can read your solve |

---

## Replay (Observe Mode)

Watch how others solved the case.

```
📺 OBSERVE MODE

@alice's Solve of Case #47

Turn 1: Examined crime scene
Turn 2: Found hair sample → Witness appeared
Turn 3: Questioned Suspect B
Turn 4: Examined financial records
Turn 5: Cited evidence, formed theory
Turn 6: Requested truth reveal

⏱️ 6 turns | 🎯 85% alignment | ⭐ Sharp
```

**Only published journals are observable.**

---

## Case Creation System

### Starter Cases

5 cases (one per difficulty) as templates.

**Source:** Real solved cases adapted for the game.

### Community Cases

Anyone can create and share cases.

#### Creation Flow

```
1. Choose reference case (optional)
   "Let's base this on the Isabella Stewart Gardner theft"

2. Gather/create evidence
   Upload images (crime scene, suspects, documents)

3. Write case brief
   ├── Title, difficulty
   ├── Suspect list (names, photos)
   ├── Evidence set
   ├── Hidden truth (creator's intended story)
   ├── Red herrings (optional)
   ├── Plot twist (optional)
   └── Witness triggers (which evidence triggers Witness)

4. Test it
   Play through yourself to verify solvability

5. Publish
   ├── Private link (friends only)
   └── Public (case library)
```

### Case Format

```yaml
case:
  title: "The Hartwell Heist"
  difficulty: medium
  difficulty_description: "Requires comparison of evidence"
  
  evidence:
    - id: 1
      type: photo
      image: crime_scene.jpg
      description: "Crime scene photograph"
      triggers_witness: true
      hint_level: not_too_obvious
    
    - id: 2
      type: document
      image: letter.jpg
      description: "Anonymous letter found"
      triggers_witness: false
      hint_level: barely_obvious
  
  suspects:
    - name: "Suspect A"
      photo: suspect_a.jpg
      description: "Gallery curator"
      
  truth:
    summary: "A and B collaborated..."
    alignment_criteria:
      - "Correctly identified collaboration"
      - "Identified A as key holder"
      - "Identified B as main actor"

  witness_triggers:
    - evidence_id: 1
      testimony: "I see glass on the floor inside..."
```

### Case Creator Tools

| Tool | Purpose |
|------|---------|
| **Skill** | Hermes skill for case creation guidance |
| **Validator** | Verify case format is correct |

---

## Community Moderation

### Discovery Philosophy

> **Community cases are the jungle. Direct links are the path.**

| Discovery Method | Quality | Effort |
|-----------------|---------|--------|
| Case library (browse) | Mixed (jungle) | Low |
| Direct link from creator | Same quality | Medium |
| Social media / community | Trusted (curated) | High |

### Quality Signals

| Signal | Description |
|--------|-------------|
| **Visits** | How many times case was played |
| **Reviews** | 👍 or 👎 (no text, requires effort to spam) |

```
Case #47B — "The Missing Heirloom"
├── Visits: 234
├── 👍 45 | 👎 3
└── Quality score: High
```

**Note:** Review manipulation is possible but requires effort. Not perfect, but workable.

### Sharing Flow

```
Creator creates case
    ↓
Tests locally
    ↓
Publishes to community
    ↓
Shares link on social media / Discord
    ↓
Players try directly from creator
```

---

## Summary of Decisions

| Element | Decision |
|---------|----------|
| Difficulty | 5 levels (Easy → Impossible) |
| Daily structure | One case per day, same for all |
| Timer | ❌ No (first phase) |
| Hints | ✅ Embedded in evidence |
| Retry | ✅ Unlimited attempts |
| Journal | ✅ Every attempt documented |
| Observe | ✅ Watch published solves |
| Privacy | Private by default |
| Publish | Stats always, journal optional |
| Scoring | Alignment %, Evidence %, Time |
| Open-ended | ✅ No single truth |
| Truth reveal | Available anytime |
| Case source | Real cases + community |
| Witness | Dynamic (triggers in hard cases) |
| Red herrings | ✅ Hard+ difficulty |
| Plot twist | ✅ Hardcore+ difficulty |
| Community | Visits + reviews (no auth) |

---

## What's Next

Once we finalize the concept:
- Technical architecture
- UI/UX design
- Prompt engineering
- Case creation template
- Prototype development

---

## Related Documents

- `docs/ideas/COMPARISON.md` — Full comparison matrix
- `docs/ideas/008-visual-detective.md` — Initial brainstorm