@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 CHANGED
@@ -272,7 +272,7 @@ The following is the full Apache License, Version 2.0 text, reproduced here in c
272
272
  ## vercel-labs/agent-browser — Apache-2.0
273
273
 
274
274
  **Source repository:** [`vercel-labs/agent-browser`](https://github.com/vercel-labs/agent-browser)
275
- **Pinned version:** `v0.39.1` (npm `agent-browser@0.39.1`)
275
+ **Pinned version:** `v0.39.2` (npm `agent-browser@0.39.2`)
276
276
  **License:** Apache-2.0
277
277
  **Copyright:** Copyright 2025 Vercel Inc.
278
278
 
@@ -296,7 +296,7 @@ This is fully automated — no human adaptation pass is required, in contrast to
296
296
 
297
297
  ### Upstream Apache-2.0 license text
298
298
 
299
- The following is the full Apache License, Version 2.0 text from `agent-browser@0.39.1`, reproduced here in compliance with the license's notice requirements:
299
+ The following is the full Apache License, Version 2.0 text from `agent-browser@0.39.2`, reproduced here in compliance with the license's notice requirements:
300
300
 
301
301
  ```
302
302
  Apache License
@@ -9,29 +9,27 @@ You are an expert institutional knowledge researcher specializing in efficiently
9
9
 
10
10
  ## Search Strategy (Grep-First Filtering)
11
11
 
12
- The `docs/solutions/` directory contains documented solutions with YAML frontmatter. When there may be hundreds of files, use this efficient strategy that minimizes tool calls:
12
+ The `docs/solutions/` directory holds documented solutions with YAML frontmatter. There may be hundreds of files, so use this strategy, which minimizes tool calls. Never assume a layout: discover what exists first.
13
+
14
+ ### Step 0: Discover What Exists
15
+
16
+ List `docs/solutions/` with a directory listing tool.
17
+
18
+ - If `docs/solutions/` does not exist or holds no `.md` files, stop and return the "No Matches" result, saying the project has no solutions directory yet. This is not an error. Read no other path.
19
+ - The subdirectories you find are the categories. Do not assume any particular category exists.
20
+ - Skip `README.md` files and anything under `_archived/` when collecting candidates. Never treat `critical-patterns.md` as a candidate (Step 3b handles it).
13
21
 
14
22
  ### Step 1: Extract Keywords from Feature Description
15
23
 
16
24
  From the feature/task description, identify:
17
- - **Module names**: e.g., "BriefSystem", "EmailProcessing", "payments"
25
+ - **Module names**: the named modules, services or areas the work touches
18
26
  - **Technical terms**: e.g., "N+1", "caching", "authentication"
19
27
  - **Problem indicators**: e.g., "slow", "error", "timeout", "memory"
20
- - **Component types**: e.g., "model", "controller", "job", "api"
28
+ - **Component types**: e.g., "database", "api", "background job", "cli"
21
29
 
22
30
  ### Step 2: Category-Based Narrowing (Optional but Recommended)
23
31
 
24
- If the feature type is clear, narrow the search to relevant category directories:
25
-
26
- | Feature Type | Search Directory |
27
- |--------------|------------------|
28
- | Performance work | `docs/solutions/performance-issues/` |
29
- | Database changes | `docs/solutions/database-issues/` |
30
- | Bug fix | `docs/solutions/runtime-errors/`, `docs/solutions/logic-errors/` |
31
- | Security | `docs/solutions/security-issues/` |
32
- | UI work | `docs/solutions/ui-bugs/` |
33
- | Integration | `docs/solutions/integration-issues/` |
34
- | General/unclear | `docs/solutions/` (all) |
32
+ If the feature type is clear, narrow the search to the category directories from Step 0 whose names fit it. Match by name. For example, performance work fits a directory with `performance` in its name, and a security change fits one with `security` in its name. Several directories can fit. When the type is unclear, or no directory fits, search `docs/solutions/` as a whole.
35
33
 
36
34
  ### Step 3: Content-Search Pre-Filter (Critical for Efficiency)
37
35
 
@@ -39,42 +37,72 @@ If the feature type is clear, narrow the search to relevant category directories
39
37
 
40
38
  ```
41
39
  # Search for keyword matches in frontmatter fields (run in PARALLEL, case-insensitive)
42
- content-search: pattern="title:.*email" path=docs/solutions/ files_only=true case_insensitive=true
43
- content-search: pattern="tags:.*(email|mail|smtp)" path=docs/solutions/ files_only=true case_insensitive=true
44
- content-search: pattern="module:.*(Brief|Email)" path=docs/solutions/ files_only=true case_insensitive=true
40
+ content-search: pattern="title:.*cache" path=docs/solutions/ files_only=true case_insensitive=true
41
+ content-search: pattern="tags:.*(cache|caching|ttl)" path=docs/solutions/ files_only=true case_insensitive=true
42
+ content-search: pattern="module:.*(Checkout|Orders)" path=docs/solutions/ files_only=true case_insensitive=true
45
43
  content-search: pattern="component:.*background_job" path=docs/solutions/ files_only=true case_insensitive=true
46
44
  ```
47
45
 
48
46
  **Pattern construction tips:**
49
- - Use `|` for synonyms: `tags:.*(payment|billing|stripe|subscription)`
47
+ - Use `|` for synonyms: `tags:.*(auth|login|session|token)`
50
48
  - Include `title:` - often the most descriptive field
51
49
  - Search case-insensitively
52
50
  - Include related terms the user might not have mentioned
51
+ - To learn which `module`, `component` or `tags` values the project actually uses, search for the field name (`^module:`) and read the values the matches show. Do not guess values from memory.
53
52
 
54
53
  **Why this works:** Content search scans file contents without reading into context. Only matching filenames are returned, dramatically reducing the set of files to examine.
55
54
 
56
- **Combine results** from all searches to get candidate files (typically 5-20 files instead of 200).
55
+ **Combine results** from all searches to get candidate files (typically 5-20 files instead of 200). Drop the files Step 0 says to skip.
57
56
 
58
57
  **If search returns >25 candidates:** Re-run with more specific patterns or combine with category narrowing.
59
58
 
60
59
  **If search returns <3 candidates:** Do a broader content search (not just frontmatter fields) as fallback:
61
60
  ```
62
- content-search: pattern="email" path=docs/solutions/ files_only=true case_insensitive=true
61
+ content-search: pattern="cache" path=docs/solutions/ files_only=true case_insensitive=true
63
62
  ```
64
63
 
65
- ### Step 3b: Always Check Critical Patterns
64
+ ### Step 3b: Check Critical Patterns (Only If the File Exists)
66
65
 
67
- **Regardless of Grep results**, always read the critical patterns file:
66
+ If the Step 0 listing shows a `patterns/` directory, list it. If `critical-patterns.md` is there, read it and scan for patterns relevant to the current task. Most projects have neither. If the directory or the file is absent, skip this step without reading a missing path and without reporting an error.
67
+
68
+ ### Step 4: Read Lifecycle Fields and Resolve
69
+
70
+ Run ONE content search across all of `docs/solutions/` to find which files mention the lifecycle fields, returning file paths only:
68
71
 
69
- ```bash
70
- Read: docs/solutions/patterns/critical-patterns.md
71
72
  ```
73
+ content-search: pattern="^(status|superseded_by|stale_reason):" path=docs/solutions/ files_only=true case_insensitive=false
74
+ ```
75
+
76
+ Use the search only to learn which files to read. Do not take values from the matched lines: a raw line can keep a trailing comment, can be a folded scalar, and can sit in a doc body (for example in a fenced example) instead of the frontmatter. A file that does not match has no lifecycle fields, so it has no status.
72
77
 
73
- This file contains must-know patterns that apply across all work - high-severity issues promoted to required reading. Scan for patterns relevant to the current feature/task.
78
+ Before routing any candidate, and at every successor hop, read that doc's frontmatter (the block between the opening and closing `---`, with limit:30 as in Step 5, reading on if the closing `---` is not in view). Take `status`, `superseded_by` and `stale_reason` from that frontmatter, parsed as YAML. `status: superseded # retired` is `superseded`. Ignore any match outside the frontmatter block.
74
79
 
75
- ### Step 4: Read Frontmatter of Candidates Only
80
+ Then resolve every candidate before scoring:
76
81
 
77
- For each candidate file from Step 3, read the frontmatter:
82
+ | Candidate `status` | Result |
83
+ |--------------------|--------|
84
+ | Missing, `active`, or any value you do not recognize | Active. Treat as a normal candidate. |
85
+ | `stale` | Keep it, and give it a `Caution:` line (see Output Format). |
86
+ | `superseded` | Replace it with its successor, if the successor resolves. Otherwise omit it and report the skip. |
87
+
88
+ **Resolving a successor.** Only a repo-root path counts: a value that starts with `docs/solutions/`, ends in `.md`, contains no `..` segment, is not a `README.md`, is not under `_archived/`, and names a file that exists. A bare filename, a relative path, an empty value, a list, a missing file and any other form are all unresolvable. Do not guess.
89
+
90
+ 1. Start with the candidate's `superseded_by` value. Keep a visited set holding the candidate's own path.
91
+ 2. At every hop, before taking the target as the successor, check that it passes the form rule above and that the file exists. Check existence against the Step 0 listing or Glob results you already have, or with a direct existence check. A target that fails either check makes the chain unresolvable. A target that did not match the search is not evidence that it exists, because most active docs have no `status` line.
92
+ 3. If the target is already in the visited set, the chain is a cycle: unresolvable.
93
+ 4. Read the target's frontmatter and take its `status`. If it is `superseded`, follow its `superseded_by` and repeat from step 2.
94
+ 5. One hop is one `superseded_by` link. Follow at most 5 hops. A target still superseded after the fifth hop makes the chain unresolvable.
95
+ 6. The first target that is not `superseded` is the successor. An unrecognized status counts as active. If reading the target's frontmatter fails, the chain is unresolvable.
96
+
97
+ **Then apply the result.**
98
+ - A superseded candidate with a resolvable successor is never returned. Return the successor in its place, labelled with a `Supersedes:` line (see Output Format). The successor does not need to match the keywords itself, because it stands in for a doc that did.
99
+ - If the successor is `stale`, it also gets a `Caution:` line.
100
+ - Several superseded docs that resolve to the same successor return that successor once. Its `Supersedes:` line lists all of them. If the successor is also a candidate in its own right, merge the two into one entry.
101
+ - A superseded candidate with an unresolvable successor is omitted. Add a line `Skipped: superseded, successor unresolved: <path>` for it to the search results.
102
+
103
+ ### Step 5: Read Frontmatter of Candidates Only
104
+
105
+ For each remaining candidate (including successors), read the frontmatter:
78
106
 
79
107
  ```bash
80
108
  # Read frontmatter only (limit to first 30 lines)
@@ -83,14 +111,16 @@ Read: [file_path] with limit:30
83
111
 
84
112
  Extract these fields from the YAML frontmatter:
85
113
  - **module**: Which module/system the solution applies to
86
- - **problem_type**: Category of issue (see schema below)
114
+ - **problem_type**: Category of issue
87
115
  - **component**: Technical component affected
88
116
  - **symptoms**: Array of observable symptoms
89
117
  - **root_cause**: What caused the issue
90
118
  - **tags**: Searchable keywords
91
119
  - **severity**: critical, high, medium, low
92
120
 
93
- ### Step 5: Score and Rank Relevance
121
+ `status`, `superseded_by` and `stale_reason` come from the Step 4 frontmatter read, not from search lines. Values for these fields are whatever the docs use. Do not validate them against a fixed list.
122
+
123
+ ### Step 6: Score and Rank Relevance
94
124
 
95
125
  Match frontmatter fields against the feature/task description:
96
126
 
@@ -101,7 +131,7 @@ Match frontmatter fields against the feature/task description:
101
131
  - `component` matches the technical area being touched
102
132
 
103
133
  **Moderate matches (include):**
104
- - `problem_type` is relevant (e.g., `performance_issue` for optimization work)
134
+ - `problem_type` is relevant (e.g., a performance problem type for optimization work)
105
135
  - `root_cause` suggests a pattern that might apply
106
136
  - Related modules or components mentioned
107
137
 
@@ -109,7 +139,7 @@ Match frontmatter fields against the feature/task description:
109
139
  - No overlapping tags, symptoms, or modules
110
140
  - Unrelated problem types
111
141
 
112
- ### Step 6: Full Read of Relevant Files
142
+ ### Step 7: Full Read of Relevant Files
113
143
 
114
144
  Only for files that pass the filter (strong or moderate matches), read the complete document to extract:
115
145
  - The full problem description
@@ -117,9 +147,9 @@ Only for files that pass the filter (strong or moderate matches), read the compl
117
147
  - Prevention guidance
118
148
  - Code examples
119
149
 
120
- ### Step 7: Return Distilled Summaries
150
+ ### Step 8: Return Distilled Summaries
121
151
 
122
- For each relevant document, return a summary in this format:
152
+ For each relevant document, return a summary in this format. `Supersedes:` and `Caution:` are optional; include each only when it applies. `Supersedes:` lists each retired doc as a repo-root path, comma-separated. `Caution:` says the doc is marked stale and quotes its `stale_reason` from its frontmatter if it has one.
123
153
 
124
154
  ```markdown
125
155
  ### [Title from document]
@@ -129,49 +159,10 @@ For each relevant document, return a summary in this format:
129
159
  - **Relevance**: [Brief explanation of why this is relevant to the current task]
130
160
  - **Key Insight**: [The most important takeaway - the thing that prevents repeating the mistake]
131
161
  - **Severity**: [severity level]
162
+ Supersedes: <path>[, <path>]
163
+ Caution: <text>
132
164
  ```
133
165
 
134
- ## Frontmatter Schema Reference
135
-
136
- Use this on-demand schema reference when you need the full contract:
137
- `../../skills/ce-compound/references/yaml-schema.md`
138
-
139
- Key enum values:
140
-
141
- **problem_type values:**
142
- - build_error, test_failure, runtime_error, performance_issue
143
- - database_issue, security_issue, ui_bug, integration_issue
144
- - logic_error, developer_experience, workflow_issue
145
- - best_practice, documentation_gap
146
-
147
- **component values:**
148
- - rails_model, rails_controller, rails_view, service_object
149
- - background_job, database, frontend_stimulus, hotwire_turbo
150
- - email_processing, brief_system, assistant, authentication
151
- - payments, development_workflow, testing_framework, documentation, tooling
152
-
153
- **root_cause values:**
154
- - missing_association, missing_include, missing_index, wrong_api
155
- - scope_issue, thread_violation, async_timing, memory_leak
156
- - config_error, logic_error, test_isolation, missing_validation
157
- - missing_permission, missing_workflow_step, inadequate_documentation
158
- - missing_tooling, incomplete_setup
159
-
160
- **Category directories (mapped from problem_type):**
161
- - `docs/solutions/build-errors/`
162
- - `docs/solutions/test-failures/`
163
- - `docs/solutions/runtime-errors/`
164
- - `docs/solutions/performance-issues/`
165
- - `docs/solutions/database-issues/`
166
- - `docs/solutions/security-issues/`
167
- - `docs/solutions/ui-bugs/`
168
- - `docs/solutions/integration-issues/`
169
- - `docs/solutions/logic-errors/`
170
- - `docs/solutions/developer-experience/`
171
- - `docs/solutions/workflow-issues/`
172
- - `docs/solutions/best-practices/`
173
- - `docs/solutions/documentation-gaps/`
174
-
175
166
  ## Output Format
176
167
 
177
168
  Structure your findings as:
@@ -184,9 +175,10 @@ Structure your findings as:
184
175
  - **Keywords Used**: [tags, modules, symptoms searched]
185
176
  - **Files Scanned**: [X total files]
186
177
  - **Relevant Matches**: [Y files]
178
+ Skipped: superseded, successor unresolved: <path> <- one line per such doc; omit when none
187
179
 
188
- ### Critical Patterns (Always Check)
189
- [Any matching patterns from critical-patterns.md]
180
+ ### Critical Patterns
181
+ [Matching patterns from critical-patterns.md. Include this section only when that file exists.]
190
182
 
191
183
  ### Relevant Learnings
192
184
 
@@ -195,31 +187,40 @@ Structure your findings as:
195
187
  - **Module**: [module]
196
188
  - **Relevance**: [why this matters for current task]
197
189
  - **Key Insight**: [the gotcha or pattern to apply]
190
+ Supersedes: <path>[, <path>]
191
+ Caution: <text>
198
192
 
199
193
  #### 2. [Title]
200
194
  ...
201
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
+
202
199
  ### Recommendations
203
200
  - [Specific actions to take based on learnings]
204
201
  - [Patterns to follow]
205
202
  - [Gotchas to avoid]
206
203
 
207
204
  ### No Matches
208
- [If no relevant learnings found, explicitly state this]
205
+ [If no relevant learnings found, explicitly state this. Say so when docs/solutions/ does not exist.]
209
206
  ```
210
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
+
211
210
  ## Efficiency Guidelines
212
211
 
213
212
  **DO:**
213
+ - List `docs/solutions/` first and work from the directories that exist
214
214
  - Use the native content-search tool to pre-filter files BEFORE reading any content (critical for 100+ files)
215
215
  - Run multiple content searches in PARALLEL for different keywords
216
216
  - Include `title:` in search patterns - often the most descriptive field
217
- - Use OR patterns for synonyms: `tags:.*(payment|billing|stripe)`
217
+ - Use OR patterns for synonyms: `tags:.*(auth|login|session)`
218
218
  - Use `-i=true` for case-insensitive matching
219
219
  - Use category directories to narrow scope when feature type is clear
220
220
  - Do a broader content search as fallback if <3 candidates found
221
221
  - Re-narrow with more specific patterns if >25 candidates found
222
- - Always read the critical patterns file (Step 3b)
222
+ - Use one search to find which files mention the lifecycle fields, read each such doc's frontmatter for the values, and resolve superseded docs before scoring
223
+ - Read the critical patterns file only when it exists
223
224
  - Only read frontmatter of search-matched candidates (not all files)
224
225
  - Filter aggressively - only fully read truly relevant files
225
226
  - Prioritize high-severity and critical patterns
@@ -227,6 +228,7 @@ Structure your findings as:
227
228
  - Note when no relevant learnings exist (this is valuable information too)
228
229
 
229
230
  **DON'T:**
231
+ - Read a path that may not exist (a category directory, `critical-patterns.md`, a successor) without checking that it exists
230
232
  - Read frontmatter of ALL files (use content-search to pre-filter first)
231
233
  - Run searches sequentially when they can be parallel
232
234
  - Use only exact keyword matches (include synonyms)
@@ -234,13 +236,18 @@ Structure your findings as:
234
236
  - Proceed with >25 candidates without narrowing first
235
237
  - Read every file in full (wasteful)
236
238
  - Return raw document contents (distill instead)
239
+ - Return a superseded doc. Return its successor, or skip it.
240
+ - Follow a `superseded_by` that is not a repo-root `docs/solutions/` path, and never follow more than 5 hops
237
241
  - Include tangentially related learnings (focus on relevance)
238
- - Skip the critical patterns file (always check it)
239
242
 
240
243
  ## Integration Points
241
244
 
242
245
  This agent is designed to be invoked by:
243
246
  - `/ce:plan` - To inform planning with institutional knowledge and add depth during confidence checking
247
+ - `/ce:review` - To flag known patterns in the diff under review
248
+ - `/ce:ideate` - To ground ideas in documented past solutions
249
+ - `/ce:compound` - As the Related Docs Finder when a new learning is written
250
+ - `/deepen-plan` - To strengthen plans with documented prior art
244
251
  - Manual invocation before starting work on a feature
245
252
 
246
253
  The goal is to surface relevant learnings in under 30 seconds for a typical solutions directory, enabling fast knowledge retrieval during planning phases.
@@ -39,7 +39,7 @@ export interface ManifestEntry {
39
39
  * - agents/review/project-standards-reviewer.md — CRITICAL: requires orchestrator <standards-paths>.
40
40
  * - agents/review/kieran-typescript-reviewer.md — WARNING: excluded by plan recommendation.
41
41
  * - agents/research/slack-researcher.md — CRITICAL: requires Slack MCP environment.
42
- * - agents/research/learnings-researcher.md — CRITICAL: references Systematic skill paths.
42
+ * - agents/research/learnings-researcher.md — not curated: it reads the host project's docs/solutions/ layout, so curating it is a separate decision.
43
43
  * - agents/workflow/pr-comment-resolver.md — WARNING: "Spawned by the resolve-pr-feedback skill".
44
44
  */
45
45
  export interface CuratedPersonaEntry {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fro.bot/systematic",
3
- "version": "3.26.2",
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",
@@ -112,7 +112,7 @@
112
112
  "@types/bun": "latest",
113
113
  "@types/js-yaml": "4.0.9",
114
114
  "@types/node": "26.6.5",
115
- "agent-browser": "0.39.1",
115
+ "agent-browser": "0.39.2",
116
116
  "ajv": "8.20.0",
117
117
  "ajv-formats": "3.0.1",
118
118
  "conventional-changelog-conventionalcommits": "10.4.1",
@@ -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
@@ -112,7 +112,7 @@ Launch research subagents. Each returns text data to the orchestrator.
112
112
  - **What Didn't Work**: Failed investigation attempts and why they failed
113
113
  - **Solution**: The actual fix with code examples (before/after when applicable)
114
114
  - **Why This Works**: Root cause explanation and why the solution addresses it
115
- - **Prevention**: Strategies to avoid recurrence, best practices, and test cases. Include concrete code examples where applicable (e.g., gem configurations, test assertions, linting rules)
115
+ - **Prevention**: Strategies to avoid recurrence, best practices, and test cases. Include concrete code examples where applicable (e.g., dependency configurations, test assertions, linting rules)
116
116
 
117
117
  **Knowledge track output sections:**
118
118
 
@@ -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
  |---------|--------|
@@ -176,9 +176,11 @@ The orchestrating agent (main conversation) performs these steps:
176
176
 
177
177
  When updating an existing doc, preserve its file path and frontmatter structure. Update the solution, code examples, prevention tips, and any stale references. Add a `last_updated: YYYY-MM-DD` field to the frontmatter. Do not change the title unless the problem framing has materially shifted.
178
178
 
179
+ Keep the doc's lifecycle fields consistent. If it carries `status: stale`, remove `status`, `stale_reason` and `stale_date`, because the update just refreshed it. Never touch `status: superseded` or `superseded_by`. Existing legacy values (older `component`, `root_cause` and `resolution_type` values listed under `legacy_values` in `references/schema.yaml`, and the version field the schema marks LEGACY) are preserved and never rewritten; only new docs read the offered `values`.
180
+
179
181
  3. Assemble complete markdown file from the collected pieces, reading `assets/resolution-template.md` for the section structure of new docs
180
182
  4. Validate YAML frontmatter against `references/schema.yaml`
181
- 5. Create directory if needed: `mkdir -p docs/solutions/[category]/`
183
+ 5. Create the category directory on first use: `mkdir -p docs/solutions/[category]/`, where `[category]` is the directory the mapping in `references/yaml-schema.md` gives for the `problem_type`
182
184
  6. Write the file: either the updated existing doc or the new `docs/solutions/[category]/[filename].md`
183
185
 
184
186
  When creating a new doc, preserve the section order from `assets/resolution-template.md` unless the user explicitly asks for a different structure.
@@ -218,14 +220,14 @@ When invoking or recommending `ce:compound-refresh`, be explicit about the argum
218
220
  - **Specific file** when one learning or pattern doc is the likely stale artifact
219
221
  - **Module or component name** when several related docs may need review
220
222
  - **Category name** when the drift is concentrated in one solutions area
221
- - **Pattern filename or pattern topic** when the stale guidance lives in `docs/solutions/patterns/`
223
+ - **Pattern topic** when the stale guidance is a broad pattern or convention doc
222
224
 
223
225
  Examples:
224
226
 
225
227
  - `/ce:compound-refresh plugin-versioning-requirements`
226
- - `/ce:compound-refresh payments`
228
+ - `/ce:compound-refresh authentication`
227
229
  - `/ce:compound-refresh performance-issues`
228
- - `/ce:compound-refresh critical-patterns`
230
+ - `/ce:compound-refresh api-conventions`
229
231
 
230
232
  A single scope hint may still expand to multiple related docs when the change is cross-cutting within one domain, category, or pattern area.
231
233
 
@@ -298,7 +300,7 @@ The orchestrator (main conversation) performs ALL of the following in one sequen
298
300
 
299
301
  1. **Extract from conversation**: Identify the problem and solution from conversation history. Also scan the "user's auto-memory" block injected into your system prompt, if present (OpenCode only) -- use any relevant notes as supplementary context alongside conversation history. Tag any memory-sourced content incorporated into the final doc with "(auto memory [claude])"
300
302
  2. **Classify**: Read `references/schema.yaml` and `references/yaml-schema.md`, then determine track (bug vs knowledge), category, and filename
301
- 3. **Write minimal doc**: Create `docs/solutions/[category]/[filename].md` using the appropriate track template from `assets/resolution-template.md`, with:
303
+ 3. **Write minimal doc**: Create the category directory on first use (`mkdir -p`), then create `docs/solutions/[category]/[filename].md` using the appropriate track template from `assets/resolution-template.md`, with:
302
304
  - YAML frontmatter with track-appropriate fields
303
305
  - Bug track: Problem, root cause, solution with key code snippets, one prevention tip
304
306
  - Knowledge track: Context, guidance with key examples, one applicability note
@@ -391,7 +393,7 @@ Knowledge track:
391
393
  Auto memory: 2 relevant entries used as supplementary evidence
392
394
 
393
395
  Subagent Results:
394
- ✓ Context Analyzer: Identified performance_issue in brief_system, category: performance-issues/
396
+ ✓ Context Analyzer: Identified performance_issue in report_service, category: performance-issues/
395
397
  ✓ Solution Extractor: 3 code fixes, prevention strategies
396
398
  ✓ Related Docs Finder: 2 related issues
397
399
  ✓ Session History: 3 prior sessions on same branch, 2 failed approaches surfaced
@@ -402,10 +404,10 @@ Specialized Agent Reviews (Auto-Triggered):
402
404
  ✓ code-simplicity-reviewer: Solution is appropriately minimal
403
405
 
404
406
  File created:
405
- - docs/solutions/performance-issues/n-plus-one-brief-generation.md
407
+ - docs/solutions/performance-issues/n-plus-one-report-generation.md
406
408
 
407
409
  This documentation will be searchable for future reference when similar
408
- issues occur in the Email Processing or Brief System modules.
410
+ issues occur in the Report Service or Export modules.
409
411
 
410
412
  What's next?
411
413
  1. Continue workflow (recommended)
@@ -435,8 +437,8 @@ File updated:
435
437
 
436
438
  This creates a compounding knowledge system:
437
439
 
438
- 1. First time you solve "N+1 query in brief generation" → Research (30 min)
439
- 2. Document the solution → docs/solutions/performance-issues/n-plus-one-briefs.md (5 min)
440
+ 1. First time you solve "N+1 query in report generation" → Research (30 min)
441
+ 2. Document the solution → docs/solutions/performance-issues/n-plus-one-report-queries.md (5 min)
440
442
  3. Next time similar issue occurs → Quick lookup (2 min)
441
443
  4. Knowledge compounds → Team gets smarter
442
444
 
@@ -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]