@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
|
@@ -77,23 +77,33 @@ required_fields:
|
|
|
77
77
|
component:
|
|
78
78
|
type: enum
|
|
79
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:
|
|
80
98
|
- rails_model
|
|
81
99
|
- rails_controller
|
|
82
100
|
- rails_view
|
|
83
101
|
- service_object
|
|
84
|
-
- background_job
|
|
85
|
-
- database
|
|
86
102
|
- frontend_stimulus
|
|
87
103
|
- hotwire_turbo
|
|
88
104
|
- email_processing
|
|
89
105
|
- brief_system
|
|
90
|
-
- assistant
|
|
91
|
-
- authentication
|
|
92
106
|
- payments
|
|
93
|
-
- development_workflow
|
|
94
|
-
- testing_framework
|
|
95
|
-
- documentation
|
|
96
|
-
- tooling
|
|
97
107
|
description: "Component involved"
|
|
98
108
|
|
|
99
109
|
severity:
|
|
@@ -117,7 +127,6 @@ track_rules:
|
|
|
117
127
|
root_cause:
|
|
118
128
|
type: enum
|
|
119
129
|
values:
|
|
120
|
-
- missing_association
|
|
121
130
|
- missing_include
|
|
122
131
|
- missing_index
|
|
123
132
|
- wrong_api
|
|
@@ -134,7 +143,12 @@ track_rules:
|
|
|
134
143
|
- inadequate_documentation
|
|
135
144
|
- missing_tooling
|
|
136
145
|
- incomplete_setup
|
|
137
|
-
|
|
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.
|
|
138
152
|
resolution_type:
|
|
139
153
|
type: enum
|
|
140
154
|
values:
|
|
@@ -147,6 +161,7 @@ track_rules:
|
|
|
147
161
|
- workflow_improvement
|
|
148
162
|
- documentation_update
|
|
149
163
|
- tooling_addition
|
|
164
|
+
legacy_values:
|
|
150
165
|
- seed_data_update
|
|
151
166
|
description: "Type of fix applied"
|
|
152
167
|
|
|
@@ -163,7 +178,6 @@ track_rules:
|
|
|
163
178
|
root_cause:
|
|
164
179
|
type: enum
|
|
165
180
|
values:
|
|
166
|
-
- missing_association
|
|
167
181
|
- missing_include
|
|
168
182
|
- missing_index
|
|
169
183
|
- wrong_api
|
|
@@ -180,7 +194,12 @@ track_rules:
|
|
|
180
194
|
- inadequate_documentation
|
|
181
195
|
- missing_tooling
|
|
182
196
|
- incomplete_setup
|
|
183
|
-
|
|
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.
|
|
184
203
|
resolution_type:
|
|
185
204
|
type: enum
|
|
186
205
|
values:
|
|
@@ -193,6 +212,7 @@ track_rules:
|
|
|
193
212
|
- workflow_improvement
|
|
194
213
|
- documentation_update
|
|
195
214
|
- tooling_addition
|
|
215
|
+
legacy_values:
|
|
196
216
|
- seed_data_update
|
|
197
217
|
description: "Type of change, if applicable (optional for knowledge track)"
|
|
198
218
|
|
|
@@ -207,12 +227,66 @@ optional_fields:
|
|
|
207
227
|
max_items: 8
|
|
208
228
|
description: "Search keywords, lowercase and hyphen-separated"
|
|
209
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
|
+
|
|
210
284
|
# --- Fields optional for bug track only -------------------------------------
|
|
211
285
|
bug_optional_fields:
|
|
212
286
|
rails_version:
|
|
213
287
|
type: string
|
|
214
288
|
pattern: '^\d+\.\d+\.\d+$'
|
|
215
|
-
description: "Rails version in X.Y.Z format.
|
|
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."
|
|
216
290
|
|
|
217
291
|
# --- Backward compatibility --------------------------------------------------
|
|
218
292
|
# Docs created before the track system was introduced may have bug-track
|
|
@@ -221,6 +295,13 @@ bug_optional_fields:
|
|
|
221
295
|
# - Bug-track fields present on a knowledge-track doc are harmless. Do not
|
|
222
296
|
# strip them during refresh unless the doc is being rewritten for other reasons.
|
|
223
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.
|
|
224
305
|
|
|
225
306
|
# --- Validation rules --------------------------------------------------------
|
|
226
307
|
validation_rules:
|
|
@@ -230,10 +311,13 @@ validation_rules:
|
|
|
230
311
|
- "Knowledge-track docs have no additional required fields beyond the shared ones"
|
|
231
312
|
- "Bug-track fields on existing knowledge-track docs are harmless (see backward compatibility note)"
|
|
232
313
|
- "Track-specific optional fields may be included but are not required"
|
|
233
|
-
- "Enum fields must match allowed values exactly"
|
|
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"
|
|
234
318
|
- "Array fields must respect min_items/max_items when specified"
|
|
235
319
|
- "date must match YYYY-MM-DD format"
|
|
236
|
-
- "
|
|
320
|
+
- "Legacy fields and values (see the backward compatibility note) are preserved on update and never offered to writers"
|
|
237
321
|
- "tags should be lowercase and hyphen-separated"
|
|
238
322
|
- |-
|
|
239
323
|
YAML quoting: scalar values that contain ' #' (space-hash) must be
|
|
@@ -30,15 +30,16 @@ Prefer the narrowest applicable value. `best_practice` is the fallback when no n
|
|
|
30
30
|
- **module**: Module or area affected
|
|
31
31
|
- **date**: ISO date in `YYYY-MM-DD`
|
|
32
32
|
- **problem_type**: One of the values listed in the Tracks table above
|
|
33
|
-
- **component**: One of `
|
|
33
|
+
- **component**: One of `backend`, `frontend`, `api`, `database`, `background_job`, `authentication`, `infrastructure`, `configuration`, `dependencies`, `tooling`, `development_workflow`, `testing_framework`, `documentation`, `assistant`
|
|
34
34
|
- **severity**: One of `critical`, `high`, `medium`, `low`
|
|
35
35
|
|
|
36
36
|
## Bug Track Fields
|
|
37
37
|
|
|
38
38
|
Required:
|
|
39
39
|
- **symptoms**: YAML array with 1-5 observable symptoms (errors, broken behavior)
|
|
40
|
-
- **root_cause**: One of `
|
|
41
|
-
-
|
|
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`
|
|
42
43
|
|
|
43
44
|
## Knowledge Track Fields
|
|
44
45
|
|
|
@@ -55,10 +56,25 @@ No additional required fields beyond the shared ones. All fields below are optio
|
|
|
55
56
|
|
|
56
57
|
- **related_components**: Other components involved
|
|
57
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`
|
|
58
64
|
|
|
59
|
-
##
|
|
65
|
+
## Lifecycle Fields (both tracks, optional)
|
|
60
66
|
|
|
61
|
-
- **
|
|
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`.
|
|
72
|
+
|
|
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.
|
|
62
78
|
|
|
63
79
|
## Backward Compatibility
|
|
64
80
|
|
|
@@ -67,6 +83,18 @@ Docs created before the track system may have `symptoms`/`root_cause`/`resolutio
|
|
|
67
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.
|
|
68
84
|
- When creating **new** docs, follow the track rules above.
|
|
69
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.
|
|
97
|
+
|
|
70
98
|
## Category Mapping
|
|
71
99
|
|
|
72
100
|
- `build_error` -> `docs/solutions/build-errors/`
|
|
@@ -98,7 +126,8 @@ directories that fragment search.
|
|
|
98
126
|
3. Bug-track required fields (`symptoms`, `root_cause`, `resolution_type`) must be present on bug-track docs.
|
|
99
127
|
4. Knowledge-track docs have no additional required fields beyond the shared ones.
|
|
100
128
|
5. Bug-track fields on existing knowledge-track docs are harmless (see Backward Compatibility).
|
|
101
|
-
6. Enum fields must match the allowed values exactly.
|
|
129
|
+
6. Enum fields must match the allowed values exactly. Legacy values are accepted too (see Legacy Values).
|
|
102
130
|
7. Array fields must respect min/max item counts.
|
|
103
131
|
8. `date` must match `YYYY-MM-DD`.
|
|
104
|
-
9. `
|
|
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.
|
|
@@ -23,7 +23,7 @@ Check if `$ARGUMENTS` contains `mode:autofix`. If present, strip it from argumen
|
|
|
23
23
|
- **Skip all user questions.** Never pause for input.
|
|
24
24
|
- **Process all docs in scope.** No scope narrowing questions — if no scope hint was provided, process everything.
|
|
25
25
|
- **Attempt all safe actions:** Keep (no-op), Update (fix references), Consolidate (merge and delete subsumed doc), auto-Delete (unambiguous criteria met), Replace (when evidence is sufficient). If a write succeeds, record it as **applied**. If a write fails (e.g., permission denied), record the action as **recommended** in the report and continue — do not stop or ask for permissions.
|
|
26
|
-
- **Mark as stale when uncertain.** If classification is genuinely ambiguous (Update vs Replace vs Consolidate vs Delete) or Replace evidence is insufficient, mark as stale with `status: stale`, `stale_reason`, and `stale_date` in the frontmatter. If even the stale-marking write fails, include it as a recommendation.
|
|
26
|
+
- **Mark as stale when uncertain.** If classification is genuinely ambiguous (Update vs Replace vs Consolidate vs Delete) or Replace evidence is insufficient, mark as stale with `status: stale`, `stale_reason`, and `stale_date` in the frontmatter (subject to the stale guard in Lifecycle Consistency). If even the stale-marking write fails, include it as a recommendation.
|
|
27
27
|
- **Use conservative confidence.** In interactive mode, borderline cases get a user question. In autofix mode, borderline cases get marked stale. Err toward stale-marking over incorrect action.
|
|
28
28
|
- **Always generate a report.** The report is the primary deliverable. It has two sections: **Applied** (actions that were successfully written) and **Recommended** (actions that could not be written, with full rationale so a human can apply them or run the skill interactively). The report structure is the same regardless of what permissions were granted — the only difference is which section each action lands in.
|
|
29
29
|
|
|
@@ -82,9 +82,10 @@ For each candidate artifact, classify it into one of five outcomes:
|
|
|
82
82
|
- the user has provided enough concrete replacement context to document the successor honestly, or
|
|
83
83
|
- the codebase investigation found the current approach and can document it as the successor, or
|
|
84
84
|
- newer docs, pattern docs, PRs, or issues provide strong successor evidence.
|
|
85
|
-
8. **Delete when the code is gone.** If the referenced code,
|
|
85
|
+
8. **Delete when the code is gone.** If the referenced code, module, or workflow no longer exists in the codebase and no successor can be found, delete the file — don't default to Keep just because the general advice is still "sound." A learning about a deleted feature misleads readers into thinking that feature still exists. A missing referenced file with no matching code is strong evidence that the implementation is gone, not proof that the learning is obsolete. Before deleting, apply the problem-domain check in Phase 2 ("Before deleting"): if the problem domain is gone too, Delete; if it persists, Replace. When in doubt between Keep and Delete, ask the user (in interactive mode) or mark as stale (in autofix mode).
|
|
86
86
|
9. **Evaluate document-set design, not just accuracy.** In addition to checking whether each doc is accurate, evaluate whether it is still the right unit of knowledge. If two or more docs overlap heavily, determine whether they should remain separate, be cross-scoped more clearly, or be consolidated into one canonical document. Redundant docs are dangerous because they drift silently — two docs saying the same thing will eventually say different things.
|
|
87
87
|
10. **Delete, don't archive.** There is no `_archived/` directory. When a doc is no longer useful, delete it. Git history preserves every deleted file — that is the archive. A dedicated archive directory creates problems: archived docs accumulate, pollute search results, and nobody reads them. If someone needs a deleted doc, `git log --diff-filter=D -- docs/solutions/` will find it.
|
|
88
|
+
11. **Preserve legacy values.** Existing docs may carry values that `references/schema.yaml` lists under `legacy_values` (older `component` values, the `root_cause` and `resolution_type` values listed there) and the version field that the schema marks LEGACY. They are valid. Do not report them as off-vocabulary and do not rewrite them. Only a new doc, such as a Replace successor, reads the offered `values`.
|
|
88
89
|
|
|
89
90
|
## Scope Selection
|
|
90
91
|
|
|
@@ -195,7 +196,7 @@ Three guidelines that are easy to get wrong:
|
|
|
195
196
|
|
|
196
197
|
## Phase 1.5: Investigate Pattern Docs
|
|
197
198
|
|
|
198
|
-
After reviewing the underlying learning docs, investigate any relevant pattern docs under `docs/solutions/patterns
|
|
199
|
+
After reviewing the underlying learning docs, investigate any relevant pattern docs under `docs/solutions/patterns/` **only if that directory exists**. It is a legacy location: no writer creates it, so most repos never have one. Treat it as read-only. Use it as evidence and report findings about it, but do not edit, delete or create files there, and do not create the directory. If it does not exist, skip this phase.
|
|
199
200
|
|
|
200
201
|
Pattern docs are high-leverage — a stale pattern is more dangerous than a stale individual learning because future work may treat it as broadly applicable guidance. Evaluate whether the generalized rule still holds given the refreshed state of the learnings it depends on.
|
|
201
202
|
|
|
@@ -290,7 +291,7 @@ After gathering evidence, assign one recommended action.
|
|
|
290
291
|
|
|
291
292
|
### Keep
|
|
292
293
|
|
|
293
|
-
The learning is still accurate and useful. Do not edit the file — report that it was reviewed and remains trustworthy. Only add `last_refreshed` if you are already making a meaningful update for another reason.
|
|
294
|
+
The learning is still accurate and useful. Do not edit the file — report that it was reviewed and remains trustworthy. Only add `last_refreshed` if you are already making a meaningful update for another reason. The one exception is a doc that carries a stale marker: see Lifecycle Consistency.
|
|
294
295
|
|
|
295
296
|
### Update
|
|
296
297
|
|
|
@@ -328,7 +329,7 @@ By the time you identify a Replace candidate, Phase 1 investigation has already
|
|
|
328
329
|
|
|
329
330
|
- **Sufficient evidence** — you understand both what the old learning recommended AND what the current approach is. The investigation found the current code patterns, the new file locations, the changed architecture. → Proceed to write the replacement (see Phase 4 Replace Flow).
|
|
330
331
|
- **Insufficient evidence** — the drift is so fundamental that you cannot confidently document the current approach. The entire subsystem was replaced, or the new architecture is too complex to understand from a file scan alone. → Mark as stale in place:
|
|
331
|
-
- Add `status: stale`, `stale_reason: [what you found]`, `stale_date: YYYY-MM-DD` to the frontmatter
|
|
332
|
+
- Add `status: stale`, `stale_reason: [what you found]`, `stale_date: YYYY-MM-DD` to the frontmatter (subject to the stale guard in Lifecycle Consistency)
|
|
332
333
|
- Report what evidence you found and what is missing
|
|
333
334
|
- Recommend the user run `ce:compound` after their next encounter with that area, when they have fresh problem-solving context
|
|
334
335
|
|
|
@@ -347,7 +348,7 @@ Action: delete the file. No archival directory, no metadata — just delete it.
|
|
|
347
348
|
|
|
348
349
|
When a learning's referenced files are gone, that is strong evidence — but only that the **implementation** is gone. Before deleting, reason about whether the **problem the learning solves** is still a concern in the codebase:
|
|
349
350
|
|
|
350
|
-
- A learning about session token storage where `
|
|
351
|
+
- A learning about session token storage where `src/auth/auth-token.ts` is gone — does the application still handle session tokens? If so, the concept persists under a new implementation. That is Replace, not Delete.
|
|
351
352
|
- A learning about a deprecated API endpoint where the entire feature was removed — the problem domain is gone. That is Delete.
|
|
352
353
|
|
|
353
354
|
Do not search mechanically for keywords from the old learning. Instead, understand what problem the learning addresses, then investigate whether that problem domain still exists in the codebase. The agent understands concepts — use that understanding to look for where the problem lives now, not where the old code used to be.
|
|
@@ -358,13 +359,13 @@ Do not search mechanically for keywords from the old learning. Instead, understa
|
|
|
358
359
|
- the learning is fully superseded by a clearly better successor AND the old doc adds no distinct value
|
|
359
360
|
- the document is plainly redundant and adds nothing the canonical doc doesn't already say
|
|
360
361
|
|
|
361
|
-
If the implementation is gone but the problem domain persists (the app still does auth, still
|
|
362
|
+
If the implementation is gone but the problem domain persists (the app still does auth, still sends notifications, still handles migrations), classify as **Replace** — the problem still matters and the current approach should be documented.
|
|
362
363
|
|
|
363
364
|
Do not keep a learning just because its general advice is "still sound" — if the specific code it references is gone, the learning misleads readers. But do not delete a learning whose problem domain is still active — that knowledge gap should be filled with a replacement.
|
|
364
365
|
|
|
365
366
|
## Pattern Guidance
|
|
366
367
|
|
|
367
|
-
Apply the same five outcomes (Keep, Update, Consolidate, Replace, Delete) to pattern docs, but evaluate them as **derived guidance** rather than incident-level learnings. Key differences:
|
|
368
|
+
Apply the same five outcomes (Keep, Update, Consolidate, Replace, Delete) to pattern docs, but evaluate them as **derived guidance** rather than incident-level learnings. This covers broad pattern or convention docs filed anywhere under `docs/solutions/` by the canonical category mapping. It does not cover a legacy `docs/solutions/patterns/` directory, which stays read-only (see Phase 1.5). Key differences:
|
|
368
369
|
|
|
369
370
|
- **Keep**: the underlying learnings still support the generalized rule and examples remain representative
|
|
370
371
|
- **Update**: the rule holds but examples, links, scope, or supporting references drifted
|
|
@@ -469,7 +470,7 @@ Apply in-place edits only when the solution is still substantively correct.
|
|
|
469
470
|
|
|
470
471
|
Examples of valid in-place updates:
|
|
471
472
|
|
|
472
|
-
- Rename `
|
|
473
|
+
- Rename `src/auth/auth-token.ts` reference to `src/auth/session-token.ts`
|
|
473
474
|
- Update `module: AuthToken` to `module: SessionToken`
|
|
474
475
|
- Fix outdated links to related docs
|
|
475
476
|
- Refresh implementation notes after a directory move
|
|
@@ -485,6 +486,8 @@ Examples that should **not** be in-place updates:
|
|
|
485
486
|
|
|
486
487
|
Those cases require **Replace**, not Update.
|
|
487
488
|
|
|
489
|
+
An Update also clears any stale marker on the doc: see Lifecycle Consistency. Preserve legacy values (Core Rule 11).
|
|
490
|
+
|
|
488
491
|
### Consolidate Flow
|
|
489
492
|
|
|
490
493
|
The orchestrator handles consolidation directly (no subagent needed — the docs are already read and the merge is a focused edit). Process Consolidate candidates by topic cluster. For each cluster identified in Phase 1.75:
|
|
@@ -492,8 +495,8 @@ The orchestrator handles consolidation directly (no subagent needed — the docs
|
|
|
492
495
|
1. **Confirm the canonical doc** — the broader, more current, more accurate doc in the cluster.
|
|
493
496
|
2. **Extract unique content** from the subsumed doc(s) — anything the canonical doc does not already cover. This might be specific edge cases, additional prevention rules, or alternative debugging approaches.
|
|
494
497
|
3. **Merge unique content** into the canonical doc in a natural location. Do not just append — integrate it where it logically belongs. If the unique content is small (a bullet point, a sentence), inline it. If it is a substantial sub-topic, add it as a clearly labeled section.
|
|
495
|
-
4. **Update cross-references** — if any other docs reference the subsumed doc, update those references to point to the canonical doc.
|
|
496
|
-
5. **Delete the subsumed doc
|
|
498
|
+
4. **Update cross-references** — if any other docs reference the subsumed doc, update those references to point to the canonical doc. Retarget any `superseded_by` pointer to the subsumed doc as described in Lifecycle Consistency.
|
|
499
|
+
5. **Delete the subsumed doc**, but only once the safeguards in Lifecycle Consistency ("Retarget before removing") hold. Do not archive it, do not add redirect metadata — just delete the file. Git history preserves it.
|
|
497
500
|
|
|
498
501
|
If a doc cluster has 3+ overlapping docs, process pairwise: consolidate the two most overlapping docs first, then evaluate whether the merged result should be consolidated with the next doc.
|
|
499
502
|
|
|
@@ -516,14 +519,14 @@ Do not let replacement subagents invent frontmatter fields, enum values, or sect
|
|
|
516
519
|
1. Spawn a single subagent to write the replacement learning. Pass it:
|
|
517
520
|
- The old learning's full content
|
|
518
521
|
- A summary of the investigation evidence (what changed, what the current code does, why the old guidance is misleading)
|
|
519
|
-
- The target path
|
|
522
|
+
- The target path. File the new learning in the directory that the category mapping in `references/yaml-schema.md` gives for its `problem_type`, not simply the old learning's directory. Create that directory on first use (`mkdir -p`).
|
|
520
523
|
- The relevant contents of the three support files listed above
|
|
521
|
-
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.
|
|
522
|
-
3. After the subagent completes, the orchestrator
|
|
524
|
+
2. The subagent writes the new learning using the support files as the source of truth, and uses only the offered `values` for enum fields, never a `legacy_values` entry: `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.
|
|
525
|
+
3. After the subagent completes, the orchestrator retargets any `superseded_by` pointer to the old learning at the new one, then deletes the old learning file, subject to the safeguards in Lifecycle Consistency ("Retarget before removing"). Do not write a `supersedes` field or any other back-pointer into the new learning — the git history and commit message record the replacement.
|
|
523
526
|
|
|
524
527
|
**When evidence is insufficient:**
|
|
525
528
|
|
|
526
|
-
1. Mark the learning as stale in place:
|
|
529
|
+
1. Mark the learning as stale in place (subject to the stale guard in Lifecycle Consistency):
|
|
527
530
|
- Add to frontmatter: `status: stale`, `stale_reason: [what you found]`, `stale_date: YYYY-MM-DD`
|
|
528
531
|
2. Report what evidence was found and what is missing
|
|
529
532
|
3. Recommend the user run `ce:compound` after their next encounter with that area
|
|
@@ -532,6 +535,17 @@ Do not let replacement subagents invent frontmatter fields, enum values, or sect
|
|
|
532
535
|
|
|
533
536
|
Delete only when a learning is clearly obsolete, redundant (with no unique content to merge), or its problem domain is gone. Do not delete a document just because it is old — age alone is not a signal.
|
|
534
537
|
|
|
538
|
+
Before deleting, apply the Delete cascade in Lifecycle Consistency.
|
|
539
|
+
|
|
540
|
+
### Lifecycle Consistency
|
|
541
|
+
|
|
542
|
+
The lifecycle fields (`status`, `stale_reason`, `stale_date`, `superseded_by`, `superseded_date`) must stay consistent after every action. In a user repo this prose is the only protection, since the validator runs only in Systematic's own CI. Find pointers with a content search for `superseded_by:` under `docs/solutions/`. A `superseded_by` value is a repo-root path such as `docs/solutions/best-practices/example.md`.
|
|
543
|
+
|
|
544
|
+
- **Clear stale markers.** A Keep or Update on a doc with `status: stale` removes `status`, `stale_reason` and `stale_date` from its frontmatter. The review just showed the doc is accurate, so the marker would mislead. This is the one case where Keep writes to the file. Leave a doc with no stale marker untouched.
|
|
545
|
+
- **Stale guard.** Never overwrite `status: superseded` with `status: stale`. A superseded doc is already retired. Skip every stale-marking write for it, leave its fields unchanged, and list it in the report as superseded and left unchanged.
|
|
546
|
+
- **Retarget before removing.** Before Consolidate or Replace deletes a file, find every doc whose `superseded_by` names that file and set it to the surviving doc's repo-root path (the canonical doc for Consolidate, the new learning for Replace). Retarget first, then delete, so no pointer is ever left dangling. Remove the old or subsumed doc only after the survivor file exists and every merge, retarget and cross-reference write succeeded. If any of those failed, delete nothing, leave the pointers as they are, and list the action under Recommended with the reason; this overrides autofix's general record-and-continue rule. Name each retargeted doc in the report.
|
|
547
|
+
- **Delete cascade.** A plain Delete leaves no surviving doc, so a superseded doc pointing at the deleted file would be retired with its replacement gone. Collect every doc whose `superseded_by` names the file being deleted, then every doc that names those docs, and so on. Keep a set of paths already handled in this run and skip any path already in it, which ends cycles. The search must cover every match, so page it if the tool caps its output. Defer the whole Delete if any pointing doc must remain: a pointing doc outside the run's scope, or, in interactive mode, one the user declines to delete. Deferring means deleting nothing and listing the Delete under Recommended, naming the pointing docs that blocked it. Otherwise delete the farthest dependents first, working back toward the target, and the target last, naming each in the Delete action. If a delete fails, stop that cascade and report which files were removed and which remain. Because every remaining doc's pointer names a doc that is still present, this leaves no dangling pointer. In interactive mode, show the full list and ask the user to confirm before deleting anything. In autofix mode, delete when nothing blocks it and list the deletions under the Delete entry in the report.
|
|
548
|
+
|
|
535
549
|
## Output Format
|
|
536
550
|
|
|
537
551
|
**The full report MUST be printed as markdown output.** Do not summarize findings internally and then output a one-liner. The report is the deliverable — print every section in full, formatted as readable markdown with headers, tables, and bullet points.
|
|
@@ -558,6 +572,9 @@ Then for EVERY file processed, list:
|
|
|
558
572
|
- What evidence was found -- tag any memory-sourced findings with "(auto memory [claude])" to distinguish them from codebase-sourced evidence
|
|
559
573
|
- What action was taken (or recommended)
|
|
560
574
|
- For Consolidate: which doc was canonical, what unique content was merged, what was deleted
|
|
575
|
+
- For Consolidate and Replace: any docs whose `superseded_by` was retargeted to the surviving doc
|
|
576
|
+
- For Delete: any superseded docs deleted with it
|
|
577
|
+
- For a superseded doc skipped by the stale guard: its path, listed as superseded and left unchanged
|
|
561
578
|
|
|
562
579
|
For **Keep** outcomes, list them under a reviewed-without-edits section so the result is visible without creating git churn.
|
|
563
580
|
|
|
@@ -571,7 +588,7 @@ Split actions into two sections:
|
|
|
571
588
|
- For each **Updated** file: the file path, what references were fixed, and why
|
|
572
589
|
- For each **Consolidated** cluster: the canonical doc, what unique content was merged from each subsumed doc, and the subsumed docs that were deleted
|
|
573
590
|
- For each **Replaced** file: what the old learning recommended vs what the current code does, and the path to the new successor
|
|
574
|
-
- For each **Deleted** file: the file path
|
|
591
|
+
- For each **Deleted** file: the file path, why it was removed (problem domain gone, fully redundant, etc.), and the superseded docs deleted with it
|
|
575
592
|
- For each **Marked stale** file: the file path, what evidence was found, and why it was ambiguous
|
|
576
593
|
|
|
577
594
|
**Recommended** (actions that could not be written — e.g., permission denied):
|
|
@@ -14,7 +14,7 @@ Use for: `build_error`, `test_failure`, `runtime_error`, `performance_issue`, `d
|
|
|
14
14
|
---
|
|
15
15
|
title: [Clear problem title]
|
|
16
16
|
date: [YYYY-MM-DD]
|
|
17
|
-
category: [docs/solutions
|
|
17
|
+
category: [directory name under docs/solutions/, e.g. best-practices]
|
|
18
18
|
module: [Module or area]
|
|
19
19
|
problem_type: [schema enum]
|
|
20
20
|
component: [schema enum]
|
|
@@ -60,7 +60,7 @@ Use for: `best_practice`, `documentation_gap`, `workflow_issue`, `developer_expe
|
|
|
60
60
|
---
|
|
61
61
|
title: [Clear, descriptive title]
|
|
62
62
|
date: [YYYY-MM-DD]
|
|
63
|
-
category: [docs/solutions
|
|
63
|
+
category: [directory name under docs/solutions/, e.g. best-practices]
|
|
64
64
|
module: [Module or area]
|
|
65
65
|
problem_type: [schema enum]
|
|
66
66
|
component: [schema enum]
|