hermes-detective/docs/case-format-draft.md

# Case Format (YAML Schema) — Draft v1

**Date:** 2026-04-19  
**Status:** Draft  
**Purpose:** Define structure for investigation cases

---

## Case File Structure

```yaml
case:
  id: "easy-01"
  title: "The Missing Heirloom"
  difficulty: easy
  difficulty_description: "A straightforward case with obvious clues"
  
  # Case metadata
  version: "1.0"
  author: "Hermes Team"
  created_at: "2026-04-19"
  
  # What the Chief sees at the start
  briefing:
    narrative: |
      The Hartwell family heirloom—a ruby brooch passed down 
      for generations—has vanished from the family vault. 
      The vault was locked, and only three people had access.
    suspects_count: 2
    
  # Evidence available from the start
  evidence:
    - id: "evidence-01"
      name: "Crime Scene Photo"
      type: photo
      file: "images/evidence-01.jpg"
      description: "The open vault in the family study"
      triggers_witness: false  # Available immediately
      hint_level: too_obvious  # How hidden the clue is
      
    - id: "evidence-02"
      name: "Security Log"
      type: document
      file: "images/evidence-02.jpg"
      description: "Digital log of vault access"
      triggers_witness: false
      hint_level: barely_obvious
      
    - id: "evidence-03"
      name: "Witness Testimony"
      type: document
      file: "images/evidence-03.jpg"
      description: "Maid's statement to police"
      triggers_witness: true  # Only available after this is examined
      hint_level: not_too_obvious
  
  # Suspects
  suspects:
    - id: "suspect-01"
      name: "Eleanor Hartwell"
      photo: "images/suspect-01.jpg"
      description: |
        The eldest daughter. Had keys to the vault.
        Recently denied inheritance due to family dispute.
      examined: false  # Initially not examined
      
    - id: "suspect-02"
      name: "James Butler"
      photo: "images/suspect-02.jpg"
      description: |
        The family butler. Has served for 20 years.
        Seen near the vault that morning.
      examined: false

  # How evidence links to truth
  truth:
    # What the creator intended
    summary: |
      Eleanor Hartwell took the brooch because she was denied 
      inheritance. She hid it in the garden shed to claim insurance.
    
    # Criteria for alignment scoring
    criteria:
      - id: "criterion-01"
        description: "Identified Eleanor as main suspect"
        weight: 40
        
      - id: "criterion-02"
        description: "Understood motive (inheritance dispute)"
        weight: 30
        
      - id: "criterion-03"
        description: "Found the hiding spot (garden shed)"
        weight: 30
    
    # Evidence that supports each criterion
    evidence_map:
      criterion-01:
        supporting: ["evidence-01", "suspect-01"]
      criterion-02:
        supporting: ["evidence-02", "evidence-03"]
      criterion-03:
        supporting: ["evidence-03"]  # Hidden in testimony

  # Witness appearance rules
  witness:
    mode: "default"  # "default" | "triggered" | "manual"
    
    # For "triggered" mode - which evidence triggers witness
    triggers:
      - evidence_id: "evidence-03"
        testimony: |
          "I remember now—Miss Eleanor was arguing with her father 
          about the inheritance just last week. She seemed furious.
          And this morning, I saw her walking toward the garden..."

  # Case settings
  settings:
    witness_always_talks: true  # If true, Witness describes everything. If false, only what Chief asks.
    allow_skip: true           # Can skip evidence
    max_turns: 10             # Soft limit
```

---

## Field Explanations

### Required Fields

| Field | Description |
|-------|-------------|
| `case.id` | Unique identifier (slug) |
| `case.title` | Display name |
| `case.difficulty` | easy, medium, hard, hardcore, impossible |
| `case.briefing` | Initial narrative + suspect count |
| `case.evidence` | List of evidence items |
| `case.suspects` | List of suspects |
| `case.truth` | Creator's intended story + criteria |

### Evidence Types

| Type | Kimi Sees |
|------|-----------|
| `photo` | Visual analysis |
| `document` | Text extraction + analysis |
| `video` | Frame-by-frame (if supported) |
| `audio` | Transcription + analysis |

### Hint Levels

| Level | Meaning |
|-------|---------|
| `too_obvious` | Player will find it easily |
| `barely_obvious` | Requires some exploration |
| `not_too_obvious` | Hidden, requires attention |

### Witness Modes

| Mode | Behavior |
|------|---------|
| `default` | Witness appears with all triggered evidence |
| `triggered` | Witness only appears when evidence triggers |
| `manual` | Chief must explicitly request witness |

---

## Example Evidence Item

```yaml
- id: "evidence-01"
  name: "Crime Scene Photo"
  type: photo
  file: "images/evidence-01.jpg"
  description: "The open vault in the family study"
  triggers_witness: false
  hint_level: too_obvious
```

---

## Questions / Decisions Needed

1. **Witness modes** — Do we need all three? Or simplify?
2. **Criteria weights** — Should they always sum to 100%?
3. **Evidence linking** — Is `evidence_map` the right approach for alignment?
4. **Optional fields** — What should be required vs optional?
5. **Images** — How to reference? Path? URL?

---

## Starter Case Example

For the first proof-of-concept, we could create:

```
easy-01: "The Missing Heirloom"
- 3 evidence items
- 2 suspects
- 3 criteria
- Simple truth: Someone stole something for a reason
```

---

**Does this format make sense? What should we add/remove?**