@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.
@@ -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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fro.bot/systematic",
3
- "version": "3.26.3",
3
+ "version": "3.26.4",
4
4
  "description": "Compound-engineering loops for OpenCode, Pi, and Claude Code",
5
5
  "type": "module",
6
6
  "homepage": "https://fro.bot/systematic",
@@ -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-problem-slug]-[date].md`
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. State the per-dimension verdicts, then the resulting count, then the score, in that order. 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.
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 subdirectory]
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 subdirectory]
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. When in doubt between Keep and Delete, ask the user (in interactive mode) or mark as stale (in autofix mode). But missing referenced files with no matching code is **not** a doubt case — it is strong, unambiguous Delete evidence. Auto-delete it.
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 subdirectory]
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 subdirectory]
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-symptom-or-title]-[module]-[YYYYMMDD].md`
141
+ Format: `[sanitized-slug]-[YYYY-MM-DD].md`
142
142
 
143
- Bug-track docs name the file after the symptom. Knowledge-track docs have no symptom, so they use a short sanitized title of the guidance.
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-ReportService-20251110.md` (bug track)
155
- - `parameter-not-saving-state-Checkout-20251110.md` (bug track)
156
- - `webview-crash-on-resize-Assistant-20251110.md` (bug track)
157
- - `prefer-explicit-request-timeouts-HttpClient-20251110.md` (knowledge track)
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-ReportService-20251110.md`
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-ReportService-20251110.md`
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-ReportService-20251110.md
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 subdirectory]
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 subdirectory]
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]