@fro.bot/systematic 3.26.2 → 3.26.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/ATTRIBUTIONS.md +2 -2
- package/agents/research/learnings-researcher.md +82 -80
- package/dist/lib/pi-subagents-personas.d.ts +1 -1
- package/package.json +2 -2
- package/skills/ce-compound/SKILL.md +13 -11
- package/skills/ce-compound/references/schema.yaml +99 -15
- package/skills/ce-compound/references/yaml-schema.md +36 -7
- package/skills/ce-compound-refresh/SKILL.md +33 -16
- package/skills/ce-compound-refresh/references/schema.yaml +99 -15
- package/skills/ce-compound-refresh/references/yaml-schema.md +36 -7
- package/skills/ce-review/SKILL.md +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
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.
|
|
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.
|
|
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
|
|
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**:
|
|
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., "
|
|
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
|
|
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:.*
|
|
43
|
-
content-search: pattern="tags:.*(
|
|
44
|
-
content-search: pattern="module:.*(
|
|
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:.*(
|
|
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="
|
|
61
|
+
content-search: pattern="cache" path=docs/solutions/ files_only=true case_insensitive=true
|
|
63
62
|
```
|
|
64
63
|
|
|
65
|
-
### Step 3b:
|
|
64
|
+
### Step 3b: Check Critical Patterns (Only If the File Exists)
|
|
66
65
|
|
|
67
|
-
|
|
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.
|
|
68
67
|
|
|
69
|
-
|
|
70
|
-
|
|
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:
|
|
71
|
+
|
|
72
|
+
```
|
|
73
|
+
content-search: pattern="^(status|superseded_by|stale_reason):" path=docs/solutions/ files_only=true case_insensitive=false
|
|
71
74
|
```
|
|
72
75
|
|
|
73
|
-
|
|
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.
|
|
74
77
|
|
|
75
|
-
|
|
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.
|
|
76
79
|
|
|
77
|
-
|
|
80
|
+
Then resolve every candidate before scoring:
|
|
81
|
+
|
|
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
|
|
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
|
-
|
|
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.,
|
|
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
|
|
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
|
|
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
|
|
189
|
-
[
|
|
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,6 +187,8 @@ 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
|
...
|
|
@@ -205,21 +199,23 @@ Structure your findings as:
|
|
|
205
199
|
- [Gotchas to avoid]
|
|
206
200
|
|
|
207
201
|
### No Matches
|
|
208
|
-
[If no relevant learnings found, explicitly state this]
|
|
202
|
+
[If no relevant learnings found, explicitly state this. Say so when docs/solutions/ does not exist.]
|
|
209
203
|
```
|
|
210
204
|
|
|
211
205
|
## Efficiency Guidelines
|
|
212
206
|
|
|
213
207
|
**DO:**
|
|
208
|
+
- List `docs/solutions/` first and work from the directories that exist
|
|
214
209
|
- Use the native content-search tool to pre-filter files BEFORE reading any content (critical for 100+ files)
|
|
215
210
|
- Run multiple content searches in PARALLEL for different keywords
|
|
216
211
|
- Include `title:` in search patterns - often the most descriptive field
|
|
217
|
-
- Use OR patterns for synonyms: `tags:.*(
|
|
212
|
+
- Use OR patterns for synonyms: `tags:.*(auth|login|session)`
|
|
218
213
|
- Use `-i=true` for case-insensitive matching
|
|
219
214
|
- Use category directories to narrow scope when feature type is clear
|
|
220
215
|
- Do a broader content search as fallback if <3 candidates found
|
|
221
216
|
- Re-narrow with more specific patterns if >25 candidates found
|
|
222
|
-
-
|
|
217
|
+
- 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
|
|
218
|
+
- Read the critical patterns file only when it exists
|
|
223
219
|
- Only read frontmatter of search-matched candidates (not all files)
|
|
224
220
|
- Filter aggressively - only fully read truly relevant files
|
|
225
221
|
- Prioritize high-severity and critical patterns
|
|
@@ -227,6 +223,7 @@ Structure your findings as:
|
|
|
227
223
|
- Note when no relevant learnings exist (this is valuable information too)
|
|
228
224
|
|
|
229
225
|
**DON'T:**
|
|
226
|
+
- Read a path that may not exist (a category directory, `critical-patterns.md`, a successor) without checking that it exists
|
|
230
227
|
- Read frontmatter of ALL files (use content-search to pre-filter first)
|
|
231
228
|
- Run searches sequentially when they can be parallel
|
|
232
229
|
- Use only exact keyword matches (include synonyms)
|
|
@@ -234,13 +231,18 @@ Structure your findings as:
|
|
|
234
231
|
- Proceed with >25 candidates without narrowing first
|
|
235
232
|
- Read every file in full (wasteful)
|
|
236
233
|
- Return raw document contents (distill instead)
|
|
234
|
+
- Return a superseded doc. Return its successor, or skip it.
|
|
235
|
+
- Follow a `superseded_by` that is not a repo-root `docs/solutions/` path, and never follow more than 5 hops
|
|
237
236
|
- Include tangentially related learnings (focus on relevance)
|
|
238
|
-
- Skip the critical patterns file (always check it)
|
|
239
237
|
|
|
240
238
|
## Integration Points
|
|
241
239
|
|
|
242
240
|
This agent is designed to be invoked by:
|
|
243
241
|
- `/ce:plan` - To inform planning with institutional knowledge and add depth during confidence checking
|
|
242
|
+
- `/ce:review` - To flag known patterns in the diff under review
|
|
243
|
+
- `/ce:ideate` - To ground ideas in documented past solutions
|
|
244
|
+
- `/ce:compound` - As the Related Docs Finder when a new learning is written
|
|
245
|
+
- `/deepen-plan` - To strengthen plans with documented prior art
|
|
244
246
|
- Manual invocation before starting work on a feature
|
|
245
247
|
|
|
246
248
|
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 —
|
|
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.
|
|
3
|
+
"version": "3.26.3",
|
|
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.
|
|
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",
|
|
@@ -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.,
|
|
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
|
|
|
@@ -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
|
|
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
|
|
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
|
|
228
|
+
- `/ce:compound-refresh authentication`
|
|
227
229
|
- `/ce:compound-refresh performance-issues`
|
|
228
|
-
- `/ce:compound-refresh
|
|
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
|
|
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-
|
|
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
|
|
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
|
|
439
|
-
2. Document the solution → docs/solutions/performance-issues/n-plus-one-
|
|
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
|
|
|
@@ -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
|