todo_metadata_standards.md

Todo Metadata Standards Analysis

Current State Analysis

Based on review of existing todo entries in the collection, here are the metadata patterns found:

Core Fields (Standardized)

These fields appear consistently across all todos:

{
  "_id": "ObjectId",
  "id": "uuid-v4-string",
  "description": "string",
  "project": "string",
  "priority": "High|Medium|Low|Critical",
  "status": "pending|completed|in_progress",
  "target_agent": "user|claude|system",
  "created_at": "unix_timestamp",
  "updated_at": "unix_timestamp"
}

Completion Fields (When status=completed)

{
  "completed_at": "unix_timestamp",
  "duration": "human_readable_string", // e.g. "1 minute"
  "duration_sec": "number_of_seconds"
}

Metadata Field Variations Found

Pattern 1: Phase-Based Metadata (Most Common)

Used in omnispindle todos for grouping related tasks:

"metadata": {
  "phase": "pm2-modernization|docker-update|...",
  "file": "path/to/file.ext",
  "completed_by": "email_address",
  "completion_comment": "detailed_completion_notes"
}

Pattern 2: Technical State Tracking

From your example in the conversation:

"metadata": {
  "file": "src/Omnispindle/stdio_server.py",
  "current_state": "hardcoded_all_tools",
  "needed": "respect_OMNISPINDLE_TOOL_LOADOUT"
}

Pattern 3: Feature Development Metadata

From inventorium todos:

"metadata": {
  "component": "TodoList Integration",
  "file": "src/components/TodoList.jsx",
  "changes": "170+ lines modified",
  "features": ["field validation", "MCP updates", "real-time saving", "TTS integration"],
  "completed_by": "email_address",
  "completion_comment": "detailed_notes"
}

Pattern 4: Task Analysis Metadata

Current analysis task:

"metadata": {
  "task_type": "analysis",
  "deliverable": "todo_metadata_standards.md",
  "scope": "review_existing_formats_and_standardize"
}

Identified Issues & Inconsistencies

1. Field Naming Variations

• target_agent vs target (some todos use target)
• completed_by appears in metadata vs potential top-level field
• completion_comment in metadata vs potential standardized field

2. Data Type Inconsistencies

• Some timestamps as unix timestamps, others as ISO strings
• Duration stored as both human-readable strings and seconds
• Arrays vs comma-separated strings for lists

3. Missing Structure

• No validation schema for metadata contents
• Free-form metadata leads to inconsistent structures
• No standardized way to represent file references, dependencies, or relationships

Proposed Standardization

Core Schema (Mandatory)

{
  "_id": "ObjectId",
  "id": "uuid-v4",
  "description": "string (required, max 500 chars)",
  "project": "string (required, from approved project list)",
  "priority": "Critical|High|Medium|Low (required)",
  "status": "pending|in_progress|completed|blocked (required)",
  "target_agent": "user|claude|system (required)",
  "created_at": "unix_timestamp (auto-generated)",
  "updated_at": "unix_timestamp (auto-updated)"
}

Completion Fields (When status=completed)

{
  "completed_at": "unix_timestamp",
  "completed_by": "email_or_agent_id",
  "completion_comment": "string (optional)",
  "duration_sec": "number (calculated)"
}

Standardized Metadata Schema

"metadata": {
  // Technical Context (optional)
  "files": ["array", "of", "file/paths"],
  "components": ["ComponentName1", "ComponentName2"],
  "commit_hash": "string (optional)",
  "branch": "string (optional)",

  // Project Organization (optional)
  "phase": "string (for multi-phase projects)",
  "epic": "string (for grouping related features)",
  "tags": ["tag1", "tag2", "tag3"],

  // State Tracking (optional)
  "current_state": "string (what exists now)",
  "target_state": "string (desired end state) (or epic-todo uuid)",
  "blockers": ["blocker1-uuid", "blocker2-uuid"],

  // Deliverables (optional)
  "deliverables": ["file1.md", "component.jsx"],
  "acceptance_criteria": ["criteria1", "criteria2"],

  // Analysis & Estimates (optional)
  "complexity": "Low|Medium|High|Complex",
  "confidence": "1|2|3|4|5",

  // Custom fields (project-specific)
  "custom": {
    // Project-specific metadata goes here
  }
}

Implementation Recommendations

Phase 1: Immediate Standardization

1. Standardize core fields naming (target_agent over target)
2. Move completed_by and completion_comment to top level, including updating Inventorium to use the new fields
3. Ensure all timestamps use unix format
4. Add validation for required fields

Phase 2: Metadata Migration

1. Create migration script to standardize existing metadata
2. Convert string arrays to proper arrays
3. Normalize file path references
4. Add missing completion tracking fields

Phase 3: Enhanced Features

1. Add dependency tracking between todos
2. Implement epic/phase grouping
3. Add estimation and complexity tracking
4. Create metadata validation schemas

Phase 4: Integration Improvements

1. Auto-populate file references from git changes
2. Link todos to commits/branches
3. Add integration with project management tools
4. Implement todo templates for common patterns

Form Design Recommendations

For the metadata form in todo creation:

Basic Tab

• Core fields (description, project, priority, target_agent)
• Phase/Epic selection (dropdown with project-specific options)
• Tags (multi-select or chip input)

Technical Tab (Optional)

• File references (file picker or manual entry)
• Component names (autocomplete from project)
• Dependencies (todo picker)
• Current/Target state (text areas)

Planning Tab (Optional)

• Estimated hours (number input)
• Complexity level (radio buttons)
• Acceptance criteria (dynamic list)
• Deliverables (file list)

This structure provides consistency while maintaining flexibility for different project needs.