skills/ce-compound/references/schema.yaml

# Documentation schema for learnings written by ce-compound
# Treat this as the canonical frontmatter contract for compounded learnings.
#
# The schema has two tracks based on problem_type:
#   Bug track  — problem_type is a defect or failure (build_error, test_failure, etc.)
#   Knowledge track — problem_type is guidance or practice (best_practice, workflow_issue, etc.)
#
# Both tracks share the same required core fields. The tracks differ in which
# additional fields are required vs optional (see track_rules below).

# --- Track classification ---------------------------------------------------
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
  knowledge:
    description: "Practices, patterns, conventions, decisions, workflow improvements, and documentation"
    problem_types:
      - best_practice
      - documentation_gap
      - workflow_issue
      - developer_experience
      - architecture_pattern
      - design_pattern
      - tooling_decision
      - convention

# --- Fields required by BOTH tracks -----------------------------------------
required_fields:
  module:
    type: string
    description: "Module 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
      - developer_experience
      - workflow_issue
      - best_practice
      - documentation_gap
      - architecture_pattern
      - design_pattern
      - tooling_decision
      - convention
    description: "Primary category — determines track (bug vs knowledge). Prefer the narrowest applicable value; best_practice is the fallback when no narrower knowledge-track value fits."

  component:
    type: string
    suggested_values:
      - data_model
      - api_layer
      - service_layer
      - background_job
      - database
      - frontend
      - messaging
      - infrastructure
      - observability
      - authentication
      - payments
      - development_workflow
      - testing_framework
      - documentation
      - tooling
    description: "Component or area involved. Open vocabulary: choose it per the corpus-first rule in yaml-schema.md (corpus value for this area, most-used spelling when the corpus disagrees, suggested_values only when no doc covers the area; corpus values reused as spelled). A newly chosen suggested_values fallback is lowercase, underscore-separated."

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

# --- Track-specific rules ----------------------------------------------------
track_rules:
  bug:
    required:
      symptoms:
        type: array[string]
        min_items: 1
        max_items: 5
        description: "Observable symptoms such as errors or broken behavior"
      root_cause:
        type: string
        suggested_values:
          - wrong_api
          - data_integrity
          - concurrency
          - 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. Open vocabulary, corpus-first rule as for component, matched by the cause itself rather than the area."
      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"

  knowledge:
    optional:
      applies_when:
        type: array[string]
        max_items: 5
        description: "Conditions or situations where this guidance applies"
      symptoms:
        type: array[string]
        max_items: 5
        description: "Observable gaps or friction that prompted this guidance (optional for knowledge track)"
      root_cause:
        type: string
        suggested_values:
          - wrong_api
          - data_integrity
          - concurrency
          - async_timing
          - memory_leak
          - config_error
          - logic_error
          - test_isolation
          - missing_validation
          - missing_permission
          - missing_workflow_step
          - inadequate_documentation
          - missing_tooling
          - incomplete_setup
        description: "Underlying cause, if there is a specific one (optional for knowledge track). Open vocabulary, corpus-first rule as for component, matched by the cause itself rather than the area."
      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 change, if applicable (optional for knowledge track)"

# --- Fields optional for BOTH tracks ----------------------------------------
optional_fields:
  related_components:
    type: array[string]
    description: "Other components involved"

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

# --- Fields optional for bug track only -------------------------------------
bug_optional_fields:
  framework_version:
    type: string
    description: "Framework or runtime name and version the bug was observed on, e.g. \"rails 7.1.2\" or \"node 22.4.0\". Only relevant for bug-track docs."

# --- Backward compatibility --------------------------------------------------
# Docs created before the track system was introduced may have bug-track
# fields (symptoms, root_cause, resolution_type) on knowledge-type
# problem_types. These are valid legacy docs:
#   - Bug-track fields present on a knowledge-track doc are harmless. Do not
#     strip them during refresh unless the doc is being rewritten for other reasons.
#   - When creating NEW docs, follow the track rules above.
# Docs written before component/root_cause became open vocabulary may carry
# values from the earlier closed list (rails_*, hotwire_turbo, missing_include,
# ...) or a rails_version field. They stay valid; the corpus-first rule means a
# repo whose docs consistently use those values keeps using them.

# --- Validation rules --------------------------------------------------------
validation_rules:
  - "Determine track from problem_type using the tracks section above"
  - "All shared required_fields must be present"
  - "Bug-track required fields (symptoms, root_cause, resolution_type) must be present on bug-track docs"
  - "Knowledge-track docs have no additional required fields beyond the shared ones"
  - "Bug-track fields on existing knowledge-track docs are harmless (see backward compatibility note)"
  - "Track-specific optional fields may be included but are not required"
  - "Enum fields (problem_type, severity, resolution_type) must match allowed values exactly"
  - "Open-vocabulary fields (component, root_cause) follow the corpus-first rule in yaml-schema.md: component is matched by area (the value existing docs under <root>/solutions/ use for that area, most-used spelling when existing docs disagree), root_cause is matched by the cause itself (the value existing docs use for that same cause, most-used spelling when existing docs disagree), suggested_values only when no existing doc covers the area (component) or names the cause (root_cause). Do not coin a near-synonym of a value the corpus already uses"
  - "Array fields must respect min_items/max_items when specified"
  - "date must match YYYY-MM-DD format"
  - "framework_version, if provided, only applies to bug-track docs"
  - "tags should be lowercase and hyphen-separated"
  - "Array-of-strings frontmatter items (symptoms, applies_when, tags, related_components, or any future array field) must be wrapped in double quotes when the value starts with a YAML reserved indicator (`, [, *, &, !, |, >, %, @, ?) or contains the substring `: ` — otherwise strict YAML parsers reject the file"