# Knowledge documentation schema for {KNOWLEDGE_DIR}
# Canonical frontmatter contract. Two tracks: bug and knowledge.

tracks:
  bug:
    description: "Defects, failures, and errors that were diagnosed and fixed"
    problem_types:
      - build_error
      - test_failure
      - runtime_error
      - performance_issue
      - database_issue
      - security_issue
      - ui_bug
      - integration_issue
      - logic_error
      - config_error
  knowledge:
    description: "Practices, patterns, conventions, decisions, and workflow improvements"
    problem_types:
      - best_practice
      - documentation_gap
      - workflow_issue
      - developer_experience
      - architecture_pattern
      - design_pattern
      - tooling_decision
      - convention
      - api_design
      - testing_pattern

required_fields:
  module:
    type: string
    description: "Module, component, or area affected"

  date:
    type: string
    pattern: '^\d{4}-\d{2}-\d{2}$'
    description: "Date documented (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
      - config_error
      - developer_experience
      - workflow_issue
      - best_practice
      - documentation_gap
      - architecture_pattern
      - design_pattern
      - tooling_decision
      - convention
      - api_design
      - testing_pattern
    description: "Primary category — determines track (bug vs knowledge)"

  category:
    type: string
    description: "Directory name under {KNOWLEDGE_DIR} (see category-mapping.md)"

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

track_rules:
  bug:
    required:
      symptoms:
        type: array
        description: "Observable symptoms (errors, broken behavior)"
      root_cause:
        type: string
        description: "Fundamental technical cause"
      resolution_type:
        type: enum
        values:
          - code_fix
          - migration
          - config_change
          - test_fix
          - dependency_update
          - environment_setup
          - workflow_improvement
          - documentation_update
          - tooling_addition
        description: "Type of fix applied"
  knowledge:
    optional:
      applies_when:
        type: array
        description: "Conditions or situations where this guidance applies"

optional_fields:
  plan_id:
    type: string
    description: "Registered workflow/plan identity (ACTIVE execution_plans row)"
  tags:
    type: array
    max_items: 8
    description: "Search keywords, lowercase, hyphen-separated"
  last_updated:
    type: string
    pattern: '^\d{4}-\d{2}-\d{2}$'
    description: "Date of last substantive update (added when updating an existing doc)"
  related_components:
    type: array
    description: "Other components involved"