YAML Frontmatter Schema

schema.yaml in this directory is the canonical contract for docs/solutions/ frontmatter written by ce:compound.

Use this file as the quick reference for:

• required fields
• enum values
• validation expectations
• category mapping

Required Fields

• module: Module or area affected by the problem
• date: ISO date in YYYY-MM-DD
• problem_type: One of 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
• component: One of 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
• symptoms: YAML array with 1-5 concrete symptoms
• root_cause: One of 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
• resolution_type: One of code_fix, migration, config_change, test_fix, dependency_update, environment_setup, workflow_improvement, documentation_update, tooling_addition, seed_data_update
• severity: One of critical, high, medium, low

Optional Fields

• rails_version: Rails version in X.Y.Z format
• related_components: Other components involved
• tags: Search keywords, lowercase and hyphen-separated

Category Mapping

• build_error -> docs/solutions/build-errors/
• test_failure -> docs/solutions/test-failures/
• runtime_error -> docs/solutions/runtime-errors/
• performance_issue -> docs/solutions/performance-issues/
• database_issue -> docs/solutions/database-issues/
• security_issue -> docs/solutions/security-issues/
• ui_bug -> docs/solutions/ui-bugs/
• integration_issue -> docs/solutions/integration-issues/
• logic_error -> docs/solutions/logic-errors/
• developer_experience -> docs/solutions/developer-experience/
• workflow_issue -> docs/solutions/workflow-issues/
• best_practice -> docs/solutions/best-practices/
• documentation_gap -> docs/solutions/documentation-gaps/

Validation Rules

1. All required fields must be present.
2. Enum fields must match the allowed values exactly.
3. symptoms must be a YAML array with 1-5 items.
4. date must match YYYY-MM-DD.
5. rails_version, if present, must match X.Y.Z.