# Documentation schema for learnings written by ce:compound
# Treat this as the canonical frontmatter contract for docs/solutions/.

required_fields:
  module:
    type: string
    description: "Module or area affected by the problem"

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

  problem_type:
    type: enum
    values:
      - build_error
      - test_failure
      - runtime_error
      - performance_issue
      - database_issue
      - security_issue
      - ui_bug
      - integration_issue
      - logic_error
      - developer_experience
      - workflow_issue
      - best_practice
      - documentation_gap
    description: "Primary category of the problem"

  component:
    type: enum
    values:
      - rails_model
      - rails_controller
      - rails_view
      - service_object
      - background_job
      - database
      - frontend_stimulus
      - hotwire_turbo
      - email_processing
      - brief_system
      - assistant
      - authentication
      - payments
      - development_workflow
      - testing_framework
      - documentation
      - tooling
    description: "Component involved"

  symptoms:
    type: array[string]
    min_items: 1
    max_items: 5
    description: "Observable symptoms such as errors or broken behavior"

  root_cause:
    type: enum
    values:
      - missing_association
      - missing_include
      - missing_index
      - wrong_api
      - scope_issue
      - thread_violation
      - async_timing
      - memory_leak
      - config_error
      - logic_error
      - test_isolation
      - missing_validation
      - missing_permission
      - missing_workflow_step
      - inadequate_documentation
      - missing_tooling
      - incomplete_setup
    description: "Fundamental technical cause of the problem"

  resolution_type:
    type: enum
    values:
      - code_fix
      - migration
      - config_change
      - test_fix
      - dependency_update
      - environment_setup
      - workflow_improvement
      - documentation_update
      - tooling_addition
      - seed_data_update
    description: "Type of fix applied"

  severity:
    type: enum
    values:
      - critical
      - high
      - medium
      - low
    description: "Impact severity"

optional_fields:
  rails_version:
    type: string
    pattern: '^\d+\.\d+\.\d+$'
    description: "Rails version in X.Y.Z format"

  related_components:
    type: array[string]
    description: "Other components involved"

  tags:
    type: array[string]
    max_items: 8
    description: "Search keywords, lowercase and hyphen-separated"

validation_rules:
  - "All required fields must be present"
  - "Enum fields must match allowed values exactly"
  - "symptoms must be a YAML array with 1-5 items"
  - "date must match YYYY-MM-DD format"
  - "rails_version, if provided, must match X.Y.Z format"
  - "tags should be lowercase and hyphen-separated"