Claude-Code-Workflow/.claude/skills/skill-tuning/phases/state-schema.md

State Schema

Defines the state structure for skill-tuning orchestrator.

State Structure

interface TuningState {
  // === Core Status ===
  status: 'pending' | 'running' | 'completed' | 'failed';
  started_at: string;           // ISO timestamp
  updated_at: string;           // ISO timestamp

  // === Target Skill Info ===
  target_skill: {
    name: string;               // e.g., "software-manual"
    path: string;               // e.g., ".claude/skills/software-manual"
    execution_mode: 'sequential' | 'autonomous';
    phases: string[];           // List of phase files
    specs: string[];            // List of spec files
  };

  // === User Input ===
  user_issue_description: string;  // User's problem description
  focus_areas: string[];           // User-specified focus (optional)

  // === Diagnosis Results ===
  diagnosis: {
    context: DiagnosisResult | null;
    memory: DiagnosisResult | null;
    dataflow: DiagnosisResult | null;
    agent: DiagnosisResult | null;
  };

  // === Issues Found ===
  issues: Issue[];
  issues_by_severity: {
    critical: number;
    high: number;
    medium: number;
    low: number;
  };

  // === Fix Management ===
  proposed_fixes: Fix[];
  applied_fixes: AppliedFix[];
  pending_fixes: string[];      // Fix IDs pending application

  // === Iteration Control ===
  iteration_count: number;
  max_iterations: number;       // Default: 5

  // === Quality Metrics ===
  quality_score: number;        // 0-100
  quality_gate: 'pass' | 'review' | 'fail';

  // === Orchestrator State ===
  completed_actions: string[];
  current_action: string | null;
  action_history: ActionHistoryEntry[];

  // === Error Handling ===
  errors: ErrorEntry[];
  error_count: number;
  max_errors: number;           // Default: 3

  // === Output Paths ===
  work_dir: string;
  backup_dir: string;
}

interface DiagnosisResult {
  status: 'completed' | 'skipped' | 'failed';
  issues_found: number;
  severity: 'critical' | 'high' | 'medium' | 'low' | 'none';
  execution_time_ms: number;
  details: {
    patterns_checked: string[];
    patterns_matched: string[];
    evidence: Evidence[];
    recommendations: string[];
  };
}

interface Evidence {
  file: string;
  line?: number;
  pattern: string;
  context: string;
  severity: string;
}

interface Issue {
  id: string;                   // e.g., "ISS-001"
  type: 'context_explosion' | 'memory_loss' | 'dataflow_break' | 'agent_failure';
  severity: 'critical' | 'high' | 'medium' | 'low';
  priority: number;             // 1 = highest
  location: {
    file: string;
    line_start?: number;
    line_end?: number;
    phase?: string;
  };
  description: string;
  evidence: string[];
  root_cause: string;
  impact: string;
  suggested_fix: string;
  related_issues: string[];     // Issue IDs
}

interface Fix {
  id: string;                   // e.g., "FIX-001"
  issue_ids: string[];          // Issues this fix addresses
  strategy: FixStrategy;
  description: string;
  rationale: string;
  changes: FileChange[];
  risk: 'low' | 'medium' | 'high';
  estimated_impact: string;
  verification_steps: string[];
}

type FixStrategy =
  | 'context_summarization'     // Add context compression
  | 'sliding_window'            // Implement sliding context window
  | 'structured_state'          // Convert to structured state passing
  | 'constraint_injection'      // Add constraint propagation
  | 'checkpoint_restore'        // Add checkpointing mechanism
  | 'schema_enforcement'        // Add data contract validation
  | 'orchestrator_refactor'     // Refactor agent coordination
  | 'state_centralization'      // Centralize state management
  | 'custom';                   // Custom fix

interface FileChange {
  file: string;
  action: 'create' | 'modify' | 'delete';
  old_content?: string;
  new_content?: string;
  diff?: string;
}

interface AppliedFix {
  fix_id: string;
  applied_at: string;
  success: boolean;
  backup_path: string;
  verification_result: 'pass' | 'fail' | 'pending';
  rollback_available: boolean;
}

interface ActionHistoryEntry {
  action: string;
  started_at: string;
  completed_at: string;
  result: 'success' | 'failure' | 'skipped';
  output_files: string[];
}

interface ErrorEntry {
  action: string;
  message: string;
  timestamp: string;
  recoverable: boolean;
}

Initial State Template

{
  "status": "pending",
  "started_at": null,
  "updated_at": null,
  "target_skill": {
    "name": null,
    "path": null,
    "execution_mode": null,
    "phases": [],
    "specs": []
  },
  "user_issue_description": "",
  "focus_areas": [],
  "diagnosis": {
    "context": null,
    "memory": null,
    "dataflow": null,
    "agent": null
  },
  "issues": [],
  "issues_by_severity": {
    "critical": 0,
    "high": 0,
    "medium": 0,
    "low": 0
  },
  "proposed_fixes": [],
  "applied_fixes": [],
  "pending_fixes": [],
  "iteration_count": 0,
  "max_iterations": 5,
  "quality_score": 0,
  "quality_gate": "fail",
  "completed_actions": [],
  "current_action": null,
  "action_history": [],
  "errors": [],
  "error_count": 0,
  "max_errors": 3,
  "work_dir": null,
  "backup_dir": null
}

State Transition Diagram

                         ┌─────────────┐
                         │   pending   │
                         └──────┬──────┘
                                │ action-init
                                ↓
                         ┌─────────────┐
              ┌──────────│   running   │──────────┐
              │          └──────┬──────┘          │
              │                 │                 │
    diagnosis │    ┌────────────┼────────────┐    │ error_count >= 3
    actions   │    │            │            │    │
              │    ↓            ↓            ↓    │
              │ context     memory      dataflow  │
              │    │            │            │    │
              │    └────────────┼────────────┘    │
              │                 │                 │
              │                 ↓                 │
              │          action-verify            │
              │                 │                 │
              │     ┌───────────┼───────────┐     │
              │     │           │           │     │
              │     ↓           ↓           ↓     │
              │  quality    iterate      apply    │
              │  gate=pass  (< max)       fix     │
              │     │           │           │     │
              │     │           └───────────┘     │
              │     ↓                             ↓
              │ ┌─────────────┐           ┌─────────────┐
              └→│  completed  │           │   failed    │
                └─────────────┘           └─────────────┘

State Update Rules

Atomicity

All state updates must be atomic - read current state, apply changes, write entire state.

Immutability

Never mutate state in place. Always create new state object with changes.

Validation

Before writing state, validate against schema to prevent corruption.

Timestamps

Always update updated_at on every state change.

function updateState(workDir, updates) {
  const currentState = JSON.parse(Read(`${workDir}/state.json`));

  const newState = {
    ...currentState,
    ...updates,
    updated_at: new Date().toISOString()
  };

  // Validate before write
  if (!validateState(newState)) {
    throw new Error('Invalid state update');
  }

  Write(`${workDir}/state.json`, JSON.stringify(newState, null, 2));
  return newState;
}