@fro.bot/systematic 3.26.2 → 3.26.3

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.
@@ -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
- **See `schema.yaml` for the complete schema specification.**
3
+ `schema.yaml` in this directory is the canonical contract for `docs/solutions/` frontmatter written by `ce:compound`.
4
4
 
5
- ## Required Fields
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
- - **module** (string): Module name (e.g., "EmailProcessing") or "System" for system-wide issues
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
- ## Optional Fields
14
+ The `problem_type` determines which **track** applies. Each track has different required and optional fields.
17
15
 
18
- - **rails_version** (string): Rails version in X.Y.Z format
19
- - **tags** (array): Searchable keywords (lowercase, hyphen-separated)
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
- ## Validation Rules
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
- 1. All required fields must be present
24
- 2. Enum fields must match allowed values exactly (case-sensitive)
25
- 3. symptoms must be YAML array with 1-5 items
26
- 4. date must match YYYY-MM-DD format
27
- 5. rails_version (if provided) must match X.Y.Z format
28
- 6. tags should be lowercase, hyphen-separated
29
-
30
- ## Example
31
-
32
- ```yaml
33
- ---
34
- module: Email Processing
35
- date: 2025-11-12
36
- problem_type: performance_issue
37
- component: rails_model
38
- symptoms:
39
- - "N+1 query when loading email threads"
40
- - "Brief generation taking >5 seconds"
41
- root_cause: missing_include
42
- rails_version: 7.1.2
43
- resolution_type: code_fix
44
- severity: high
45
- tags: [n-plus-one, eager-loading, performance]
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
- Based on `problem_type`, documentation is filed in:
52
-
53
- - **build_error** → `docs/solutions/build-errors/`
54
- - **test_failure** → `docs/solutions/test-failures/`
55
- - **runtime_error** → `docs/solutions/runtime-errors/`
56
- - **performance_issue** → `docs/solutions/performance-issues/`
57
- - **database_issue** → `docs/solutions/database-issues/`
58
- - **security_issue** → `docs/solutions/security-issues/`
59
- - **ui_bug** → `docs/solutions/ui-bugs/`
60
- - **integration_issue** → `docs/solutions/integration-issues/`
61
- - **logic_error** → `docs/solutions/logic-errors/`
62
- - **developer_experience** → `docs/solutions/developer-experience/`
63
- - **workflow_issue** → `docs/solutions/workflow-issues/`
64
- - **best_practice** → `docs/solutions/best-practices/`
65
- - **documentation_gap** → `docs/solutions/documentation-gaps/`
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