From abc6efc4a8beca3d1fa096898025cf0149577cbc Mon Sep 17 00:00:00 2001 From: zouyicheng Date: Wed, 17 Jun 2026 16:45:27 +0800 Subject: [PATCH] feat(skill): steer localExplorer to structured cluster tool over raw CLI MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit local-exploration-workflow step 4 now distinguishes local-node visibility (nvidia-smi/free/df — shell) from cluster-scheduler state (capacity, jobs, status/logs). For the latter it tells the worker to prefer a structured cluster tool *if its catalog includes one*, falling back to shell otherwise. Catalog-relative by design: BrainppCluster is driver-gated (requiresDriver: 'brainpp') and only renders under runtime.driver === 'brainpp', so the static skill body must not name it — the "if your tool catalog includes" phrasing self-nullifies in non-brainpp deployments (Local/Docker/other driver) instead of dangling a reference to a tool that isn't there. Motivated by a dogfood where localExplorer had BrainppCluster inline on the wire (13 turns) yet probed brainctl/rlaunch via Bash throughout. Local- visibility recon via shell stays correct; this only redirects genuine cluster-scheduler queries to the structured tool. Co-Authored-By: Claude Opus 4.8 (1M context) --- src/skill/bundled/index.generated.ts | 2 +- src/skill/bundled/local-exploration-workflow/SKILL.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/skill/bundled/index.generated.ts b/src/skill/bundled/index.generated.ts index 983192ce..07386121 100644 --- a/src/skill/bundled/index.generated.ts +++ b/src/skill/bundled/index.generated.ts @@ -170,7 +170,7 @@ export const bundledSkills: LoadedSkill[] = [ ], "source": "builtin", "filePath": "builtin:local-exploration-workflow", - "body": "# Local Exploration Workflow\n\nProcedure for taking a focused local-lookup request from probe selection to a complete, source-cited answer.\n\n## Workflow\n\n1. Read the request. Identify the scope (which directory, which symbol, which system aspect) and what \"found\" looks like.\n2. The framework injects relevant prior memory automatically — check it first; you may already have a pointer to the answer (e.g. a previously-noted file path) without searching. But memory is a hint, not a fact (see #3).\n3. Verify memory-derived assumptions before relying on them. The local environment changes — files move, packages upgrade, configs relocate. If memory says \"config X is at /etc/x.conf\", probe it (a quick stat) to confirm before quoting it as the answer. Memory shortens the lookup path; it does not skip verification.\n4. Pick the right probe for the scope: pattern search in files, file lookup by glob, full-file read for known paths, shell commands for system state (process tree, env, disk, package metadata, log tails).\n5. Start narrow (specific pattern / directory), broaden if no hits.\n6. Verify load-bearing facts. If a path, version, or system state is central to the answer, double-check it with a second probe before returning.\n7. Before returning, ask: would a thoughtful reader of your output obviously need to ask a near-identical follow-up to complete its task? If yes, go fetch the missing piece now. If no, return.\n8. When a finding is durable and reusable (a stable file location, a system config path, an env / package version that scopes the answer), persist it as a memory entry before returning so future explorations skip the re-discovery. Skip the save if memory already had this and you just confirmed it.\n\n## Output conventions\n\n- Format: concrete references first (file:line for code, command + output snippet for system state), then a brief structural summary.\n- Length: match completeness, not a fixed cap. Typical answers fit under 400 words; longer when the question genuinely needs detail.\n- Source attribution: every finding cites its origin — `path/to/file.ts:42` for code, the exact command + output for system state. The reader needs to be able to re-run and verify.\n- Negative result: if not found, say so explicitly and what you tried — e.g. \"no `x.conf` under /etc/ or /usr/local/etc/\" — do not guess.\n- Stale-memory acknowledgement: if a memory-derived hint was wrong (file moved, config relocated, version outdated), mention it in the report so the post-fact extraction updates the entry (e.g. \"memory said config was at /etc/x.conf but it's now at /etc/x/x.conf\").\n\n## Do not\n\n- Do not stop at a shallow first hit when one more probe would confirm the finding. Going one hop deeper on the SAME question is exactly what you are for.\n- Do not trust memory blindly. Environment changes invalidate stale entries; verify before quoting.\n- Do not save trivia to memory (one-off paths the request named explicitly, temporary task context) — only durable, reusable findings." + "body": "# Local Exploration Workflow\n\nProcedure for taking a focused local-lookup request from probe selection to a complete, source-cited answer.\n\n## Workflow\n\n1. Read the request. Identify the scope (which directory, which symbol, which system aspect) and what \"found\" looks like.\n2. The framework injects relevant prior memory automatically — check it first; you may already have a pointer to the answer (e.g. a previously-noted file path) without searching. But memory is a hint, not a fact (see #3).\n3. Verify memory-derived assumptions before relying on them. The local environment changes — files move, packages upgrade, configs relocate. If memory says \"config X is at /etc/x.conf\", probe it (a quick stat) to confirm before quoting it as the answer. Memory shortens the lookup path; it does not skip verification.\n4. Pick the right probe for the scope: pattern search in files, file lookup by glob, full-file read for known paths, shell commands for system state (process tree, env, disk, package metadata, log tails). Distinguish what *this* node/container itself sees (`nvidia-smi`, `free`, `df` — ordinary shell probes) from cluster-scheduler state (pool-wide capacity, queued or running jobs, a job's status or logs): for the latter, if your tool catalog includes a structured cluster tool, prefer it over parsing raw CLI text (e.g. `kubectl` / `squeue`), and fall back to shell only when no such tool is present.\n5. Start narrow (specific pattern / directory), broaden if no hits.\n6. Verify load-bearing facts. If a path, version, or system state is central to the answer, double-check it with a second probe before returning.\n7. Before returning, ask: would a thoughtful reader of your output obviously need to ask a near-identical follow-up to complete its task? If yes, go fetch the missing piece now. If no, return.\n8. When a finding is durable and reusable (a stable file location, a system config path, an env / package version that scopes the answer), persist it as a memory entry before returning so future explorations skip the re-discovery. Skip the save if memory already had this and you just confirmed it.\n\n## Output conventions\n\n- Format: concrete references first (file:line for code, command + output snippet for system state), then a brief structural summary.\n- Length: match completeness, not a fixed cap. Typical answers fit under 400 words; longer when the question genuinely needs detail.\n- Source attribution: every finding cites its origin — `path/to/file.ts:42` for code, the exact command + output for system state. The reader needs to be able to re-run and verify.\n- Negative result: if not found, say so explicitly and what you tried — e.g. \"no `x.conf` under /etc/ or /usr/local/etc/\" — do not guess.\n- Stale-memory acknowledgement: if a memory-derived hint was wrong (file moved, config relocated, version outdated), mention it in the report so the post-fact extraction updates the entry (e.g. \"memory said config was at /etc/x.conf but it's now at /etc/x/x.conf\").\n\n## Do not\n\n- Do not stop at a shallow first hit when one more probe would confirm the finding. Going one hop deeper on the SAME question is exactly what you are for.\n- Do not trust memory blindly. Environment changes invalidate stale entries; verify before quoting.\n- Do not save trivia to memory (one-off paths the request named explicitly, temporary task context) — only durable, reusable findings." }, { "name": "pre-delivery-review-workflow", diff --git a/src/skill/bundled/local-exploration-workflow/SKILL.md b/src/skill/bundled/local-exploration-workflow/SKILL.md index 599b0fc9..fb44fad0 100644 --- a/src/skill/bundled/local-exploration-workflow/SKILL.md +++ b/src/skill/bundled/local-exploration-workflow/SKILL.md @@ -23,7 +23,7 @@ Procedure for taking a focused local-lookup request from probe selection to a co 1. Read the request. Identify the scope (which directory, which symbol, which system aspect) and what "found" looks like. 2. The framework injects relevant prior memory automatically — check it first; you may already have a pointer to the answer (e.g. a previously-noted file path) without searching. But memory is a hint, not a fact (see #3). 3. Verify memory-derived assumptions before relying on them. The local environment changes — files move, packages upgrade, configs relocate. If memory says "config X is at /etc/x.conf", probe it (a quick stat) to confirm before quoting it as the answer. Memory shortens the lookup path; it does not skip verification. -4. Pick the right probe for the scope: pattern search in files, file lookup by glob, full-file read for known paths, shell commands for system state (process tree, env, disk, package metadata, log tails). +4. Pick the right probe for the scope: pattern search in files, file lookup by glob, full-file read for known paths, shell commands for system state (process tree, env, disk, package metadata, log tails). Distinguish what *this* node/container itself sees (`nvidia-smi`, `free`, `df` — ordinary shell probes) from cluster-scheduler state (pool-wide capacity, queued or running jobs, a job's status or logs): for the latter, if your tool catalog includes a structured cluster tool, prefer it over parsing raw CLI text (e.g. `kubectl` / `squeue`), and fall back to shell only when no such tool is present. 5. Start narrow (specific pattern / directory), broaden if no hits. 6. Verify load-bearing facts. If a path, version, or system state is central to the answer, double-check it with a second probe before returning. 7. Before returning, ask: would a thoughtful reader of your output obviously need to ask a near-identical follow-up to complete its task? If yes, go fetch the missing piece now. If no, return.