@fro.bot/systematic 3.28.1 → 3.29.0
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/HARNESSES.md +11 -8
- package/agents/research/learnings-researcher.md +76 -53
- package/dist/cli.js +14 -9
- package/dist/{index-9chxhh5j.js → index-e467g4b6.js} +204 -84
- package/dist/index.js +1 -1
- package/dist/lib/search-core.d.ts +39 -21
- package/dist/lib/search-corpus.d.ts +25 -4
- package/dist/lib/search-render.d.ts +23 -4
- package/dist/lib/search-tool.d.ts +2 -1
- package/dist/pi.js +205 -85
- package/package.json +1 -1
- package/skills/ce-brainstorm/SKILL.md +6 -2
- package/skills/ce-ideate/SKILL.md +5 -2
- package/skills/ce-plan/SKILL.md +10 -5
- package/skills/ce-plan/references/deepening-workflow.md +3 -1
- package/skills/ce-plan/references/plan-sections.md +4 -2
- package/skills/deepen-plan/SKILL.md +3 -1
package/HARNESSES.md
CHANGED
|
@@ -14,7 +14,7 @@ The five capability rows use the vocabulary in the [OpenCode profile](skills/usi
|
|
|
14
14
|
| Blocking user interaction | `question` on v1 [OC-2] and v2 [OC2-PROFILE] | No native blocking tool; numbered-chat fallback [PI-2] | `AskUserQuestion` [CC-2] | `request_user_input`; blocking and root-thread-only [CX-1][CX-2] | `ask_user`; pauses until answers [GE-1][GE-2] | No dedicated tool name verified; plan-mode clarification and `--no-ask-user` are documented [GH-3][GH-4] |
|
|
15
15
|
| Task tracking | `todowrite` on v1 [OC-3]; on v2 only when the experimental `todo` option is on [OC2-TODO] | No native mechanism; visible list fallback [PI-2] | `TodoWrite` is deprecated/disabled by default; `TaskCreate`/`TaskGet`/`TaskList`/`TaskUpdate` replace it [CC-3][CC-4] | **UNVERIFIED** [U] | **UNVERIFIED** [U] | No `TodoWrite` equivalent verified; cloud-agent tasks/sessions API is documented [GH-5] |
|
|
16
16
|
| Skill loading | Skills become commands and `systematic_skill` is registered [OC-4][OC-5]; v2 also registers each skill with the host's own `skill` tool [OC2-SKILL] | `systematic_skill` adapter and Pi-native activation [PI-3][PI-4] | Native Skill tool with `SKILL.md` discovery (`~/.claude/skills/`, `.claude/skills/`, plugin `skills/`); Systematic ships no `systematic_skill` tool on Claude Code [CC-5][CC-6][CC-9] | **UNVERIFIED** [U] | **UNVERIFIED** [U] | `SKILL.md` skills [GH-6] |
|
|
17
|
-
| Durable-output search | v1 and v2: `systematic_search` over
|
|
17
|
+
| Durable-output search | v1 and v2: `systematic_search` over solutions, plans, brainstorms and ideation docs (`kind`: `solution`, `plan`, `brainstorm`, `ideation` or `all`) [SR-1][SR-2][SR-5] | `systematic_search` with the same kinds, also handed to the built-in read-only delegates [SR-1][SR-5] | `systematic-search` bin in the plugin's `bin/`; user-level config only [SR-3] | None (no Systematic adapter) | None (no Systematic adapter) | None (no Systematic adapter) |
|
|
18
18
|
| Skills-file support | `SKILL.md` is loaded by the Systematic skill path [OC-4] | `pi.skills` ships `./skills`, including `SKILL.md` discovery [PI-4][PI-5] | `SKILL.md` and `.claude/skills/`; the plugin bundle is built and identifier-translated in CI from `skills/`, never committed [CC-5][CC-6][CC-9] | **UNVERIFIED** [U] | **UNVERIFIED** [U] | `SKILL.md` [GH-6] |
|
|
19
19
|
|
|
20
20
|
`[U]` means the capability was not checked in the supplied research pack. It is not a claim that the capability does not exist.
|
|
@@ -56,7 +56,7 @@ Pi's profile records degraded or unavailable native capabilities and explicit fa
|
|
|
56
56
|
|
|
57
57
|
Optional mature delegation is available via [pi-subagents](https://github.com/tintinweb/pi-subagents). It is outside Systematic's bounded-delegate guarantees and governed by pi-subagents' own configuration. Tested against pi-subagents 0.22.0 on Pi 1.3.0; versions outside the tested range are unsupported but nonfatal. pi-subagents reaches Systematic's personas by two paths:
|
|
58
58
|
|
|
59
|
-
- **Installed package.** The package declares `pi.subagents.agents` at `package.json:24-28`, pointing at `dist/pi-subagents/agents/`. `scripts/build-pi-package-agents.ts` writes that directory at build time from the same render the export uses, so the 29 curated personas it ships are byte-equal to the committed fixtures (`tests/unit/package-exports.test.ts:289-344`) [PI-7]. pi-subagents 0.22 is the first release that reads package-declared agents. It reads them from the packages in Pi's `settings.json` `packages[]`, global and project, and never from `node_modules`, because the only scan is Pi's own configured-package list (`node_modules/@tintinweb/pi-subagents/dist/package-resources.js:327-341`). It sees a project-scope package only after the project is trusted: the trust flag starts `false` (`node_modules/@tintinweb/pi-subagents/dist/package-resources.js:90`), is passed to `SettingsManager.create` when the package list is read (`node_modules/@tintinweb/pi-subagents/dist/package-resources.js:332`), and keys the scan (`node_modules/@tintinweb/pi-subagents/dist/package-resources.js:432`). An installed Systematic therefore exposes `systematic-<name>` types with plain defaults and no export step. `pi -e` does not, because it is not in `packages[]`, and neither does a git install, which has no built `dist/`. `tests/integration/pi.test.ts:
|
|
59
|
+
- **Installed package.** The package declares `pi.subagents.agents` at `package.json:24-28`, pointing at `dist/pi-subagents/agents/`. `scripts/build-pi-package-agents.ts` writes that directory at build time from the same render the export uses, so the 29 curated personas it ships are byte-equal to the committed fixtures (`tests/unit/package-exports.test.ts:289-344`) [PI-7]. pi-subagents 0.22 is the first release that reads package-declared agents. It reads them from the packages in Pi's `settings.json` `packages[]`, global and project, and never from `node_modules`, because the only scan is Pi's own configured-package list (`node_modules/@tintinweb/pi-subagents/dist/package-resources.js:327-341`). It sees a project-scope package only after the project is trusted: the trust flag starts `false` (`node_modules/@tintinweb/pi-subagents/dist/package-resources.js:90`), is passed to `SettingsManager.create` when the package list is read (`node_modules/@tintinweb/pi-subagents/dist/package-resources.js:332`), and keys the scan (`node_modules/@tintinweb/pi-subagents/dist/package-resources.js:432`). An installed Systematic therefore exposes `systematic-<name>` types with plain defaults and no export step. `pi -e` does not, because it is not in `packages[]`, and neither does a git install, which has no built `dist/`. `tests/integration/pi.test.ts:1553-1655` pins dispatch from the package at project and global scope, the `packageAgents: false` switch in `subagents.json`, and local precedence [PI-7].
|
|
60
60
|
- **Export.** `systematic pi-subagents <preview|export|refresh|cleanup> --scope project|global` writes flat files that carry `systematic.json` overlays. Package agents load first, so a local file of the same name outranks the packaged one (`node_modules/@tintinweb/pi-subagents/dist/custom-agents.js:36-39,59-64`). No files are written without an explicit command [PI-7].
|
|
61
61
|
|
|
62
62
|
Packaged personas are config-blind. The only function that sets pi-subagents' agent registry, `registerAgents` (`node_modules/@tintinweb/pi-subagents/dist/agent-types.js:65`), is called only from its own `dist/index.js:361`, so another extension cannot register or filter agent types. Overlays, `disabled_agents` and `agents.<name>.disable` therefore cannot reach a packaged file. `src/pi.ts:165-179` warns once at startup when either is configured. pi-subagents' own `/agents → Disable` turns off one packaged persona, and `packageAgents: false` in `subagents.json` turns off all of them (`node_modules/@tintinweb/pi-subagents/dist/settings.js:133-135`). A top-level `Agent` call runs in the background unless it passes `run_in_background: false` (`node_modules/@tintinweb/pi-subagents/dist/index.js:1187`).
|
|
@@ -67,7 +67,7 @@ Systematic's own config (`systematic.json`/`.jsonc`) is the durable source of tr
|
|
|
67
67
|
|
|
68
68
|
Every export/refresh/cleanup operation walks every path component from a scope-anchored root down to the target agents directory and fails closed if any intermediate component is a symlink or a non-directory: the project anchor is the current working directory, the default global anchor is the user's home directory, and when `PI_CODING_AGENT_DIR` is set the anchor is that variable's parent directory. Manifest entries must name files matching `systematic-*.md`. `cleanup` deletes a manifest-owned file only when its on-disk content hash still matches the manifest's recorded hash — if a generated file has drifted from what the manifest recorded, `cleanup` refuses before any mutation and leaves both the file and the manifest untouched, and the user reverts the file to its exported content or deletes it by hand before running it again. `export` and `refresh` apply the same hash check to files that are no longer wanted, but a drifted file is left in place and reported as still active, and its previous manifest entry is kept unchanged, so a hand-edit never aborts the run. Manifest content hashes are ownership/drift evidence only — they are not a cryptographic integrity or authenticity guarantee.
|
|
69
69
|
|
|
70
|
-
The package manifest exposes the extension and skills at `package.json:17-23` (and the packaged personas at `package.json:24-28`), with tests verifying both manifest entries and their packaged paths `tests/unit/package-exports.test.ts:64-84,268-288` [PI-4]. Pi's RPC/JSONL test fixture isolates its environment (`tests/integration/pi.test.ts:
|
|
70
|
+
The package manifest exposes the extension and skills at `package.json:17-23` (and the packaged personas at `package.json:24-28`), with tests verifying both manifest entries and their packaged paths `tests/unit/package-exports.test.ts:64-84,268-288` [PI-4]. Pi's RPC/JSONL test fixture isolates its environment (`tests/integration/pi.test.ts:348-387`), and the installed runtime exposes environment-specific agent/session directories `node_modules/@earendil-works/pi-coding-agent/dist/config.js:396-398` [PI-5].
|
|
71
71
|
|
|
72
72
|
Pi honors Systematic's disable settings. `src/pi.ts` loads the merged config once at extension start and passes `disabled_skills` to the skill resolver, so a disabled skill is absent from the `systematic_skill` description and parameter hint and fails to load as unknown. The same list reaches Pi's bootstrap, which drops the worktree placement rule when `git-worktree` is disabled; nothing else from the config reaches the bootstrap, so Pi still ignores `bootstrap.enabled` and `bootstrap.file` and carries the rule even when `bootstrap.file` is set [PI-8]. It filters the `systematic_delegate` catalog with `isAgentDisabled`, so a persona disabled by `disabled_agents` (bare name or `category/name`) or by an `agents.<name>.disable` overlay disappears from the tool's description, hint and lookup. The pi-subagents export applies the same predicate, and `tests/unit/disable-parity.test.ts` pins it to what OpenCode's config handler omits [PI-6]. Settings are read at extension start, so a Pi restart applies a change. Pi's `systematic_skill` takes a single `name` parameter and no arguments (`src/pi.ts:223-227`) [PI-3], so a skill that needs arguments, such as `mode:embed` and image paths for `pr-attachments`, reads them from the invoking instruction text instead; OpenCode and Claude Code can also pass skill arguments. Pi's own skill discovery is a separate path: `pi.skills` ships the whole `./skills` directory and Pi's `/skill:name` commands, so those still list and load disabled skills [PI-4], [PI-5]. Pi's skill loading also has no OpenCode-style permission gate — OpenCode's `skill-tool.ts` calls `context.ask({ permission: 'skill', ... })` before returning skill content, and Systematic's Pi tool implementation asks for no confirmation and registers no `tool_call` handler, the event Pi (1.4.0, as installed here) offers extensions for blocking a call (`node_modules/@earendil-works/pi-coding-agent/dist/core/extensions/types.d.ts:1224`) [PI-6]. Those are deliberate honesty boundaries, not implied parity.
|
|
73
73
|
|
|
@@ -90,12 +90,13 @@ Honest capability boundary: output-style enforcement is real and applies automat
|
|
|
90
90
|
|
|
91
91
|
## Durable-output search — tool surfaces
|
|
92
92
|
|
|
93
|
-
Systematic ships its own search over `docs/solutions/`. It is not a host primitive, so every claim below rests on Systematic's own code and tests. One host-neutral composition, `runSearch` in `src/lib/search-core.ts`, validates, ranks lexically, resolves the
|
|
93
|
+
Systematic ships its own search over four kinds of durable output: `docs/solutions/`, `docs/plans/`, `docs/brainstorms/` and `docs/ideation/`. `kind` takes each of them, or `all` for one ranking across the four; leaving it out means `solution`. It is not a host primitive, so every claim below rests on Systematic's own code and tests. One host-neutral composition, `runSearch` in `src/lib/search-core.ts`, validates, loads each requested kind, ranks lexically, resolves the lifecycle per kind and renders; every surface only maps host I/O to it [SR-1]. The surfaces are `systematic_search` on OpenCode v1, OpenCode v2 and Pi, `systematic search` on the CLI, and the `systematic-search` bin in the Claude Code bundle [SR-1][SR-3]. The learnings-researcher calls it first and keeps its grep steps as the fallback; its `scope: past-work` makes one search per kind across all four, and ce:plan, ce:ideate, ce:brainstorm and deepen-plan dispatch it that way.
|
|
94
94
|
|
|
95
95
|
Evidence tiers differ by host, and this file does not claim more than the tests do:
|
|
96
96
|
- **Host-free contract evidence:** one parity test drives each adapter's real entry over one fixture corpus and compares the rendered text; a second runs the built bin under real Node from a directory with no `node_modules` [SR-1].
|
|
97
97
|
- **Real-host tests:** OpenCode v1 on the floor (1.18.29) and current (1.19.4) lanes, and OpenCode v2 (2.2.0), each call the tool through a real host [SR-2]. CI runs them in the host-contract jobs.
|
|
98
|
-
- **
|
|
98
|
+
- **Delegated-reach tests:** on OpenCode v1 (floor and current), OpenCode v2 and Pi, a dispatched learnings-researcher child calls `systematic_search` and its result reaches the parent. The child's next model request must carry a tool message that starts `Search "` and names both planted documents, and the parent's final request must carry both paths [SR-5]. These prove reach and plumbing. A scripted model makes the call, so they do not show that a live model chooses to search.
|
|
99
|
+
- **Claude Code:** the bin has no CI real-host check. It is covered by its foreign-directory bundle run and the output-style assertion in `tests/integration/claude-code.test.ts` [SR-3]. Whether a Claude Code subagent runs it is recorded once, as manual evidence, in [SR-4].
|
|
99
100
|
|
|
100
101
|
## Worktree placement rule — bootstrap paths
|
|
101
102
|
|
|
@@ -235,9 +236,9 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
|
|
|
235
236
|
- **PI-2** — [Pi profile](skills/using-systematic/references/pi-profile.md#L5-L8).
|
|
236
237
|
- **PI-3** — `src/pi.ts:218-237`.
|
|
237
238
|
- **PI-4** — `package.json:17-23`; `tests/unit/package-exports.test.ts:64-84,268-288`.
|
|
238
|
-
- **PI-5** — `tests/integration/pi.test.ts:
|
|
239
|
+
- **PI-5** — `tests/integration/pi.test.ts:348-387`; installed Pi source `node_modules/@earendil-works/pi-coding-agent/dist/config.js:396-398`.
|
|
239
240
|
- **PI-6** — `src/pi.ts:182-187` (merged `disabled_skills` passed to the skill resolver); `src/pi.ts:250-263` (`systematic_delegate` catalog filtered with `isAgentDisabled`); `src/lib/config.ts:2103-2115` (`isAgentDisabled`); `src/lib/pi-subagents-export.ts:857-893` (`generateEntries` applies it to the export); `tests/unit/disable-parity.test.ts` (parity with OpenCode's config handler); OpenCode's contrasting permission gate at `src/lib/skill-tool.ts:198-203`.
|
|
240
|
-
- **PI-7** — `package.json:24-28` (the `pi.subagents.agents` declaration); `scripts/build-pi-package-agents.ts` (writes `dist/pi-subagents/agents/` at build time); `tests/unit/package-exports.test.ts:76-83,289-344` (manifest key, `pi-package` keyword, packed files byte-equal to the fixtures); `tests/integration/pi.test.ts:
|
|
241
|
+
- **PI-7** — `package.json:24-28` (the `pi.subagents.agents` declaration); `scripts/build-pi-package-agents.ts` (writes `dist/pi-subagents/agents/` at build time); `tests/unit/package-exports.test.ts:76-83,289-344` (manifest key, `pi-package` keyword, packed files byte-equal to the fixtures); `tests/integration/pi.test.ts:1553-1655` (real Pi host: dispatch from the package at project and global scope, the `packageAgents: false` fallback to `general-purpose`, and a local file outranking the packaged one); `node_modules/@tintinweb/pi-subagents/dist/package-resources.js:90,327-341,432` (which packages are read, trust), `node_modules/@tintinweb/pi-subagents/dist/custom-agents.js:36-39,59-64` (precedence), `node_modules/@tintinweb/pi-subagents/dist/settings.js:133-135` (`packageAgents` gate), `node_modules/@tintinweb/pi-subagents/dist/index.js:361,1187` (registry setter and background default), `node_modules/@tintinweb/pi-subagents/dist/agent-types.js:65` (`registerAgents`); `src/lib/pi-subagents-export.ts` (export lifecycle, manifest, rollback, stale-file removal and retention); `src/lib/pi-subagents-personas.ts` (curated persona list, compatibility screening); `src/cli.ts:1080-1106` (CLI surface: `pi-subagents preview|export|refresh|cleanup`). Tested interop contract: pi-subagents 0.22.0 on Pi 1.3.0.
|
|
241
242
|
- **PI-8** — `src/pi.ts:189-204` (rule supplied, `piConfig.disabled_skills` the only config passed); `src/lib/bootstrap.ts:172-198` (`computeBootstrapContentSafe` keeps `bootstrap.enabled` and `bootstrap.file` at their defaults); `tests/unit/pi.test.ts:1317-1447` (real extension init: default, `git-worktree` disabled, `bootstrap.file` set, `bootstrap.enabled: false`, foreign prompt text kept and not doubled).
|
|
242
243
|
- **CC-P** — [Claude Code profile](skills/using-systematic/references/claude-code-profile.md#L3-L9).
|
|
243
244
|
- **CC-1** — [Claude Code skills](https://code.claude.com/docs/en/skills) (`context: fork`); name-based subagent dispatch verified via `claude-code/agents/` and the plugin's invocation convention [CC-9].
|
|
@@ -272,4 +273,6 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
|
|
|
272
273
|
- **WT-2** — `skills/git-worktree/scripts/worktree-manager.sh` (the script); `tests/unit/git-worktree-manager.test.ts` and `tests/unit/git-worktree-cleanup.test.ts` (placement from the root, a subdirectory and a linked worktree, refused layouts, ignore policy, base resolution, `--no-track`, `list`, `switch`, `copy-env`, `cleanup`; real git in throwaway repositories with a bare `origin`, `TEST_BASH=/bin/bash` runs them under bash 3.2); `tests/unit/git-worktree-skills-contract.test.ts` (the safety and routing terms in `skills/git-worktree/SKILL.md` and the pointers in `ce-review`, `orchestrating-subagents` and `git-clean-gone-branches`). Package probe: the plugin-init, Pi-init and built-output-style tests cited by WT-1, OC-8, PI-8 and CC-13. No live session has run.
|
|
273
274
|
- **SR-1** — `src/lib/search-core.ts` (`runSearch`, the tool name and argument constants, the lifecycle constants and resolver); `src/lib/search-tool.ts` (the v1, v2 and Pi adapters); `tests/unit/search-adapters-parity.test.ts` (every adapter's real entry over one corpus: byte-identical text, fixed validation errors, no permission request, registration shapes); `tests/unit/search-lifecycle.test.ts` (the resolver over a lifecycle fixture corpus); `tests/unit/search-determinism.test.ts` (Bun and Node produce the same bits).
|
|
274
275
|
- **SR-2** — `tests/integration/opencode-v1.test.ts` › "systematic_search finds a document under the host project, and limit 0 and 21 reach the core" (CI jobs `Host Contract v1 floor` and `Host Contract v1 current`); `tests/integration/opencode-v2.test.ts` › "systematic_search is offered to the model, finds a document under the project, and limit 0 and 21 reach the core" (CI job `Host Contract v2 shard N/4`, OpenCode 2.2.0, run only when `SYSTEMATIC_OPENCODE_V2_BIN` is set).
|
|
275
|
-
- **SR-3** — `src/claude-code-search.ts` (the bin entry); `tests/unit/claude-code-search.test.ts` (the bundle run from a foreign directory); `tests/unit/harness-profiles-search.test.ts` and `tests/integration/claude-code.test.ts` (the output style names `systematic-search` and `command -v systematic-search`, and still ships no `systematic_skill` tool). No
|
|
276
|
+
- **SR-3** — `src/claude-code-search.ts` (the bin entry); `tests/unit/claude-code-search.test.ts` (the bundle run from a foreign directory); `tests/unit/harness-profiles-search.test.ts` and `tests/integration/claude-code.test.ts` (the output style names `systematic-search` and `command -v systematic-search`, and still ships no `systematic_skill` tool). No CI job runs the bin inside a live Claude Code session; see SR-4.
|
|
277
|
+
- **SR-4** — Manual evidence, not a CI check. Recorded 2026-10-31 with Claude Code 2.1.312 and model claude-sonnet-5-5. The plugin bundle was built from 9ed5a336 with `bun run claude-code:build` and loaded with `--plugin-dir`. The fixture project held one solution and one `status: abandoned` brainstorm. `claude -p --output-format stream-json --verbose --forward-subagent-text` was given a prompt to dispatch `systematic:learnings-researcher` with `scope: past-work`. Outcome: the subagent ran `systematic-search --kind all --limit 12 -- '<query>'` through Bash. The Bash `tool_use` carried `parent_tool_use_id` set to the `Agent` dispatch's id. The `tool_result` began `Search "` and named both the solution and the brainstorm. In that bundle the researcher still used the `all` call. The per-kind calls that replaced it run through the same bin.
|
|
278
|
+
- **SR-5** — `tests/helpers/delegated-search-proof.ts` (the planted fixture, the scripted four-turn model and the proof assertion with its failure diagnostics); `tests/unit/delegated-search-proof.test.ts` (the assertion over recorded request lists, including each failure code); `tests/integration/opencode-v1.test.ts` › "a dispatched learnings-researcher child calls systematic_search and its result reaches the parent" (CI jobs `Host Contract v1 floor` and `Host Contract v1 current`, OpenCode 1.18.29 and the current v1 pin); `tests/integration/opencode-v2.test.ts` › the same test name (CI job `Host Contract v2 shard N/4`, OpenCode 2.2.0, run only when `SYSTEMATIC_OPENCODE_V2_BIN` is set); `tests/integration/pi.test.ts` › "a delegated learnings-researcher child calls systematic_search and its result reaches the parent" (the real Pi runtime, run in the v2 host-contract profile). Each file also has a negative control: with `search.enabled` false the child is not offered the tool and the proof fails saying so. Scope limit: a scripted model makes the call, so these show reach and plumbing only.
|
|
@@ -1,23 +1,35 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: learnings-researcher
|
|
3
|
-
description: "Searches docs/solutions/ for relevant past solutions by frontmatter metadata. Use before implementing features or fixing problems to surface institutional knowledge and prevent repeated mistakes."
|
|
3
|
+
description: "Searches docs/solutions/ for relevant past solutions by frontmatter metadata; with scope: past-work, also plans, brainstorms and ideation. Use before implementing features or fixing problems to surface institutional knowledge and prevent repeated mistakes."
|
|
4
4
|
mode: subagent
|
|
5
5
|
temperature: 0.2
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
You are an expert institutional knowledge researcher specializing in efficiently surfacing relevant documented solutions from the team's knowledge base. Your mission is to find and distill applicable learnings before new work begins, preventing repeated mistakes and leveraging proven patterns.
|
|
9
9
|
|
|
10
|
+
## Scope
|
|
11
|
+
|
|
12
|
+
The first line of the prompt may be `scope: <value>`. An optional `exclude: <repo-root path>` line may follow it.
|
|
13
|
+
|
|
14
|
+
- `solutions` is the default, and a prompt with no `scope:` line means `solutions`.
|
|
15
|
+
- `past-work` also covers `docs/plans/`, `docs/brainstorms/` and `docs/ideation/`. Text marked "Past-work" applies only to this scope.
|
|
16
|
+
- Any other value is unknown: name it in the Search Context, and use `solutions`.
|
|
17
|
+
- Overlap mode (the caller asks for an overlap assessment) uses `solutions` whatever the line says.
|
|
18
|
+
|
|
19
|
+
Drop the `exclude:` path from the hits by exact path; a `Supersedes:` line keeps its other entries.
|
|
20
|
+
|
|
10
21
|
## Search Strategy (Search First, Grep Fallback)
|
|
11
22
|
|
|
12
23
|
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
24
|
|
|
14
|
-
Try the search tool
|
|
25
|
+
Try the search tool (Step 1b: one call in `solutions` scope, one per kind in `past-work` scope). When it returns hits, it replaces the grep steps (Steps 2 and 3, and the content search in Step 4). When it cannot help, the grep steps below run unchanged.
|
|
15
26
|
|
|
16
27
|
### Step 0: Discover What Exists
|
|
17
28
|
|
|
18
29
|
List `docs/solutions/` with a directory listing tool.
|
|
19
30
|
|
|
20
31
|
- 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.
|
|
32
|
+
- Past-work: list `docs/solutions/`, `docs/plans/`, `docs/brainstorms/` and `docs/ideation/`, and read no missing path. Stop with "No Matches" only when none of the four exists or holds a `.md` file.
|
|
21
33
|
- The subdirectories you find are the categories. Do not assume any particular category exists.
|
|
22
34
|
- Skip `README.md` files and anything under `_archived/` when collecting candidates. Never treat `critical-patterns.md` as a candidate (Step 3b handles it).
|
|
23
35
|
|
|
@@ -36,7 +48,9 @@ From the feature/task description, identify:
|
|
|
36
48
|
- **Hosts that ship a command instead of a tool (the plugin bundle's `bin/`):** run `command -v systematic-search`. A printed path means the tool exists.
|
|
37
49
|
- If there is no such tool, go to Step 2 and use the grep path.
|
|
38
50
|
|
|
39
|
-
**
|
|
51
|
+
**In `solutions` scope, call it once**, with the problem description as the query and `kind` set to `solution`. With the tool, call `systematic_search({ query: "<description>", kind: "solution" })`. With the command, run `systematic-search --kind solution -- '<description>'` with single quotes removed from the description first. Write the query as symptoms, error text, module names and the topic, as a person would type them. Use the default limit.
|
|
52
|
+
|
|
53
|
+
**Past-work scope.** Make one search per kind, `solution`, `plan`, `brainstorm` and `ideation`, and merge the hits by repo-root path: `systematic_search({ query: "<description>", kind: "<kind>", limit: 5 })`. With the command, pass `--kind <kind> --limit 5`. Never search `all`: long plans crowd the other kinds out of its top results. A `none`, `empty` or zero-hit reply from one kind adds nothing. A kind whose call returns `Error:` is unsearched: say so in Search Context, and grep that kind's directory only (see the Past-work grep fallback). The other kinds' hits still route normally. If every kind errors, run the whole grep path. Route on the merged hits.
|
|
40
54
|
|
|
41
55
|
**Read the reply, then pick one path.** Read the header from the line that starts with `Search "`. On the command path, warnings can print before it.
|
|
42
56
|
|
|
@@ -44,12 +58,13 @@ In overlap mode (the caller asks for an overlap assessment against a new doc), d
|
|
|
44
58
|
|
|
45
59
|
| Reply | Path |
|
|
46
60
|
|-------|------|
|
|
47
|
-
| The header says `corpus: none` | Stop and return the "No Matches" result, saying the project has no solutions directory yet. This is not an error. Do not run the grep steps. A `could not read docs/solutions` warning under the header means the directory exists but cannot be read; report that warning too. |
|
|
48
|
-
| The header says `corpus: empty` | Run Step 3b first. Search leaves out `critical-patterns.md`, so a project whose only doc is that file reports `empty`. Then return the "No Matches" result, saying the project has no indexable docs, together with any relevant critical patterns in the Critical Patterns section. This is not an error. Do not run the grep steps. |
|
|
61
|
+
| The header says `corpus: none` | Stop and return the "No Matches" result, saying the project has no solutions directory yet. This is not an error. Do not run the grep steps. A `could not read docs/solutions` warning under the header means the directory exists but cannot be read; report that warning too. Past-work: that kind adds nothing and is not a stop while another kind has docs; stop only when all four say `none`. |
|
|
62
|
+
| The header says `corpus: empty` | Run Step 3b first. Search leaves out `critical-patterns.md`, so a project whose only doc is that file reports `empty`. Then return the "No Matches" result, saying the project has no indexable docs, together with any relevant critical patterns in the Critical Patterns section. This is not an error. Do not run the grep steps. Past-work: that kind adds nothing; take this row only when no kind has docs. |
|
|
63
|
+
| The reply ends with `[Systematic: search output truncated at 16 KB]` | Past-work. Results were cut: say so, and tell the caller to narrow the query. Do not repeat that call. |
|
|
49
64
|
| The header says `N doc(s), M hit(s)` with M at least 1 (the header prints `1 doc` and `1 hit` in the singular), and at least one hit remains after the overlap-mode drop | **Search path.** Skip Steps 2 and 3 and the content search in Step 4. Run Step 3b. Then go to Step 5 with the hits. |
|
|
50
65
|
| The header says `N doc(s), 0 hits` (including the singular `1 doc, 0 hits`), or in overlap mode no hit remains after the drop | Grep path. Go to Step 2. |
|
|
51
66
|
| The reply says `No project directory is available` | Grep path. Go to Step 2. |
|
|
52
|
-
| The reply says search is disabled, starts with `Error:`, or the call fails | Grep path. Go to Step 2. |
|
|
67
|
+
| The reply says search is disabled, starts with `Error:`, or the call fails | Grep path. Go to Step 2. Past-work: per kind, as above. |
|
|
53
68
|
|
|
54
69
|
The grep path keeps its OR patterns for synonyms. A zero-hit search does not add a new synonym pass.
|
|
55
70
|
|
|
@@ -57,13 +72,14 @@ The grep path keeps its OR patterns for synonyms. A zero-hit search does not add
|
|
|
57
72
|
- The hits are already ranked and already resolved for lifecycle. Do not run Step 4's resolution again.
|
|
58
73
|
- A hit with a `Supersedes:` line is the successor that stands in for the docs it lists. Copy `Supersedes:` and `Caution:` lines literally into the entry, including `Caution: successor unresolved` on a superseded doc whose successor does not resolve.
|
|
59
74
|
- Read a hit's `Status` and lifecycle lines from the reply. Take the other frontmatter fields in Step 5.
|
|
75
|
+
- Copy any `Successor:` line (a successor in another kind) literally in `solutions` and `past-work` scope, overlap mode included. The hit stays, and you never follow it. Past-work: read each hit's `Kind:` and `Status:` fields; Step 3b stays solution-only.
|
|
60
76
|
- In overlap mode, you already dropped the doc under comparison. Compare the docs its `Supersedes:` line listed, as well as the remaining hits. The search rank and hit count never set the `score=` value. Judge the five dimensions for each remaining doc as described under Output Format.
|
|
61
77
|
|
|
62
78
|
### Step 2: Category-Based Narrowing (Optional but Recommended)
|
|
63
79
|
|
|
64
80
|
The grep path starts here.
|
|
65
81
|
|
|
66
|
-
If the feature type is clear, narrow the search to the category directories from Step 0 whose names fit it. Match by name
|
|
82
|
+
If the feature type is clear, narrow the search to the category directories from Step 0 whose names fit it. Match by name; several can fit. When the type is unclear, or no directory fits, search `docs/solutions/` as a whole.
|
|
67
83
|
|
|
68
84
|
### Step 3: Content-Search Pre-Filter (Critical for Efficiency)
|
|
69
85
|
|
|
@@ -79,13 +95,8 @@ content-search: pattern="component:.*background_job" path=docs/solutions/ files_
|
|
|
79
95
|
|
|
80
96
|
**Pattern construction tips:**
|
|
81
97
|
- Use `|` for synonyms: `tags:.*(auth|login|session|token)`
|
|
82
|
-
- Include `title:` - often the most descriptive field
|
|
83
|
-
- Search case-insensitively
|
|
84
|
-
- Include related terms the user might not have mentioned
|
|
85
98
|
- 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.
|
|
86
99
|
|
|
87
|
-
**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.
|
|
88
|
-
|
|
89
100
|
**Combine results** from all searches to get candidate files (typically 5-20 files instead of 200). Drop the files Step 0 says to skip.
|
|
90
101
|
|
|
91
102
|
**If search returns >25 candidates:** Re-run with more specific patterns or combine with category narrowing.
|
|
@@ -121,20 +132,21 @@ Then resolve every candidate before scoring:
|
|
|
121
132
|
| `stale` | Keep it, and give it a `Caution:` line (see Output Format). |
|
|
122
133
|
| `superseded` | Replace it with its successor, if the successor resolves. Otherwise keep the superseded doc and give it `Caution: successor unresolved`. |
|
|
123
134
|
|
|
124
|
-
**Resolving a successor.**
|
|
135
|
+
**Resolving a successor.** A successor resolves only within its own kind (`docs/solutions/`, `docs/plans/`, `docs/brainstorms/`, `docs/ideation/`). The link must be a repo-root path under the holding doc's directory, end in `.md`, contain no `..` segment, not be a `README.md`, not be under `_archived/`, and name a file that exists. A link that fits another of the four directories is not followed (see the apply step). Any other form, such as a bare filename, relative path, empty value or list, and a missing same-kind file, is unresolvable. Do not guess.
|
|
125
136
|
|
|
126
137
|
1. Start with the candidate's `superseded_by` value. Keep a visited set holding the candidate's own path.
|
|
127
|
-
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.
|
|
138
|
+
2. At every hop, before taking the target as the successor, check that it passes the form rule above for the current doc's kind. If it fits another of the four directories, the walk ends here and the doc you are on stays, without reading or checking the target. Otherwise check 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.
|
|
128
139
|
3. If the target is already in the visited set, the chain is a cycle: unresolvable.
|
|
129
140
|
4. Read the target's frontmatter and take its `status`. If it is `superseded`, follow its `superseded_by` and repeat from step 2.
|
|
130
141
|
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.
|
|
131
|
-
6. The first target that is not `superseded` is the successor.
|
|
142
|
+
6. The first target that is not `superseded` is the successor. If reading the target's frontmatter fails, the chain is unresolvable.
|
|
132
143
|
|
|
133
144
|
**Then apply the result.**
|
|
134
145
|
- 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.
|
|
135
146
|
- If the successor is `stale`, it also gets a `Caution:` line.
|
|
136
147
|
- 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.
|
|
137
|
-
- A
|
|
148
|
+
- A walk that ends at a link into another of the four directories leaves the doc it stopped on in place, at its own rank. It stays, with the line `Successor: <path>`, not `Caution: successor unresolved`. This holds in both scopes: a solution superseded by a plan prints `Successor:` on the grep path too, as search does.
|
|
149
|
+
- A superseded candidate with an unresolvable successor is returned itself, at its own rank, with the line `Caution: successor unresolved`. Nothing is dropped. A same-kind successor that is missing, any other form, a cycle and a chain past the hop cap are unresolvable.
|
|
138
150
|
|
|
139
151
|
### Step 5: Read Frontmatter of Candidates Only
|
|
140
152
|
|
|
@@ -156,6 +168,8 @@ Extract these fields from the YAML frontmatter:
|
|
|
156
168
|
|
|
157
169
|
On the grep path, `status`, `superseded_by` and `stale_reason` come from the Step 4 frontmatter read, not from search lines. On the search path they come from the hit's own lines. Values for these fields are whatever the docs use. Do not validate them against a fixed list.
|
|
158
170
|
|
|
171
|
+
Past-work: for plans, brainstorms and ideation docs, read `title`, `topic` and `status`, and the headings of the decision or requirements sections, not the solution fields above.
|
|
172
|
+
|
|
159
173
|
### Step 6: Score and Rank Relevance
|
|
160
174
|
|
|
161
175
|
Match frontmatter fields against the feature/task description:
|
|
@@ -175,17 +189,15 @@ Match frontmatter fields against the feature/task description:
|
|
|
175
189
|
- No overlapping tags, symptoms, or modules
|
|
176
190
|
- Unrelated problem types
|
|
177
191
|
|
|
192
|
+
**Past-work.** Judge plans, brainstorms and ideation docs by their title, topic, filename and decision or requirements sections, not by the solution fields above. A real match on title or topic is enough to keep one. Solutions keep these rules, and `solutions` scope is unchanged.
|
|
193
|
+
|
|
178
194
|
### Step 7: Full Read of Relevant Files
|
|
179
195
|
|
|
180
|
-
|
|
181
|
-
- The full problem description
|
|
182
|
-
- The solution implemented
|
|
183
|
-
- Prevention guidance
|
|
184
|
-
- Code examples
|
|
196
|
+
Fully read only the files that pass the filter (strong or moderate matches), to extract the problem, the solution, prevention guidance and code examples.
|
|
185
197
|
|
|
186
198
|
### Step 8: Return Distilled Summaries
|
|
187
199
|
|
|
188
|
-
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. On a superseded doc whose successor does not resolve, the line is exactly `Caution: successor unresolved`.
|
|
200
|
+
For each relevant document, return a summary in this format. `Supersedes:`, `Successor:` and `Caution:` are optional; include each only when it applies. `Successor:` is copied from the hit, or written on the grep path from a cross-kind link. `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. On a superseded doc whose successor does not resolve, the line is exactly `Caution: successor unresolved`.
|
|
189
201
|
|
|
190
202
|
```markdown
|
|
191
203
|
### [Title from document]
|
|
@@ -196,9 +208,18 @@ For each relevant document, return a summary in this format. `Supersedes:` and `
|
|
|
196
208
|
- **Key Insight**: [The most important takeaway - the thing that prevents repeating the mistake]
|
|
197
209
|
- **Severity**: [severity level]
|
|
198
210
|
Supersedes: <path>[, <path>]
|
|
211
|
+
Successor: <path>
|
|
199
212
|
Caution: <text>
|
|
200
213
|
```
|
|
201
214
|
|
|
215
|
+
### Past-work grep fallback
|
|
216
|
+
|
|
217
|
+
In `past-work` scope, when search cannot help, run Steps 2 to 6 over each of the four directories that exists. If only some kinds errored, run them over that kind's directory only.
|
|
218
|
+
|
|
219
|
+
- **Patterns.** In each directory, match the frontmatter fields `title:`, `topic:`, `status:`, `type:`, `origin:` and `date:`, and match filenames with a glob on the keywords. Read those fields in Steps 5 and 6; a missing `status` is `unspecified`.
|
|
220
|
+
- **Lifecycle.** Run the Step 4 content search over all four. Step 4's rule holds in each: a `superseded_by` resolves only within the doc's own directory, a path in another of the four stays a `Successor:` line, and any other form is `Caution: successor unresolved`.
|
|
221
|
+
- **Origin lookups.** To learn whether a plan carried out a brainstorm, grep `docs/plans/` for its path in `origin:`. The proposal counts as implemented only when that plan's recorded status is `completed`.
|
|
222
|
+
|
|
202
223
|
## Output Format
|
|
203
224
|
|
|
204
225
|
Structure your findings as:
|
|
@@ -223,6 +244,7 @@ Structure your findings as:
|
|
|
223
244
|
- **Relevance**: [why this matters for current task]
|
|
224
245
|
- **Key Insight**: [the gotcha or pattern to apply]
|
|
225
246
|
Supersedes: <path>[, <path>]
|
|
247
|
+
Successor: <path>
|
|
226
248
|
Caution: <text>
|
|
227
249
|
|
|
228
250
|
#### 2. [Title]
|
|
@@ -242,52 +264,53 @@ Overlap: <repo-root path> | problem=match|no-match root_cause=match|no-match sol
|
|
|
242
264
|
|
|
243
265
|
**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. A search score, rank or hit count never maps to High, Moderate or Low. Never compare a doc with itself: leave the doc under comparison out of the lines.
|
|
244
266
|
|
|
267
|
+
## Past-Work Output
|
|
268
|
+
|
|
269
|
+
In `past-work` scope, return this in place of the Output Format template.
|
|
270
|
+
|
|
271
|
+
State the method once, on one line, in Search Context: `search`, `search, plus origin lookups by grep`, or `grep (<why search was not used>)`.
|
|
272
|
+
|
|
273
|
+
**Budget.** Report at most 12 items. Read each one's frontmatter and targeted headings, with at most 3 full reads.
|
|
274
|
+
|
|
275
|
+
**Groups.** Put every item in exactly one group, mechanically from its recorded status, never from inference. Trim and lower-case a plan, brainstorm or ideation status before comparing.
|
|
276
|
+
|
|
277
|
+
| Recorded status | Group |
|
|
278
|
+
|-----------------|-------|
|
|
279
|
+
| any `Kind: solution` hit | Proven lessons |
|
|
280
|
+
| `completed` | Existing or completed work |
|
|
281
|
+
| `abandoned`, `deferred`, `archived`, `superseded` | Rejected, deferred or superseded directions |
|
|
282
|
+
| `draft`, `active`, `unspecified` | Conflicts and open questions, worded "proposed in <path>" |
|
|
283
|
+
| any other value, such as `pending` or `planned`; `stale` keeps its `Caution:` line | Conflicts and open questions, worded "proposed in <path>" |
|
|
284
|
+
|
|
285
|
+
Recorded decisions and their rationale come from body sections (Key Decisions, Scope Boundaries) of lessons, existing work and rejected items, never from an item proposed in <path>. A proposal is never reported as implemented, shipped or decided. Every item carries its repo-root path and recorded status. A recorded status is not verified.
|
|
286
|
+
|
|
287
|
+
When nothing matches, write "no recorded plan or solution found in the results". Do not say the repo holds none.
|
|
288
|
+
|
|
289
|
+
Open with `## Past-Work Search Results` and `### Search Context` (feature, method, absent kinds, unsearched kinds, "results cut, narrow the query" when truncated). Then, omitting empty groups: `### Proven lessons`, `### Recorded decisions and their rationale`, `### Existing or completed work`, `### Rejected, deferred or superseded directions`, `### Conflicts and open questions`.
|
|
290
|
+
|
|
291
|
+
Under each group, one line per item: `- **[title]**: [path], status [recorded status]. [why it applies]`. Copy `Supersedes:`, `Successor:` and `Caution:` lines literally under their item.
|
|
292
|
+
|
|
245
293
|
## Efficiency Guidelines
|
|
246
294
|
|
|
247
295
|
The rules below about content search, patterns, synonyms and narrowing apply to the grep path. On the search path, the hits replace them.
|
|
248
296
|
|
|
249
297
|
**DO:**
|
|
250
298
|
- List `docs/solutions/` first and work from the directories that exist
|
|
251
|
-
- Try the search tool
|
|
299
|
+
- Try the search tool, when it exists, before any grep step: one call in `solutions` scope, one per kind (four) in `past-work` scope
|
|
252
300
|
- Take the grep path when search finds nothing, is disabled, errors or does not exist
|
|
253
301
|
- Use the native content-search tool to pre-filter files BEFORE reading any content (critical for 100+ files)
|
|
254
|
-
- Run
|
|
255
|
-
- Include `title:` in search patterns - often the most descriptive field
|
|
256
|
-
- Use OR patterns for synonyms: `tags:.*(auth|login|session)`
|
|
257
|
-
- Use `-i=true` for case-insensitive matching
|
|
258
|
-
- Use category directories to narrow scope when feature type is clear
|
|
259
|
-
- Do a broader content search as fallback if <3 candidates found
|
|
260
|
-
- Re-narrow with more specific patterns if >25 candidates found
|
|
302
|
+
- Run content searches in PARALLEL, with `title:` and OR patterns for synonyms
|
|
261
303
|
- 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
|
|
262
|
-
- Read the critical patterns file only when it exists
|
|
263
|
-
- Only read frontmatter of search-matched candidates (not all files)
|
|
264
|
-
- Filter aggressively - only fully read truly relevant files
|
|
265
304
|
- Prioritize high-severity and critical patterns
|
|
266
|
-
- Extract actionable insights, not just summaries
|
|
267
|
-
- Note when no relevant learnings exist (this is valuable information too)
|
|
268
305
|
|
|
269
306
|
**DON'T:**
|
|
270
307
|
- Read a path that may not exist (a category directory, `critical-patterns.md`, a successor) without checking that it exists
|
|
271
|
-
- Read frontmatter of ALL files (use content-search to pre-filter first)
|
|
272
|
-
- Run searches sequentially when they can be parallel
|
|
273
|
-
- Use only exact keyword matches (include synonyms)
|
|
274
|
-
- Skip the `title:` field in search patterns
|
|
275
|
-
- Proceed with >25 candidates without narrowing first
|
|
276
|
-
- Read every file in full (wasteful)
|
|
277
308
|
- Return raw document contents (distill instead)
|
|
278
|
-
- Return a superseded doc whose successor resolves. Return its successor.
|
|
279
|
-
- Run the grep steps after a search that returned hits, or call the search tool more than once
|
|
280
|
-
- Follow a `superseded_by`
|
|
309
|
+
- Return a superseded doc whose successor resolves. Return its successor.
|
|
310
|
+
- Run the grep steps after a search that returned hits, or call the search tool more than once in `solutions` scope, or more than four times in `past-work` scope (one call per kind)
|
|
311
|
+
- Follow a `superseded_by` outside the doc's own kind (a link into another of the four directories gets a `Successor:` line instead) or one that fails that kind's form rule, and never follow more than 5 hops
|
|
281
312
|
- Include tangentially related learnings (focus on relevance)
|
|
282
313
|
|
|
283
314
|
## Integration Points
|
|
284
315
|
|
|
285
|
-
|
|
286
|
-
- `/ce:plan` - To inform planning with institutional knowledge and add depth during confidence checking
|
|
287
|
-
- `/ce:review` - To flag known patterns in the diff under review
|
|
288
|
-
- `/ce:ideate` - To ground ideas in documented past solutions
|
|
289
|
-
- `/ce:compound` - As the Related Docs Finder when a new learning is written
|
|
290
|
-
- `/deepen-plan` - To strengthen plans with documented prior art
|
|
291
|
-
- Manual invocation before starting work on a feature
|
|
292
|
-
|
|
293
|
-
The goal is to surface relevant learnings in under 30 seconds for a typical solutions directory, enabling fast knowledge retrieval during planning phases.
|
|
316
|
+
Invoked by `/ce:plan` (planning and confidence checking), `/ce:review` (known patterns in the diff), `/ce:ideate` (grounding ideas), `/ce:compound` (Related Docs Finder), `/deepen-plan`, or manually before starting work. Aim to surface relevant learnings in under 30 seconds.
|
package/dist/cli.js
CHANGED
|
@@ -44,7 +44,7 @@ import {
|
|
|
44
44
|
SEARCH_NOTICES,
|
|
45
45
|
SEARCH_CONFIG_UNREADABLE_NOTE,
|
|
46
46
|
runSearch
|
|
47
|
-
} from "./index-
|
|
47
|
+
} from "./index-e467g4b6.js";
|
|
48
48
|
var __defProp = Object.defineProperty;
|
|
49
49
|
var __returnValue = (v) => v;
|
|
50
50
|
function __exportSetter(name, newValue) {
|
|
@@ -2927,15 +2927,18 @@ function runReviewReturnValidator(options) {
|
|
|
2927
2927
|
// src/lib/search-cli.ts
|
|
2928
2928
|
import path4 from "path";
|
|
2929
2929
|
function searchCliUsage(commandName) {
|
|
2930
|
-
return `Usage: ${commandName} <query...> [--dir <path>] [--kind solution] [--limit <${MIN_LIMIT}-${MAX_LIMIT}>] [--]
|
|
2930
|
+
return `Usage: ${commandName} <query...> [--dir <path>] [--kind solution|plan|brainstorm|ideation|all] [--limit <${MIN_LIMIT}-${MAX_LIMIT}>] [--]
|
|
2931
2931
|
|
|
2932
|
-
Searches the project's
|
|
2933
|
-
|
|
2932
|
+
Searches the project's past work by symptom, error text, module or topic, and
|
|
2933
|
+
prints ranked hits: the docs/solutions learnings, and the docs/plans,
|
|
2934
|
+
docs/brainstorms and docs/ideation documents.
|
|
2934
2935
|
|
|
2935
2936
|
Options:
|
|
2936
2937
|
--dir <path> Start the search from <path> (default: the current directory).
|
|
2937
2938
|
The project root is the nearest ancestor holding .git.
|
|
2938
|
-
--kind <kind> The kind of durable output to search
|
|
2939
|
+
--kind <kind> The kind of durable output to search: solution (docs/solutions,
|
|
2940
|
+
the default), plan (docs/plans), brainstorm (docs/brainstorms),
|
|
2941
|
+
ideation (docs/ideation), or all to rank every kind together.
|
|
2939
2942
|
--limit <n> How many hits to return, ${MIN_LIMIT} to ${MAX_LIMIT} (default: 8).
|
|
2940
2943
|
-- End of options; everything after it is part of the query.
|
|
2941
2944
|
-h, --help Show this help.
|
|
@@ -3387,10 +3390,12 @@ Commands:
|
|
|
3387
3390
|
CI, issues, or fixtures. Not for the ce:review parent's own run artifact.
|
|
3388
3391
|
Exit statuses: 0 valid artifact, 1 validation failure,
|
|
3389
3392
|
2 operational failure, 3 legacy artifact with no schema_version
|
|
3390
|
-
search <query...> [--dir <path>] [--kind solution] [--limit <1-20>]
|
|
3391
|
-
Search the project's
|
|
3392
|
-
|
|
3393
|
-
|
|
3393
|
+
search <query...> [--dir <path>] [--kind solution|plan|brainstorm|ideation|all] [--limit <1-20>]
|
|
3394
|
+
Search the project's past work by symptom, error text, module or topic,
|
|
3395
|
+
and print ranked hits: docs/solutions learnings (the default kind),
|
|
3396
|
+
docs/plans, docs/brainstorms and docs/ideation. --kind all ranks every
|
|
3397
|
+
kind together. The project root is the nearest ancestor of --dir
|
|
3398
|
+
(default: the current directory) that holds .git.
|
|
3394
3399
|
Reads user-level search settings; a project config cannot change them.
|
|
3395
3400
|
Exit statuses: 0 results, no hits, or search disabled; 2 usage error
|
|
3396
3401
|
Use -- to end options, for a query that starts with a dash
|