@fro.bot/systematic 3.26.1 → 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.
- package/ATTRIBUTIONS.md +2 -2
- package/HARNESSES.md +23 -8
- package/agents/research/learnings-researcher.md +82 -80
- package/dist/index.js +20 -2
- package/dist/lib/bootstrap.d.ts +17 -2
- package/dist/lib/pi-subagents-personas.d.ts +1 -1
- package/dist/pi.js +23 -5
- package/package.json +5 -5
- package/skills/ce-compound/SKILL.md +13 -11
- 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/references/schema.yaml +99 -15
- package/skills/ce-compound-refresh/references/yaml-schema.md +36 -7
- package/skills/ce-review/SKILL.md +5 -5
- 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/git-clean-gone-branches/SKILL.md +17 -7
- package/skills/git-worktree/SKILL.md +33 -309
- package/skills/git-worktree/scripts/worktree-manager.sh +568 -391
- package/skills/orchestrating-subagents/SKILL.md +1 -1
- package/skills/using-systematic/references/worktree-placement.md +1 -0
- 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.
|
|
@@ -29,7 +29,7 @@ If the script outputs `__NONE__`, report that no stale branches were found and s
|
|
|
29
29
|
|
|
30
30
|
### Step 2: Present branches and ask for confirmation
|
|
31
31
|
|
|
32
|
-
Show the user the list of branches that will be deleted. Format as a simple list:
|
|
32
|
+
Show the user the list of branches that will be deleted, and say what happens to their worktrees. Format as a simple list:
|
|
33
33
|
|
|
34
34
|
```
|
|
35
35
|
These local branches have been deleted from the remote:
|
|
@@ -38,6 +38,8 @@ These local branches have been deleted from the remote:
|
|
|
38
38
|
- bugfix/resolved-issue
|
|
39
39
|
- experiment/abandoned
|
|
40
40
|
|
|
41
|
+
Any of them that has a worktree with modified or untracked files, or a locked worktree, is skipped and kept. Ignored files (such as .env files and node_modules) in the worktrees that are removed are deleted.
|
|
42
|
+
|
|
41
43
|
Delete all of them? (y/n)
|
|
42
44
|
```
|
|
43
45
|
|
|
@@ -47,21 +49,29 @@ This is a yes-or-no decision on the entire list -- do not offer multi-selection
|
|
|
47
49
|
|
|
48
50
|
### Step 3: Delete confirmed branches
|
|
49
51
|
|
|
50
|
-
If the user confirms,
|
|
52
|
+
If the user confirms, run `git worktree list --porcelain` once. Each entry has a `worktree <path>` line and, for a branch checkout, a `branch refs/heads/<name>` line. The first entry is the main checkout. For each branch:
|
|
51
53
|
|
|
52
|
-
1.
|
|
53
|
-
2. If
|
|
54
|
-
3.
|
|
54
|
+
1. Find its worktree by exact match: the entry whose `branch` line is exactly `branch refs/heads/<branch>`. Do not use grep or a substring match, so `feature/a` never matches `feature/ab`.
|
|
55
|
+
2. If that entry is the main checkout, report `skipped: checked out in main checkout` and go to the next branch. Never switch the main checkout to another branch.
|
|
56
|
+
3. If that entry is another worktree and `pwd -P` is the worktree or inside it, report `skipped: current worktree`, keep its branch, and go to the next branch.
|
|
57
|
+
4. If the entry is another worktree that step 3 did not skip, remove it with `git worktree remove "$path"`. Never use the force option. If git refuses, report `skipped: <git reason>` and do not run `git branch -D` for that branch, because the worktree still has it checked out.
|
|
58
|
+
5. If the branch has no worktree, or the removal succeeded, delete the branch: `git branch -D "$branch"`
|
|
55
59
|
|
|
56
60
|
Report results as you go:
|
|
57
61
|
|
|
58
62
|
```
|
|
59
63
|
Removed worktree: .worktrees/feature/old-thing
|
|
60
64
|
Deleted branch: feature/old-thing
|
|
61
|
-
|
|
65
|
+
skipped: .worktrees/bugfix/resolved-issue contains modified or untracked files
|
|
62
66
|
Deleted branch: experiment/abandoned
|
|
63
67
|
|
|
64
|
-
Cleaned up
|
|
68
|
+
Cleaned up 2 branches, skipped 1.
|
|
65
69
|
```
|
|
66
70
|
|
|
71
|
+
The `git-worktree` skill creates worktrees under `.worktrees/<branch>` at the main repository root. Its cleanup command is the place to remove one of those worktrees with its stricter checks.
|
|
72
|
+
|
|
73
|
+
This skill finds worktrees anywhere, so it does not call that script.
|
|
74
|
+
|
|
75
|
+
`git branch -D` also deletes an unmerged gone branch. Checking merge state is out of scope for this skill.
|
|
76
|
+
|
|
67
77
|
If the user declines, acknowledge and stop without deleting anything.
|