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

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

- 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?