ralph-file-schemas

name	ralph-file-schemas
description	Schema reference for ml-ralph state files (prd.json, kanban.json). Use when reading or writing these files.

Ralph File Schemas

Reference for .ml-ralph/ state files. Pure schemas - no philosophy (see RALPH.md for that).

---

prd.json (The Destination)

Your contract with the user. Rarely changes.

{
  "project": "project-name",
  "status": "draft|approved|blocked|complete",
  "problem": "What we're solving",
  "goal": "High-level objective",
  "success_criteria": ["Metric > threshold"],
  "constraints": ["No deep learning", "< 4hr training"],
  "scope": {
    "in": ["Feature engineering", "Gradient boosting"],
    "out": ["Neural networks", "External data"]
  }
}

Status Values

Status	Meaning	Who Can Set
draft	PRD being created	Agent
approved	User approved, work begins	User
blocked	Agent cannot progress (requires user decision)	Agent
complete	All success criteria verified met	Agent

What Can Change

Freely:

• success_criteria - Refine based on what's achievable
• constraints - Add discovered constraints
• scope - Adjust based on learnings

Requires user approval:

• problem - Core problem definition
• goal - High-level objective
• Any claim that success criteria are unachievable

Always log changes with rationale!

---

kanban.json (The Journey)

Your working plan. Updated EVERY iteration.

{
  "last_updated": "2024-01-28T10:30:00Z",
  "update_reason": "H-001 revealed distribution shift - reordering priorities",

  "current_focus": {
    "id": "T-007",
    "title": "Investigate pre-2020 performance degradation",
    "why": "H-001 showed temporal features hurt old data",
    "expected_outcome": "Clear understanding of distribution shift",
    "phase": "UNDERSTAND"
  },

  "up_next": [
    {
      "id": "T-008",
      "title": "Research distribution shift handling",
      "why": "Need SOTA approaches before designing solution",
      "depends_on": "T-007"
    }
  ],

  "backlog": [
    {
      "id": "T-011",
      "title": "Explore ensemble approaches",
      "why": "Might help with robustness",
      "notes": "Lower priority until baseline is solid"
    }
  ],

  "completed": [
    {
      "id": "T-006",
      "title": "Run H-001 temporal feature experiment",
      "outcome": "Partial success - revealed distribution shift",
      "completed_at": "2024-01-28T10:00:00Z"
    }
  ],

  "abandoned": [
    {
      "id": "T-003",
      "title": "Try neural network approach",
      "reason": "Research showed tree methods dominate",
      "abandoned_at": "2024-01-27T15:00:00Z"
    }
  ]
}

Field Reference

Field	Type	Description
current_focus	object	Single task being worked on NOW
up_next	array	5-6 step lookahead, ordered with dependencies
backlog	array	Ideas for later, less defined
completed	array	Done tasks with outcomes recorded
abandoned	array	Dropped tasks with reasons
last_updated	ISO timestamp	When kanban was last modified
update_reason	string	Why it was modified

Task Object Fields

Field	Required	Description
id	Yes	Unique identifier (e.g., "T-007")
title	Yes	Brief description
why	Yes	Rationale for this task
expected_outcome	current_focus only	What success looks like
phase	current_focus only	UNDERSTAND, STRATEGIZE, EXECUTE, or REFLECT
depends_on	Optional	Task ID this depends on
outcome	completed only	What actually happened
reason	abandoned only	Why it was dropped