From 0eeb0f88e94dad3ac55fa2232650bb2f918ebb6c Mon Sep 17 00:00:00 2001 From: dvcdsys Date: Wed, 3 Jun 2026 15:19:35 +0100 Subject: [PATCH] =?UTF-8?q?docs(skills):=20make=20workspace=E2=86=92per-pr?= =?UTF-8?q?oject=20search=20transition=20explicit?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reviewer ask: the cix-workspace skill should clearly state that workspace search only SCOPES the work (which repos + a capped chunk teaser) and that you must then switch to per-project search to actually read code. - Step 2: lead with an explicit "now switch from workspace search to per-project search" — the workspace chunk panel is a ~5/repo round-robin teaser, not the answer; drill in with `cix search -n ` or the investigator sub-agent. - Rule 4: make the drill-down actionable — concrete `cix search -n ""` (+ `--server` for non-default), and call out that `-n` takes the exact projects[] id (e.g. github.com/owner/repo@branch) and that `-p` (a filesystem path) is wrong for a remote repo. This is the path fixed in cli/v0.7.1. Synced into the plugin bundle. Co-Authored-By: Claude Opus 4.8 --- plugins/cix/skills/cix-workspace/SKILL.md | 19 ++++++++++++++++--- skills/cix-workspace/SKILL.md | 19 ++++++++++++++++--- 2 files changed, 32 insertions(+), 6 deletions(-) diff --git a/plugins/cix/skills/cix-workspace/SKILL.md b/plugins/cix/skills/cix-workspace/SKILL.md index f894d3e..3b90b10 100644 --- a/plugins/cix/skills/cix-workspace/SKILL.md +++ b/plugins/cix/skills/cix-workspace/SKILL.md @@ -135,6 +135,15 @@ repos are dependencies / consumers / providers / counter-parties. ### Step 2 — answer "what code is relevant?" +**Now switch from workspace search to per-project search.** Workspace +search is a *scoping* tool: it tells you which repos are in play and shows +a teaser of chunks, but that teaser is capped (round-robin, ~5 chunks per +repo) and is NOT where you read the code. Once you know the target repos, +drill into each one with single-project search (`cix search -n +`) or a `cix-workspace-investigator` sub-agent — that is +where the real, file-grouped depth comes from. Don't try to answer the +task from the workspace chunk panel alone. + For each repo from step 1, look at the chunks panel. The chunk list is interleaved by rank across surviving projects so each repo's top hit appears early. Use these chunks as **starting points** for a @@ -273,9 +282,13 @@ the words live", not "where should the change happen". ### Rule 4 — Drop down to single-project search for depth When `projects[]` shows the target at rank 1 with a clear lead -(`project_score` ≥ 1.5× the next), switch to per-project search. -You get file-grouped, deeper results without the cross-project -round-robin cap of 5 chunks per repo. +(`project_score` ≥ 1.5× the next), switch to per-project search: +`cix search -n ""` (add `--server ` when the +workspace is on a non-default server). You get file-grouped, deeper +results without the cross-project round-robin cap of 5 chunks per repo. +`-n` takes the exact `project_path` from `projects[]` (e.g. +`github.com/owner/repo@branch`) — that is the correct, working way to +target one project; don't use `-p` (a filesystem path) for a remote repo. ### Rule 5 — `min_score=0` for intentional cross-project sweeps diff --git a/skills/cix-workspace/SKILL.md b/skills/cix-workspace/SKILL.md index f894d3e..3b90b10 100644 --- a/skills/cix-workspace/SKILL.md +++ b/skills/cix-workspace/SKILL.md @@ -135,6 +135,15 @@ repos are dependencies / consumers / providers / counter-parties. ### Step 2 — answer "what code is relevant?" +**Now switch from workspace search to per-project search.** Workspace +search is a *scoping* tool: it tells you which repos are in play and shows +a teaser of chunks, but that teaser is capped (round-robin, ~5 chunks per +repo) and is NOT where you read the code. Once you know the target repos, +drill into each one with single-project search (`cix search -n +`) or a `cix-workspace-investigator` sub-agent — that is +where the real, file-grouped depth comes from. Don't try to answer the +task from the workspace chunk panel alone. + For each repo from step 1, look at the chunks panel. The chunk list is interleaved by rank across surviving projects so each repo's top hit appears early. Use these chunks as **starting points** for a @@ -273,9 +282,13 @@ the words live", not "where should the change happen". ### Rule 4 — Drop down to single-project search for depth When `projects[]` shows the target at rank 1 with a clear lead -(`project_score` ≥ 1.5× the next), switch to per-project search. -You get file-grouped, deeper results without the cross-project -round-robin cap of 5 chunks per repo. +(`project_score` ≥ 1.5× the next), switch to per-project search: +`cix search -n ""` (add `--server ` when the +workspace is on a non-default server). You get file-grouped, deeper +results without the cross-project round-robin cap of 5 chunks per repo. +`-n` takes the exact `project_path` from `projects[]` (e.g. +`github.com/owner/repo@branch`) — that is the correct, working way to +target one project; don't use `-p` (a filesystem path) for a remote repo. ### Rule 5 — `min_score=0` for intentional cross-project sweeps