# Schema for Solution Documentation
# Version: 1.0
# Validator: Manual validation per codify-solution skill Step 5
# Format: Custom Ring schema (not JSON Schema)
# Used by: codify-solution skill for AI agent validation
#
# This schema defines the required and optional fields for solution documentation.
# AI agents use this schema to validate YAML frontmatter before creating docs.

required_fields:
  date:
    type: string
    pattern: '^\d{4}-\d{2}-\d{2}$'
    description: "Date problem was solved (YYYY-MM-DD)"
    example: "2025-01-27"

  problem_type:
    type: enum
    values:
      - build_error
      - test_failure
      - runtime_error
      - performance_issue
      - database_issue
      - security_issue
      - ui_bug
      - integration_issue
      - logic_error
      - dependency_issue
      - configuration_error
      - workflow_issue
    description: "Primary category - determines storage directory"

  component:
    type: string
    description: "Affected component/module (project-specific, not enum)"
    example: "auth-service"

  symptoms:
    type: array
    items: string
    min_items: 1
    max_items: 5
    description: "Observable symptoms (error messages, visual issues)"
    example:
      - "Error: Cannot read property 'id' of undefined"
      - "Login button unresponsive after 3 clicks"

  root_cause:
    type: enum
    values:
      - missing_dependency
      - wrong_api_usage
      - configuration_error
      - logic_error
      - race_condition
      - memory_issue
      - type_mismatch
      - missing_validation
      - permission_error
      - environment_issue
      - version_incompatibility
      - data_corruption
      - missing_error_handling
      - incorrect_assumption
    description: "Fundamental cause of the problem"

  resolution_type:
    type: enum
    values:
      - code_fix
      - config_change
      - dependency_update
      - migration
      - test_fix
      - environment_setup
      - documentation
      - workaround
    description: "Type of fix applied"

  severity:
    type: enum
    values:
      - critical
      - high
      - medium
      - low
    description: "Impact severity of the original problem"

optional_fields:
  project:
    type: string
    description: "Project name (auto-detected from git remote)"
    example: "midaz"

  language:
    type: string
    description: "Primary language involved"
    example: "go"

  framework:
    type: string
    description: "Framework if applicable"
    example: "gin"

  tags:
    type: array
    items: string
    max_items: 8
    description: "Searchable keywords for discovery"
    example:
      - "authentication"
      - "jwt"
      - "middleware"

  related_issues:
    type: array
    items: string
    description: "Links to related solution docs or external issues"
    example:
      - "docs/solutions/security-issues/jwt-expiry-handling-20250115.md"
      - "https://github.com/org/repo/issues/123"

# Category to directory mapping
category_directories:
  build_error: "build-errors"
  test_failure: "test-failures"
  runtime_error: "runtime-errors"
  performance_issue: "performance-issues"
  database_issue: "database-issues"
  security_issue: "security-issues"
  ui_bug: "ui-bugs"
  integration_issue: "integration-issues"
  logic_error: "logic-errors"
  dependency_issue: "dependency-issues"
  configuration_error: "configuration-errors"
  workflow_issue: "workflow-issues"