fix: consolidate compound-docs into ce-compound skill (#390)

plugins/compound-engineering/skills/ce-compound-refresh/SKILL.md

@@ -503,13 +503,22 @@ If a doc cluster has 3+ overlapping docs, process pairwise: consolidate the two
 
 Process Replace candidates **one at a time, sequentially**. Each replacement is written by a subagent to protect the main context window.
 
+When a replacement is needed, read the documentation contract files and pass their contents into the replacement subagent's task prompt:
+
+- `references/schema.yaml` — frontmatter fields and enum values
+- `references/yaml-schema.md` — category mapping
+- `assets/resolution-template.md` — section structure
+
+Do not let replacement subagents invent frontmatter fields, enum values, or section order from memory.
+
 **When evidence is sufficient:**
 
 1. Spawn a single subagent to write the replacement learning. Pass it:
    - The old learning's full content
    - A summary of the investigation evidence (what changed, what the current code does, why the old guidance is misleading)
    - The target path and category (same category as the old learning unless the category itself changed)
-2. The subagent writes the new learning following `ce:compound`'s document format: YAML frontmatter (title, category, date, module, component, tags), problem description, root cause, current solution with code examples, and prevention tips. It should use dedicated file search and read tools if it needs additional context beyond what was passed.
+   - The relevant contents of the three support files listed above
+2. The subagent writes the new learning using the support files as the source of truth: `references/schema.yaml` for frontmatter fields and enum values, `references/yaml-schema.md` for category mapping, and `assets/resolution-template.md` for section order. It should use dedicated file search and read tools if it needs additional context beyond what was passed.
 3. After the subagent completes, the orchestrator deletes the old learning file. The new learning's frontmatter may include `supersedes: [old learning filename]` for traceability, but this is optional — the git history and commit message provide the same information.
 
 **When evidence is insufficient:**

plugins/compound-engineering/skills/ce-compound-refresh/assets/resolution-template.md

@@ -0,0 +1,37 @@
+---
+title: [Clear problem title]
+date: [YYYY-MM-DD]
+category: [docs/solutions subdirectory]
+module: [Module or area]
+problem_type: [schema enum]
+component: [schema enum]
+symptoms:
+  - [Observable symptom 1]
+root_cause: [schema enum]
+resolution_type: [schema enum]
+severity: [schema enum]
+tags: [keyword-one, keyword-two]
+---
+
+# [Clear problem title]
+
+## Problem
+[1-2 sentence description of the issue and user-visible impact]
+
+## Symptoms
+- [Observable symptom or error]
+
+## What Didn't Work
+- [Attempted fix and why it failed]
+
+## Solution
+[The fix that worked, including code snippets when useful]
+
+## Why This Works
+[Root cause explanation and why the fix addresses it]
+
+## Prevention
+- [Concrete practice, test, or guardrail]
+
+## Related Issues
+- [Related docs or issues, if any]

plugins/compound-engineering/skills/ce-compound-refresh/references/schema.yaml

@@ -0,0 +1,127 @@
+# 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"

plugins/compound-engineering/skills/ce-compound-refresh/references/yaml-schema.md

@@ -0,0 +1,50 @@
+# 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`.