tutor-service/docs/planning/WORKFLOW_CONTRACTS.md

# Workflow Contracts

## Purpose

LLM workflow outputs that affect product state must be typed and inspectable.
The Go backend should call internalized workflow interfaces and then persist
validated results. Product state must not depend on parsing arbitrary prose.

These contracts are initial planning contracts. Field names may evolve during
implementation, but the responsibilities should remain stable.

## Shared Types

```json
{
  "evidence_ref": {
    "kind": "answer|grading|source|session|asset",
    "id": "string",
    "quote": "string",
    "confidence": 0.0
  }
}
```

```json
{
  "concept_ref": {
    "id": "string",
    "label": "string",
    "track": "backend-developer"
  }
}
```

## DiagnosticResult

Produced by `diagnose_job_seeker`.

```json
{
  "user_id": "string",
  "track": "backend-developer",
  "target_role": "junior-backend-developer",
  "stack": ["go", "postgres"],
  "initial_readiness": "unknown|fragile|improving|interview_ready|strong_signal",
  "concept_findings": [
    {
      "concept": "concept_ref",
      "readiness": "unknown|fragile|improving|interview_ready|strong_signal",
      "reason": "string",
      "evidence": ["evidence_ref"]
    }
  ],
  "recommended_next_concepts": ["concept_ref"]
}
```

## GradedAnswer

Produced by `grade_interview_answer`.

```json
{
  "user_id": "string",
  "answer_id": "string",
  "question_id": "string",
  "concepts": ["concept_ref"],
  "scores": {
    "correctness": 0,
    "depth": 0,
    "communication": 0,
    "production_judgment": 0
  },
  "overall": "miss|partial|solid|strong",
  "strengths": ["string"],
  "gaps": ["string"],
  "evidence": ["evidence_ref"],
  "misconception_candidates": [
    {
      "label": "string",
      "description": "string",
      "evidence": ["evidence_ref"],
      "confidence": 0.0
    }
  ],
  "follow_up": {
    "needed": true,
    "question": "string",
    "purpose": "clarify|repair|stretch|pressure_test"
  }
}
```

## MemoryUpdateCandidate

Produced by `extract_learning_memory`.

```json
{
  "user_id": "string",
  "source_answer_id": "string",
  "updates": [
    {
      "kind": "concept_mastery|misconception|intervention|review_schedule",
      "concept": "concept_ref",
      "proposed_state": "unknown|fragile|improving|interview_ready|strong_signal",
      "summary": "string",
      "evidence": ["evidence_ref"],
      "confidence": 0.0,
      "durability": "tentative|confirmed"
    }
  ]
}
```

## NextChallenge

Produced by `select_next_challenge`.

```json
{
  "user_id": "string",
  "track": "backend-developer",
  "concept": "concept_ref",
  "ladder_level": "define|tradeoffs|debug|design_constraints|interview_pressure",
  "question": "string",
  "rationale": "string",
  "difficulty_action": "lower|hold|raise|recover",
  "evidence": ["evidence_ref"]
}
```

## ReadinessUpdate

Produced by `update_readiness_map`.

```json
{
  "user_id": "string",
  "track": "backend-developer",
  "concept_updates": [
    {
      "concept": "concept_ref",
      "previous": "unknown|fragile|improving|interview_ready|strong_signal",
      "next": "unknown|fragile|improving|interview_ready|strong_signal",
      "reason": "string",
      "evidence": ["evidence_ref"]
    }
  ],
  "unlocks": [
    {
      "kind": "boss_question|review_card|portfolio_entry",
      "label": "string",
      "reason": "string"
    }
  ]
}
```

## OntologyGap

Produced by `detect_ontology_gaps`.

```json
{
  "track": "backend-developer",
  "missing_or_weak": [
    {
      "concept": "concept_ref",
      "gap_type": "missing_prerequisite|weak_evidence|outdated|needs_rubric",
      "reason": "string",
      "supporting_sources": ["evidence_ref"],
      "proposed_action": "generate_candidate|request_source|human_review"
    }
  ]
}
```

## TeachingAssetPrompt

Produced by `generate_teaching_asset_prompt`.

```json
{
  "concept": "concept_ref",
  "asset_type": "diagram|lesson_slice|worksheet|interview_card",
  "prompt": "string",
  "source_evidence": ["evidence_ref"],
  "model_key": "gpt-image-v2",
  "requires_model_id_verification": true,
  "review_state": "candidate"
}
```

## Validation Rules

- Required IDs must be non-empty.
- Any state-changing output must include evidence.
- Confidence values must be between 0 and 1.
- Generated or inferred content starts as `candidate` or `tentative`.
- `model_key` is a product config key; production code must verify the actual
  provider model identifier before image calls.