@fro.bot/systematic 3.26.2 → 3.26.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/ATTRIBUTIONS.md +2 -2
- package/agents/research/learnings-researcher.md +87 -80
- package/dist/lib/pi-subagents-personas.d.ts +1 -1
- package/package.json +2 -2
- package/skills/ce-compound/SKILL.md +16 -14
- package/skills/ce-compound/assets/resolution-template.md +2 -2
- package/skills/ce-compound/references/schema.yaml +99 -15
- package/skills/ce-compound/references/yaml-schema.md +36 -7
- package/skills/ce-compound-refresh/SKILL.md +33 -16
- package/skills/ce-compound-refresh/assets/resolution-template.md +2 -2
- package/skills/ce-compound-refresh/references/schema.yaml +99 -15
- package/skills/ce-compound-refresh/references/yaml-schema.md +36 -7
- package/skills/ce-review/SKILL.md +1 -1
- package/skills/ce-review/references/review-output-template.md +1 -1
- package/skills/compound-docs/SKILL.md +75 -124
- package/skills/compound-docs/assets/resolution-template.md +65 -68
- package/skills/compound-docs/references/schema.yaml +331 -0
- package/skills/compound-docs/references/yaml-schema.md +122 -54
- package/skills/compound-docs/assets/critical-pattern-template.md +0 -34
- package/skills/compound-docs/schema.yaml +0 -176
|
@@ -0,0 +1,331 @@
|
|
|
1
|
+
# Documentation schema for learnings written by ce:compound
|
|
2
|
+
# Treat this as the canonical frontmatter contract for docs/solutions/.
|
|
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).
|
|
10
|
+
|
|
11
|
+
# --- Track classification ---------------------------------------------------
|
|
12
|
+
tracks:
|
|
13
|
+
bug:
|
|
14
|
+
description: "Defects, failures, and errors that were diagnosed and fixed"
|
|
15
|
+
problem_types:
|
|
16
|
+
- build_error
|
|
17
|
+
- test_failure
|
|
18
|
+
- runtime_error
|
|
19
|
+
- performance_issue
|
|
20
|
+
- database_issue
|
|
21
|
+
- security_issue
|
|
22
|
+
- ui_bug
|
|
23
|
+
- integration_issue
|
|
24
|
+
- logic_error
|
|
25
|
+
knowledge:
|
|
26
|
+
description: "Best practices, workflow improvements, patterns, conventions, and documentation"
|
|
27
|
+
problem_types:
|
|
28
|
+
- best_practice
|
|
29
|
+
- documentation_gap
|
|
30
|
+
- workflow_issue
|
|
31
|
+
- developer_experience
|
|
32
|
+
- architecture_pattern
|
|
33
|
+
- design_pattern
|
|
34
|
+
- tooling_decision
|
|
35
|
+
- convention
|
|
36
|
+
|
|
37
|
+
# --- Fields required by BOTH tracks -----------------------------------------
|
|
38
|
+
required_fields:
|
|
39
|
+
module:
|
|
40
|
+
type: string
|
|
41
|
+
description: "Module or area affected"
|
|
42
|
+
|
|
43
|
+
date:
|
|
44
|
+
type: string
|
|
45
|
+
pattern: '^\d{4}-\d{2}-\d{2}$'
|
|
46
|
+
description: "Date documented (YYYY-MM-DD)"
|
|
47
|
+
|
|
48
|
+
problem_type:
|
|
49
|
+
type: enum
|
|
50
|
+
values:
|
|
51
|
+
- build_error
|
|
52
|
+
- test_failure
|
|
53
|
+
- runtime_error
|
|
54
|
+
- performance_issue
|
|
55
|
+
- database_issue
|
|
56
|
+
- security_issue
|
|
57
|
+
- ui_bug
|
|
58
|
+
- integration_issue
|
|
59
|
+
- logic_error
|
|
60
|
+
- developer_experience
|
|
61
|
+
- workflow_issue
|
|
62
|
+
- best_practice
|
|
63
|
+
- documentation_gap
|
|
64
|
+
- architecture_pattern
|
|
65
|
+
- design_pattern
|
|
66
|
+
- tooling_decision
|
|
67
|
+
- convention
|
|
68
|
+
description: >-
|
|
69
|
+
Primary category — determines track (bug vs knowledge).
|
|
70
|
+
Prefer the narrowest applicable value; best_practice is the fallback
|
|
71
|
+
when no narrower knowledge-track value fits.
|
|
72
|
+
architecture_pattern: structural decisions about how components relate.
|
|
73
|
+
design_pattern: reusable solutions to recurring design problems.
|
|
74
|
+
tooling_decision: choices about tools, libraries, or build infrastructure.
|
|
75
|
+
convention: agreed-upon naming, formatting, or style rules.
|
|
76
|
+
|
|
77
|
+
component:
|
|
78
|
+
type: enum
|
|
79
|
+
values:
|
|
80
|
+
- backend
|
|
81
|
+
- frontend
|
|
82
|
+
- api
|
|
83
|
+
- database
|
|
84
|
+
- background_job
|
|
85
|
+
- authentication
|
|
86
|
+
- infrastructure
|
|
87
|
+
- configuration
|
|
88
|
+
- dependencies
|
|
89
|
+
- tooling
|
|
90
|
+
- development_workflow
|
|
91
|
+
- testing_framework
|
|
92
|
+
- documentation
|
|
93
|
+
- assistant
|
|
94
|
+
# Accepted by validators and refresh, never offered to writers. Existing
|
|
95
|
+
# docs that carry these values keep passing; do not rewrite them. Only new
|
|
96
|
+
# docs read `values` above.
|
|
97
|
+
legacy_values:
|
|
98
|
+
- rails_model
|
|
99
|
+
- rails_controller
|
|
100
|
+
- rails_view
|
|
101
|
+
- service_object
|
|
102
|
+
- frontend_stimulus
|
|
103
|
+
- hotwire_turbo
|
|
104
|
+
- email_processing
|
|
105
|
+
- brief_system
|
|
106
|
+
- payments
|
|
107
|
+
description: "Component involved"
|
|
108
|
+
|
|
109
|
+
severity:
|
|
110
|
+
type: enum
|
|
111
|
+
values:
|
|
112
|
+
- critical
|
|
113
|
+
- high
|
|
114
|
+
- medium
|
|
115
|
+
- low
|
|
116
|
+
description: "Impact severity"
|
|
117
|
+
|
|
118
|
+
# --- Track-specific rules ----------------------------------------------------
|
|
119
|
+
track_rules:
|
|
120
|
+
bug:
|
|
121
|
+
required:
|
|
122
|
+
symptoms:
|
|
123
|
+
type: array[string]
|
|
124
|
+
min_items: 1
|
|
125
|
+
max_items: 5
|
|
126
|
+
description: "Observable symptoms such as errors or broken behavior"
|
|
127
|
+
root_cause:
|
|
128
|
+
type: enum
|
|
129
|
+
values:
|
|
130
|
+
- missing_include
|
|
131
|
+
- missing_index
|
|
132
|
+
- wrong_api
|
|
133
|
+
- scope_issue
|
|
134
|
+
- thread_violation
|
|
135
|
+
- async_timing
|
|
136
|
+
- memory_leak
|
|
137
|
+
- config_error
|
|
138
|
+
- logic_error
|
|
139
|
+
- test_isolation
|
|
140
|
+
- missing_validation
|
|
141
|
+
- missing_permission
|
|
142
|
+
- missing_workflow_step
|
|
143
|
+
- inadequate_documentation
|
|
144
|
+
- missing_tooling
|
|
145
|
+
- incomplete_setup
|
|
146
|
+
legacy_values:
|
|
147
|
+
- missing_association
|
|
148
|
+
description: >-
|
|
149
|
+
Fundamental technical cause of the problem.
|
|
150
|
+
missing_include: a missing eager load or an N+1 query.
|
|
151
|
+
wrong_api: an API used in a way that does not fit the situation.
|
|
152
|
+
resolution_type:
|
|
153
|
+
type: enum
|
|
154
|
+
values:
|
|
155
|
+
- code_fix
|
|
156
|
+
- migration
|
|
157
|
+
- config_change
|
|
158
|
+
- test_fix
|
|
159
|
+
- dependency_update
|
|
160
|
+
- environment_setup
|
|
161
|
+
- workflow_improvement
|
|
162
|
+
- documentation_update
|
|
163
|
+
- tooling_addition
|
|
164
|
+
legacy_values:
|
|
165
|
+
- seed_data_update
|
|
166
|
+
description: "Type of fix applied"
|
|
167
|
+
|
|
168
|
+
knowledge:
|
|
169
|
+
optional:
|
|
170
|
+
applies_when:
|
|
171
|
+
type: array[string]
|
|
172
|
+
max_items: 5
|
|
173
|
+
description: "Conditions or situations where this guidance applies"
|
|
174
|
+
symptoms:
|
|
175
|
+
type: array[string]
|
|
176
|
+
max_items: 5
|
|
177
|
+
description: "Observable gaps or friction that prompted this guidance (optional for knowledge track)"
|
|
178
|
+
root_cause:
|
|
179
|
+
type: enum
|
|
180
|
+
values:
|
|
181
|
+
- missing_include
|
|
182
|
+
- missing_index
|
|
183
|
+
- wrong_api
|
|
184
|
+
- scope_issue
|
|
185
|
+
- thread_violation
|
|
186
|
+
- async_timing
|
|
187
|
+
- memory_leak
|
|
188
|
+
- config_error
|
|
189
|
+
- logic_error
|
|
190
|
+
- test_isolation
|
|
191
|
+
- missing_validation
|
|
192
|
+
- missing_permission
|
|
193
|
+
- missing_workflow_step
|
|
194
|
+
- inadequate_documentation
|
|
195
|
+
- missing_tooling
|
|
196
|
+
- incomplete_setup
|
|
197
|
+
legacy_values:
|
|
198
|
+
- missing_association
|
|
199
|
+
description: >-
|
|
200
|
+
Underlying cause, if there is a specific one (optional for knowledge track).
|
|
201
|
+
missing_include: a missing eager load or an N+1 query.
|
|
202
|
+
wrong_api: an API used in a way that does not fit the situation.
|
|
203
|
+
resolution_type:
|
|
204
|
+
type: enum
|
|
205
|
+
values:
|
|
206
|
+
- code_fix
|
|
207
|
+
- migration
|
|
208
|
+
- config_change
|
|
209
|
+
- test_fix
|
|
210
|
+
- dependency_update
|
|
211
|
+
- environment_setup
|
|
212
|
+
- workflow_improvement
|
|
213
|
+
- documentation_update
|
|
214
|
+
- tooling_addition
|
|
215
|
+
legacy_values:
|
|
216
|
+
- seed_data_update
|
|
217
|
+
description: "Type of change, if applicable (optional for knowledge track)"
|
|
218
|
+
|
|
219
|
+
# --- Fields optional for BOTH tracks ----------------------------------------
|
|
220
|
+
optional_fields:
|
|
221
|
+
related_components:
|
|
222
|
+
type: array[string]
|
|
223
|
+
description: "Other components involved"
|
|
224
|
+
|
|
225
|
+
tags:
|
|
226
|
+
type: array[string]
|
|
227
|
+
max_items: 8
|
|
228
|
+
description: "Search keywords, lowercase and hyphen-separated"
|
|
229
|
+
|
|
230
|
+
title:
|
|
231
|
+
type: string
|
|
232
|
+
description: "Human-readable title of the learning"
|
|
233
|
+
|
|
234
|
+
environment:
|
|
235
|
+
type: string
|
|
236
|
+
description: "Runtime, platform, or toolchain the learning applies to (free text)"
|
|
237
|
+
|
|
238
|
+
category:
|
|
239
|
+
type: string
|
|
240
|
+
description: "Directory name under docs/solutions/ the doc is filed in (matches the category mapping)"
|
|
241
|
+
|
|
242
|
+
last_updated:
|
|
243
|
+
type: string
|
|
244
|
+
pattern: '^\d{4}-\d{2}-\d{2}$'
|
|
245
|
+
description: "Date the doc was last edited (YYYY-MM-DD)"
|
|
246
|
+
|
|
247
|
+
last_refreshed:
|
|
248
|
+
type: string
|
|
249
|
+
pattern: '^\d{4}-\d{2}-\d{2}$'
|
|
250
|
+
description: "Date the doc was last verified against the codebase (YYYY-MM-DD)"
|
|
251
|
+
|
|
252
|
+
# Lifecycle fields. A missing status means active. Writers keep these
|
|
253
|
+
# consistent: updating or verifying a doc clears status: stale together with
|
|
254
|
+
# stale_reason and stale_date. Superseding is a manual edit; nothing writes it.
|
|
255
|
+
status:
|
|
256
|
+
type: enum
|
|
257
|
+
values:
|
|
258
|
+
- active
|
|
259
|
+
- stale
|
|
260
|
+
- superseded
|
|
261
|
+
description: "Lifecycle state. Missing means active."
|
|
262
|
+
|
|
263
|
+
superseded_by:
|
|
264
|
+
type: string
|
|
265
|
+
description: >-
|
|
266
|
+
Repo-root path of the doc that replaces this one, for example
|
|
267
|
+
docs/solutions/best-practices/example.md. Required when status is superseded.
|
|
268
|
+
The target must exist and must not itself be superseded.
|
|
269
|
+
|
|
270
|
+
superseded_date:
|
|
271
|
+
type: string
|
|
272
|
+
pattern: '^\d{4}-\d{2}-\d{2}$'
|
|
273
|
+
description: "Date the doc was superseded (YYYY-MM-DD)"
|
|
274
|
+
|
|
275
|
+
stale_reason:
|
|
276
|
+
type: string
|
|
277
|
+
description: "Why the doc is marked stale. Present only while status is stale."
|
|
278
|
+
|
|
279
|
+
stale_date:
|
|
280
|
+
type: string
|
|
281
|
+
pattern: '^\d{4}-\d{2}-\d{2}$'
|
|
282
|
+
description: "Date the doc was marked stale (YYYY-MM-DD). Present only while status is stale."
|
|
283
|
+
|
|
284
|
+
# --- Fields optional for bug track only -------------------------------------
|
|
285
|
+
bug_optional_fields:
|
|
286
|
+
rails_version:
|
|
287
|
+
type: string
|
|
288
|
+
pattern: '^\d+\.\d+\.\d+$'
|
|
289
|
+
description: "LEGACY. Rails version in X.Y.Z format. Preserved on existing bug-track docs, never offered to writers. Documentation only: the validator does not read it."
|
|
290
|
+
|
|
291
|
+
# --- Backward compatibility --------------------------------------------------
|
|
292
|
+
# Docs created before the track system was introduced may have bug-track
|
|
293
|
+
# fields (symptoms, root_cause, resolution_type) on knowledge-type
|
|
294
|
+
# problem_types. These are valid legacy docs:
|
|
295
|
+
# - Bug-track fields present on a knowledge-track doc are harmless. Do not
|
|
296
|
+
# strip them during refresh unless the doc is being rewritten for other reasons.
|
|
297
|
+
# - When creating NEW docs, follow the track rules above.
|
|
298
|
+
#
|
|
299
|
+
# Legacy vocabulary. Older docs may carry Rails and product-specific values:
|
|
300
|
+
# component values listed under `legacy_values`, the root_cause
|
|
301
|
+
# missing_association, the resolution_type seed_data_update, and the
|
|
302
|
+
# rails_version field. Validators and refresh accept them. Update paths
|
|
303
|
+
# preserve them and never rewrite them. Only new docs read `values`, so writers
|
|
304
|
+
# are never offered a legacy value.
|
|
305
|
+
|
|
306
|
+
# --- Validation rules --------------------------------------------------------
|
|
307
|
+
validation_rules:
|
|
308
|
+
- "Determine track from problem_type using the tracks section above"
|
|
309
|
+
- "All shared required_fields must be present"
|
|
310
|
+
- "Bug-track required fields (symptoms, root_cause, resolution_type) must be present on bug-track docs"
|
|
311
|
+
- "Knowledge-track docs have no additional required fields beyond the shared ones"
|
|
312
|
+
- "Bug-track fields on existing knowledge-track docs are harmless (see backward compatibility note)"
|
|
313
|
+
- "Track-specific optional fields may be included but are not required"
|
|
314
|
+
- "Enum fields must match allowed values exactly; legacy_values are accepted but never offered to writers"
|
|
315
|
+
- "status, if present, must be one of active, stale, superseded; missing means active"
|
|
316
|
+
- "A doc with status superseded must carry superseded_by naming an existing doc that is not itself superseded"
|
|
317
|
+
- "Clearing status: stale also clears stale_reason and stale_date"
|
|
318
|
+
- "Array fields must respect min_items/max_items when specified"
|
|
319
|
+
- "date must match YYYY-MM-DD format"
|
|
320
|
+
- "Legacy fields and values (see the backward compatibility note) are preserved on update and never offered to writers"
|
|
321
|
+
- "tags should be lowercase and hyphen-separated"
|
|
322
|
+
- |-
|
|
323
|
+
YAML quoting: scalar values that contain ' #' (space-hash) must be
|
|
324
|
+
double-quoted to prevent silent YAML comment truncation (the YAML parser
|
|
325
|
+
treats ' #' as an inline comment, silently dropping the rest of the value
|
|
326
|
+
with parseError: false). Example: problem: "cache miss # under load".
|
|
327
|
+
- |-
|
|
328
|
+
YAML quoting: array-of-strings frontmatter items must be double-quoted when
|
|
329
|
+
the value starts with a YAML reserved indicator (e.g., '{', '[', '|', '>',
|
|
330
|
+
'!', '&', '*', '?', ':', '-') or contains ': ' (colon-space). Example:
|
|
331
|
+
symptoms: - "[mdx-js/rollup] Could not parse expression"
|
|
@@ -1,65 +1,133 @@
|
|
|
1
1
|
# YAML Frontmatter Schema
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
`schema.yaml` in this directory is the canonical contract for `docs/solutions/` frontmatter written by `ce:compound`.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Use this file as the quick reference for:
|
|
6
|
+
- required fields
|
|
7
|
+
- enum values
|
|
8
|
+
- validation expectations
|
|
9
|
+
- category mapping
|
|
10
|
+
- track classification (bug vs knowledge)
|
|
6
11
|
|
|
7
|
-
|
|
8
|
-
- **date** (string): ISO 8601 date (YYYY-MM-DD)
|
|
9
|
-
- **problem_type** (enum): 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]
|
|
10
|
-
- **component** (enum): 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]
|
|
11
|
-
- **symptoms** (array): 1-5 specific observable symptoms
|
|
12
|
-
- **root_cause** (enum): 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]
|
|
13
|
-
- **resolution_type** (enum): One of [code_fix, migration, config_change, test_fix, dependency_update, environment_setup, workflow_improvement, documentation_update, tooling_addition, seed_data_update]
|
|
14
|
-
- **severity** (enum): One of [critical, high, medium, low]
|
|
12
|
+
## Tracks
|
|
15
13
|
|
|
16
|
-
|
|
14
|
+
The `problem_type` determines which **track** applies. Each track has different required and optional fields.
|
|
17
15
|
|
|
18
|
-
|
|
19
|
-
|
|
16
|
+
| Track | problem_types | Description |
|
|
17
|
+
|-------|--------------|-------------|
|
|
18
|
+
| **Bug** | `build_error`, `test_failure`, `runtime_error`, `performance_issue`, `database_issue`, `security_issue`, `ui_bug`, `integration_issue`, `logic_error` | Defects and failures that were diagnosed and fixed |
|
|
19
|
+
| **Knowledge** | `best_practice`, `documentation_gap`, `workflow_issue`, `developer_experience`, `architecture_pattern`, `design_pattern`, `tooling_decision`, `convention` | Practices, patterns, workflow improvements, and documentation |
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
Prefer the narrowest applicable value. `best_practice` is the fallback when no narrower knowledge-track value fits.
|
|
22
|
+
|
|
23
|
+
- `architecture_pattern` — structural decisions about how components relate
|
|
24
|
+
- `design_pattern` — reusable solutions to recurring design problems
|
|
25
|
+
- `tooling_decision` — choices about tools, libraries, or build infrastructure
|
|
26
|
+
- `convention` — agreed-upon naming, formatting, or style rules
|
|
27
|
+
|
|
28
|
+
## Required Fields (both tracks)
|
|
29
|
+
|
|
30
|
+
- **module**: Module or area affected
|
|
31
|
+
- **date**: ISO date in `YYYY-MM-DD`
|
|
32
|
+
- **problem_type**: One of the values listed in the Tracks table above
|
|
33
|
+
- **component**: One of `backend`, `frontend`, `api`, `database`, `background_job`, `authentication`, `infrastructure`, `configuration`, `dependencies`, `tooling`, `development_workflow`, `testing_framework`, `documentation`, `assistant`
|
|
34
|
+
- **severity**: One of `critical`, `high`, `medium`, `low`
|
|
35
|
+
|
|
36
|
+
## Bug Track Fields
|
|
37
|
+
|
|
38
|
+
Required:
|
|
39
|
+
- **symptoms**: YAML array with 1-5 observable symptoms (errors, broken behavior)
|
|
40
|
+
- **root_cause**: One of `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`
|
|
41
|
+
- `missing_include` is a missing eager load or an N+1 query. `wrong_api` is an API used in a way that does not fit the situation.
|
|
42
|
+
- **resolution_type**: One of `code_fix`, `migration`, `config_change`, `test_fix`, `dependency_update`, `environment_setup`, `workflow_improvement`, `documentation_update`, `tooling_addition`
|
|
43
|
+
|
|
44
|
+
## Knowledge Track Fields
|
|
45
|
+
|
|
46
|
+
Applies to every knowledge-track `problem_type` listed in the Tracks table above.
|
|
47
|
+
|
|
48
|
+
No additional required fields beyond the shared ones. All fields below are optional:
|
|
49
|
+
|
|
50
|
+
- **applies_when**: Conditions or situations where this guidance applies
|
|
51
|
+
- **symptoms**: Observable gaps or friction that prompted this guidance
|
|
52
|
+
- **root_cause**: Underlying cause, if there is a specific one
|
|
53
|
+
- **resolution_type**: Type of change, if applicable
|
|
54
|
+
|
|
55
|
+
## Optional Fields (both tracks)
|
|
56
|
+
|
|
57
|
+
- **related_components**: Other components involved
|
|
58
|
+
- **tags**: Search keywords, lowercase and hyphen-separated
|
|
59
|
+
- **title**: Human-readable title of the learning
|
|
60
|
+
- **environment**: Runtime, platform, or toolchain the learning applies to (free text)
|
|
61
|
+
- **category**: Directory name under `docs/solutions/` the doc is filed in (see Category Mapping)
|
|
62
|
+
- **last_updated**: Date the doc was last edited, `YYYY-MM-DD`
|
|
63
|
+
- **last_refreshed**: Date the doc was last verified against the codebase, `YYYY-MM-DD`
|
|
64
|
+
|
|
65
|
+
## Lifecycle Fields (both tracks, optional)
|
|
66
|
+
|
|
67
|
+
- **status**: One of `active`, `stale`, `superseded`. A missing `status` means `active`. An explicit empty value is invalid.
|
|
68
|
+
- **superseded_by**: Repo-root path of the doc that replaces this one, for example `docs/solutions/best-practices/example.md`. Required when `status` is `superseded`. The target must be an existing doc under `docs/solutions/` (not `README.md`) that is not itself superseded. A bare filename or any other path form does not resolve.
|
|
69
|
+
- **superseded_date**: Date the doc was superseded, `YYYY-MM-DD`
|
|
70
|
+
- **stale_reason**: Why the doc is marked stale. Present only while `status` is `stale`.
|
|
71
|
+
- **stale_date**: Date the doc was marked stale, `YYYY-MM-DD`. Present only while `status` is `stale`.
|
|
22
72
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
```
|
|
73
|
+
Writers keep these fields consistent. Updating or verifying a doc clears `status: stale` together with `stale_reason` and `stale_date`. Nothing writes `status: superseded`: superseding is a manual edit. A `superseded_by` on a doc that is not superseded is ignored.
|
|
74
|
+
|
|
75
|
+
## Optional Fields (bug track only, legacy)
|
|
76
|
+
|
|
77
|
+
- **rails_version**: Legacy. Rails version in `X.Y.Z` format. Preserved on existing bug-track docs, never offered to writers. Documentation only: the validator does not check it.
|
|
78
|
+
|
|
79
|
+
## Backward Compatibility
|
|
80
|
+
|
|
81
|
+
Docs created before the track system may have `symptoms`/`root_cause`/`resolution_type` on knowledge-type problem_types. These are valid legacy docs:
|
|
82
|
+
|
|
83
|
+
- 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.
|
|
84
|
+
- When creating **new** docs, follow the track rules above.
|
|
85
|
+
|
|
86
|
+
## Legacy Values
|
|
87
|
+
|
|
88
|
+
Older docs may carry Rails and product-specific values. Validators and refresh accept them, update paths preserve them and never rewrite them, and writers are never offered them. Only new docs read the offered values above.
|
|
89
|
+
|
|
90
|
+
| Field | Legacy values |
|
|
91
|
+
|-------|---------------|
|
|
92
|
+
| `component` | `rails_model`, `rails_controller`, `rails_view`, `service_object`, `frontend_stimulus`, `hotwire_turbo`, `email_processing`, `brief_system`, `payments` |
|
|
93
|
+
| `root_cause` | `missing_association` |
|
|
94
|
+
| `resolution_type` | `seed_data_update` |
|
|
95
|
+
|
|
96
|
+
`schema.yaml` lists these under `legacy_values`, beside `values`, on the bug-required and knowledge-optional lists alike.
|
|
48
97
|
|
|
49
98
|
## Category Mapping
|
|
50
99
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
-
|
|
54
|
-
-
|
|
55
|
-
-
|
|
56
|
-
-
|
|
57
|
-
-
|
|
58
|
-
-
|
|
59
|
-
-
|
|
60
|
-
-
|
|
61
|
-
-
|
|
62
|
-
-
|
|
63
|
-
-
|
|
64
|
-
-
|
|
65
|
-
-
|
|
100
|
+
- `build_error` -> `docs/solutions/build-errors/`
|
|
101
|
+
- `test_failure` -> `docs/solutions/test-failures/`
|
|
102
|
+
- `runtime_error` -> `docs/solutions/runtime-errors/`
|
|
103
|
+
- `performance_issue` -> `docs/solutions/performance-issues/`
|
|
104
|
+
- `database_issue` -> `docs/solutions/database-issues/`
|
|
105
|
+
- `security_issue` -> `docs/solutions/security-issues/`
|
|
106
|
+
- `ui_bug` -> `docs/solutions/ui-bugs/`
|
|
107
|
+
- `integration_issue` -> `docs/solutions/integration-issues/`
|
|
108
|
+
- `logic_error` -> `docs/solutions/logic-errors/`
|
|
109
|
+
- `developer_experience` -> `docs/solutions/developer-experience/`
|
|
110
|
+
- `workflow_issue` -> `docs/solutions/workflow-issues/`
|
|
111
|
+
- `best_practice` -> `docs/solutions/best-practices/`
|
|
112
|
+
- `documentation_gap` -> `docs/solutions/documentation-gaps/`
|
|
113
|
+
- `architecture_pattern` -> `docs/solutions/best-practices/`
|
|
114
|
+
- `design_pattern` -> `docs/solutions/best-practices/`
|
|
115
|
+
- `tooling_decision` -> `docs/solutions/best-practices/`
|
|
116
|
+
- `convention` -> `docs/solutions/best-practices/`
|
|
117
|
+
|
|
118
|
+
The four narrower knowledge-track types share the `best-practices/` directory rather than each
|
|
119
|
+
getting their own. That matches where such docs are already filed, and avoids single-document
|
|
120
|
+
directories that fragment search.
|
|
121
|
+
|
|
122
|
+
## Validation Rules
|
|
123
|
+
|
|
124
|
+
1. Determine the track from `problem_type` using the Tracks table.
|
|
125
|
+
2. All shared required fields must be present.
|
|
126
|
+
3. Bug-track required fields (`symptoms`, `root_cause`, `resolution_type`) must be present on bug-track docs.
|
|
127
|
+
4. Knowledge-track docs have no additional required fields beyond the shared ones.
|
|
128
|
+
5. Bug-track fields on existing knowledge-track docs are harmless (see Backward Compatibility).
|
|
129
|
+
6. Enum fields must match the allowed values exactly. Legacy values are accepted too (see Legacy Values).
|
|
130
|
+
7. Array fields must respect min/max item counts.
|
|
131
|
+
8. `date` must match `YYYY-MM-DD`.
|
|
132
|
+
9. `status`, if present, must be `active`, `stale` or `superseded`.
|
|
133
|
+
10. A `superseded` doc must carry a `superseded_by` that names an existing doc which is not itself superseded.
|
|
@@ -1,34 +0,0 @@
|
|
|
1
|
-
# Critical Pattern Template
|
|
2
|
-
|
|
3
|
-
Use this template when adding a pattern to `docs/solutions/patterns/critical-patterns.md`:
|
|
4
|
-
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
## N. [Pattern Name] (ALWAYS REQUIRED)
|
|
8
|
-
|
|
9
|
-
### ❌ WRONG ([Will cause X error])
|
|
10
|
-
```[language]
|
|
11
|
-
[code showing wrong approach]
|
|
12
|
-
```
|
|
13
|
-
|
|
14
|
-
### ✅ CORRECT
|
|
15
|
-
```[language]
|
|
16
|
-
[code showing correct approach]
|
|
17
|
-
```
|
|
18
|
-
|
|
19
|
-
**Why:** [Technical explanation of why this is required]
|
|
20
|
-
|
|
21
|
-
**Placement/Context:** [When this applies]
|
|
22
|
-
|
|
23
|
-
**Documented in:** `docs/solutions/[category]/[filename].md`
|
|
24
|
-
|
|
25
|
-
---
|
|
26
|
-
|
|
27
|
-
**Instructions:**
|
|
28
|
-
1. Replace N with the next pattern number
|
|
29
|
-
2. Replace [Pattern Name] with descriptive title
|
|
30
|
-
3. Fill in WRONG example with code that causes the problem
|
|
31
|
-
4. Fill in CORRECT example with the solution
|
|
32
|
-
5. Explain the technical reason in "Why"
|
|
33
|
-
6. Clarify when this pattern applies in "Placement/Context"
|
|
34
|
-
7. Link to the full troubleshooting doc where this was originally solved
|