Skills › Compound Engineering › ce-compound › schema.yaml
schema.yaml
236 lines · skills/ce-compound/references/schema.yaml at 3449230
1# Documentation schema for learnings written by ce-compound
2# Treat this as the canonical frontmatter contract for compounded learnings.
3#
4# The schema has two tracks based on problem_type:
5# Bug track — problem_type is a defect or failure (build_error, test_failure, etc.)
6# Knowledge track — problem_type is guidance or practice (best_practice, workflow_issue, etc.)
7#
8# Both tracks share the same required core fields. The tracks differ in which
9# additional fields are required vs optional (see track_rules below).
11# Contract version for tools that load this file at a pinned ref (compound-cli).
12# Bump only when the file's shape changes, not when values are added.
13schema_version: 1
15# --- Track classification ---------------------------------------------------
16tracks:
17 bug:
18 description: "Defects, failures, and errors that were diagnosed and fixed"
19 problem_types:
20 - build_error
21 - test_failure
22 - runtime_error
23 - performance_issue
24 - database_issue
25 - security_issue
26 - ui_bug
27 - integration_issue
28 - logic_error
29 knowledge:
30 description: "Practices, patterns, conventions, decisions, workflow improvements, and documentation"
31 problem_types:
32 - best_practice
33 - documentation_gap
34 - workflow_issue
35 - developer_experience
36 - architecture_pattern
37 - design_pattern
38 - tooling_decision
39 - convention
41# --- Fields required by BOTH tracks -----------------------------------------
42required_fields:
43 module:
44 type: string
45 description: "Module or area affected"
47 date:
48 type: string
49 pattern: '^\d{4}-\d{2}-\d{2}$'
50 description: "Date documented (YYYY-MM-DD)"
52 problem_type:
53 type: enum
54 values:
55 - build_error
56 - test_failure
57 - runtime_error
58 - performance_issue
59 - database_issue
60 - security_issue
61 - ui_bug
62 - integration_issue
63 - logic_error
64 - developer_experience
65 - workflow_issue
66 - best_practice
67 - documentation_gap
68 - architecture_pattern
69 - design_pattern
70 - tooling_decision
71 - convention
72 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."
74 component:
75 type: string
76 suggested_values:
77 - data_model
78 - api_layer
79 - service_layer
80 - background_job
81 - database
82 - frontend
83 - messaging
84 - infrastructure
85 - observability
86 - authentication
87 - payments
88 - development_workflow
89 - testing_framework
90 - documentation
91 - tooling
92 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."
94 severity:
95 type: enum
96 values:
97 - critical
98 - high
99 - medium
100 - low
101 description: "Impact severity"
103# --- Track-specific rules ----------------------------------------------------
104track_rules:
105 bug:
106 required:
107 symptoms:
108 type: array[string]
109 min_items: 1
110 max_items: 5
111 description: "Observable symptoms such as errors or broken behavior"
112 root_cause:
113 type: string
114 suggested_values:
115 - wrong_api
116 - data_integrity
117 - concurrency
118 - async_timing
119 - memory_leak
120 - config_error
121 - logic_error
122 - test_isolation
123 - missing_validation
124 - missing_permission
125 - missing_workflow_step
126 - inadequate_documentation
127 - missing_tooling
128 - incomplete_setup
129 description: "Fundamental technical cause of the problem. Open vocabulary, corpus-first rule as for component, matched by the cause itself rather than the area."
130 resolution_type:
131 type: enum
132 values:
133 - code_fix
134 - migration
135 - config_change
136 - test_fix
137 - dependency_update
138 - environment_setup
139 - workflow_improvement
140 - documentation_update
141 - tooling_addition
142 - seed_data_update
143 description: "Type of fix applied"
145 knowledge:
146 optional:
147 applies_when:
148 type: array[string]
149 max_items: 5
150 description: "Conditions or situations where this guidance applies"
151 symptoms:
152 type: array[string]
153 max_items: 5
154 description: "Observable gaps or friction that prompted this guidance (optional for knowledge track)"
155 root_cause:
156 type: string
157 suggested_values:
158 - wrong_api
159 - data_integrity
160 - concurrency
161 - async_timing
162 - memory_leak
163 - config_error
164 - logic_error
165 - test_isolation
166 - missing_validation
167 - missing_permission
168 - missing_workflow_step
169 - inadequate_documentation
170 - missing_tooling
171 - incomplete_setup
172 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."
173 resolution_type:
174 type: enum
175 values:
176 - code_fix
177 - migration
178 - config_change
179 - test_fix
180 - dependency_update
181 - environment_setup
182 - workflow_improvement
183 - documentation_update
184 - tooling_addition
185 - seed_data_update
186 description: "Type of change, if applicable (optional for knowledge track)"
188# --- Fields optional for BOTH tracks ----------------------------------------
189optional_fields:
190 related_components:
191 type: array[string]
192 description: "Other components involved"
194 tags:
195 type: array[string]
196 max_items: 8
197 description: "Search keywords, lowercase and hyphen-separated"
199 retire_when:
200 type: string
201 description: "The change outside the repo that would retire this learning, and how a refresh can check for it without changing the repo, e.g. \"example-org/sdk#1234 closed as fixed in a released sdk version; check the issue and the sdk release notes\". Set it only when the guidance holds just while something outside the repo holds: an open upstream bug, a tool or platform version, a dependency's behavior. Omit it otherwise. A verification that needs a repo change, such as removing a workaround and rerunning CI, belongs in the body as the step before removal."
203# --- Fields optional for bug track only -------------------------------------
204bug_optional_fields:
205 framework_version:
206 type: string
207 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."
209# --- Backward compatibility --------------------------------------------------
210# Docs created before the track system was introduced may have bug-track
211# fields (symptoms, root_cause, resolution_type) on knowledge-type
212# problem_types. These are valid legacy docs:
213# - Bug-track fields present on a knowledge-track doc are harmless. Do not
214# strip them during refresh unless the doc is being rewritten for other reasons.
215# - When creating NEW docs, follow the track rules above.
216# Docs written before component/root_cause became open vocabulary may carry
217# values from the earlier closed list (rails_*, hotwire_turbo, missing_include,
218# ...) or a rails_version field. They stay valid; the corpus-first rule means a
219# repo whose docs consistently use those values keeps using them.
221# --- Validation rules --------------------------------------------------------
222validation_rules:
223 - "Determine track from problem_type using the tracks section above"
224 - "All shared required_fields must be present"
225 - "Bug-track required fields (symptoms, root_cause, resolution_type) must be present on bug-track docs"
226 - "Knowledge-track docs have no additional required fields beyond the shared ones"
227 - "Bug-track fields on existing knowledge-track docs are harmless (see backward compatibility note)"
228 - "Track-specific optional fields may be included but are not required"
229 - "Enum fields (problem_type, severity, resolution_type) must match allowed values exactly"
230 - "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"
231 - "Array fields must respect min_items/max_items when specified"
232 - "date must match YYYY-MM-DD format"
233 - "framework_version, if provided, only applies to bug-track docs"
234 - "retire_when is optional on both tracks; when present it is one string, and a doc without it stays valid"
235 - "tags should be lowercase and hyphen-separated"
236 - "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"