@fro.bot/systematic 3.26.3 → 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/agents/research/learnings-researcher.md +5 -0
- package/package.json +1 -1
- package/skills/ce-compound/SKILL.md +3 -3
- package/skills/ce-compound/assets/resolution-template.md +2 -2
- package/skills/ce-compound-refresh/SKILL.md +1 -1
- package/skills/ce-compound-refresh/assets/resolution-template.md +2 -2
- package/skills/compound-docs/SKILL.md +9 -9
- package/skills/compound-docs/assets/resolution-template.md +2 -2
|
@@ -193,6 +193,9 @@ Caution: <text>
|
|
|
193
193
|
#### 2. [Title]
|
|
194
194
|
...
|
|
195
195
|
|
|
196
|
+
### Overlap Assessment
|
|
197
|
+
Overlap: <repo-root path> | problem=match|no-match root_cause=match|no-match solution=match|no-match files=match|no-match prevention=match|no-match | count=N | score=High|Moderate|Low
|
|
198
|
+
|
|
196
199
|
### Recommendations
|
|
197
200
|
- [Specific actions to take based on learnings]
|
|
198
201
|
- [Patterns to follow]
|
|
@@ -202,6 +205,8 @@ Caution: <text>
|
|
|
202
205
|
[If no relevant learnings found, explicitly state this. Say so when docs/solutions/ does not exist.]
|
|
203
206
|
```
|
|
204
207
|
|
|
208
|
+
**Overlap lines.** Include the Overlap Assessment section only when the caller asks for an overlap assessment against a new doc. Write one `Overlap:` line per compared doc. Judge each of the five dimensions (problem statement, root cause, solution approach, referenced files, prevention rules) as `match` or `no-match` first, then count the matches. The score follows the count: 4-5 is High, 2-3 is Moderate, 0-1 is Low. If the score you would write disagrees with the count, the count wins.
|
|
209
|
+
|
|
205
210
|
## Efficiency Guidelines
|
|
206
211
|
|
|
207
212
|
**DO:**
|
package/package.json
CHANGED
|
@@ -95,7 +95,7 @@ Launch research subagents. Each returns text data to the orchestrator.
|
|
|
95
95
|
- **Knowledge track**: applies_when (symptoms/root_cause/resolution_type optional)
|
|
96
96
|
- Incorporates auto memory excerpts (if provided by the orchestrator) as supplementary evidence
|
|
97
97
|
- Reads `references/yaml-schema.md` for category mapping into `docs/solutions/`
|
|
98
|
-
- Suggests a filename using the pattern `[sanitized-
|
|
98
|
+
- Suggests a filename using the pattern `[sanitized-slug]-[YYYY-MM-DD].md`, where the slug is the symptom for bug-track docs and a short title of the guidance for knowledge-track docs
|
|
99
99
|
- Returns: YAML frontmatter skeleton (must include `category:` field mapped from problem_type), category directory path, suggested filename, and which track applies
|
|
100
100
|
- Does not invent enum values, categories, or frontmatter fields from memory; reads the schema and mapping files above
|
|
101
101
|
- Does not force bug-track fields onto knowledge-track learnings or vice versa
|
|
@@ -133,7 +133,7 @@ Launch research subagents. Each returns text data to the orchestrator.
|
|
|
133
133
|
- **Low**: 0-1 dimensions match — related but distinct
|
|
134
134
|
|
|
135
135
|
The score is a function of the count, not a separate judgment about how related the docs feel. Two docs on the same topic that match on one dimension score Low. When the score you are inclined to write disagrees with the count, the count wins.
|
|
136
|
-
- Returns: Links, relationships, refresh candidates, and overlap assessment.
|
|
136
|
+
- Returns: Links, relationships, refresh candidates, and overlap assessment. Ask for the overlap assessment in the dispatch and take it back as one `Overlap:` line per compared doc (the researcher's format), with the per-dimension verdicts first, then the count, then the score, in that order. Phase 2 reads the score from those lines. Two consistency checks apply in sequence and both must hold: the score follows the count, and the recommendation follows the score. High overlap means update the existing doc, so an assessment that scores High while recommending a new doc has broken the second check even if the first one held. Either break is a defect to re-derive, not a nuance to note.
|
|
137
137
|
|
|
138
138
|
**Search strategy (grep-first filtering for efficiency):**
|
|
139
139
|
|
|
@@ -164,7 +164,7 @@ Launch research subagents. Each returns text data to the orchestrator.
|
|
|
164
164
|
The orchestrating agent (main conversation) performs these steps:
|
|
165
165
|
|
|
166
166
|
1. Collect all text results from Phase 1 subagents
|
|
167
|
-
2. **Check the overlap assessment** from the Related Docs Finder before deciding what to write:
|
|
167
|
+
2. **Check the overlap assessment** from the Related Docs Finder (the `score=` value of its `Overlap:` lines) before deciding what to write:
|
|
168
168
|
|
|
169
169
|
| Overlap | Action |
|
|
170
170
|
|---------|--------|
|
|
@@ -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]
|
|
@@ -82,7 +82,7 @@ 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, 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.
|
|
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
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`.
|
|
@@ -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]
|
|
@@ -138,9 +138,9 @@ Proceed directly to Step 4 (no user interaction needed).
|
|
|
138
138
|
<step number="4" required="true" depends_on="2">
|
|
139
139
|
### Step 4: Generate Filename
|
|
140
140
|
|
|
141
|
-
Format: `[sanitized-
|
|
141
|
+
Format: `[sanitized-slug]-[YYYY-MM-DD].md`
|
|
142
142
|
|
|
143
|
-
|
|
143
|
+
The slug is the symptom for bug-track docs. Knowledge-track docs have no symptom, so the slug is a short sanitized title of the guidance.
|
|
144
144
|
|
|
145
145
|
**Sanitization rules:**
|
|
146
146
|
|
|
@@ -151,10 +151,10 @@ Bug-track docs name the file after the symptom. Knowledge-track docs have no sym
|
|
|
151
151
|
|
|
152
152
|
**Examples:**
|
|
153
153
|
|
|
154
|
-
- `n-plus-one-report-generation-
|
|
155
|
-
- `parameter-not-saving-state-
|
|
156
|
-
- `webview-crash-on-resize-
|
|
157
|
-
- `prefer-explicit-request-timeouts-
|
|
154
|
+
- `n-plus-one-report-generation-2025-11-10.md` (bug track)
|
|
155
|
+
- `parameter-not-saving-state-2025-11-10.md` (bug track)
|
|
156
|
+
- `webview-crash-on-resize-2025-11-10.md` (bug track)
|
|
157
|
+
- `prefer-explicit-request-timeouts-2025-11-10.md` (knowledge track)
|
|
158
158
|
</step>
|
|
159
159
|
|
|
160
160
|
<step number="5" required="true" depends_on="4" blocking="true">
|
|
@@ -418,7 +418,7 @@ Documentation is successful when ALL of the following are true:
|
|
|
418
418
|
- Solution: Loaded the comments for all reports in one eager-loaded query
|
|
419
419
|
- Root cause: Missing eager loading causing a separate database query per comment thread
|
|
420
420
|
3. **Check existing:** No similar issue found
|
|
421
|
-
4. **Generate filename:** `n-plus-one-report-generation-
|
|
421
|
+
4. **Generate filename:** `n-plus-one-report-generation-2025-11-10.md`
|
|
422
422
|
5. **Validate YAML:**
|
|
423
423
|
```yaml
|
|
424
424
|
module: Report Service
|
|
@@ -434,7 +434,7 @@ Documentation is successful when ALL of the following are true:
|
|
|
434
434
|
```
|
|
435
435
|
✅ Valid
|
|
436
436
|
6. **Create documentation:**
|
|
437
|
-
- `docs/solutions/performance-issues/n-plus-one-report-generation-
|
|
437
|
+
- `docs/solutions/performance-issues/n-plus-one-report-generation-2025-11-10.md`
|
|
438
438
|
7. **Cross-reference:** None needed (no similar issues)
|
|
439
439
|
|
|
440
440
|
**Output:**
|
|
@@ -443,7 +443,7 @@ Documentation is successful when ALL of the following are true:
|
|
|
443
443
|
✓ Solution documented
|
|
444
444
|
|
|
445
445
|
File created:
|
|
446
|
-
- docs/solutions/performance-issues/n-plus-one-report-generation-
|
|
446
|
+
- docs/solutions/performance-issues/n-plus-one-report-generation-2025-11-10.md
|
|
447
447
|
|
|
448
448
|
What's next?
|
|
449
449
|
1. Continue workflow (recommended)
|
|
@@ -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]
|