From 363a286efcd88c006cdad38996cde4a084547a60 Mon Sep 17 00:00:00 2001 From: easy1090 Date: Tue, 15 Sep 2026 17:16:37 +0800 Subject: [PATCH 1/3] feat(rsdoctor-analysis): select compiler before analysis --- skills/rsdoctor-analysis/SKILL.md | 20 ++++++++++++++++--- .../references/command-map.md | 9 +++++++++ 2 files changed, 26 insertions(+), 3 deletions(-) diff --git a/skills/rsdoctor-analysis/SKILL.md b/skills/rsdoctor-analysis/SKILL.md index 3a3b938..5fdf332 100644 --- a/skills/rsdoctor-analysis/SKILL.md +++ b/skills/rsdoctor-analysis/SKILL.md @@ -16,11 +16,22 @@ Response order (required): High-Priority Issues -> Proposed Solutions -> Optiona 3. If data exists, skip all plugin version/config/build generation logic. Update cache when useful. 4. If data is missing, stop analysis: do not run `rsdoctor-agent` analysis commands, do not run the Analysis Gate, and either ask for the data path or run the Generation Gate below only when setup/generation is required. 5. After a real data file exists, run Analysis Gate at most once before the first `rsdoctor-agent` data-fetch command: verify global `@rsdoctor/agent-cli` with `npm view @rsdoctor/agent-cli version` and `rsdoctor-agent --version`; install latest only if missing/outdated, a version-related error occurs, or the user asks to refresh. -6. Fetch only the Default Evidence Set first; run independent fetches in parallel when possible. -7. Run the ROI Triage Gate below before selecting deep-dive commands or recommendations. Use it to rank issue categories by measured impact, then synthesize findings in the required response order. +6. Discover compilers before analysis with `rsdoctor-agent compilers list --data-file `, then follow the Compiler selection rules below. +7. Fetch only the Default Evidence Set first; run independent fetches in parallel when possible. Pass the selected `--compiler ` to every data-fetch command. +8. Run the ROI Triage Gate below before selecting deep-dive commands or recommendations. Use it to rank issue categories by measured impact, then synthesize findings in the required response order. Performance rules: parallelize independent checks, cache only derived facts (`dataFile`, `dataFileMtime`, `pluginName`, `pluginVersion`, dependency/config/plugin modification times), and invalidate cache when paths disappear, modification times change, the user asks to refresh, or cached values fail. Speculative plugin checks must not trigger generation; use them only after confirming the data file is missing. +## Compiler selection + +Treat compiler discovery as the first data query, not part of the parallel evidence fetch: + +- If the report has one named compiler, use its exact `name` for the entire analysis. +- If the report has multiple compilers, use the compiler explicitly named by the user. When the request identifies a target such as client, server, or worker but does not match an exact compiler name, map it only when the discovery result makes the match unambiguous; otherwise ask the user to choose from the returned names. +- If a legacy report returns one compiler with `name: null`, omit `--compiler`. +- Never combine or compare compiler results unless the user explicitly requests cross-compiler analysis. Keep the same selected compiler across the Default Evidence Set and all follow-up queries. +- Before fetching evidence, verify the selected compiler's `available` field is `true`. If it is false, ask the user to restore or regenerate that compiler data file. + ## ROI triage gate Before recommending fixes, classify the current build into broad cost buckets and choose the highest-ROI lever from evidence, not intuition. This gate is generic for Rspack/Webpack projects; do not use framework-specific runtime layers unless the user's project exposes them in the data. @@ -84,7 +95,7 @@ Default Evidence Set: Scope rules: -- Use `rsdoctor-agent` for bundle data access only after `rsdoctor-data.json` exists; prefer parallel independent fetches; bound output with `--filter`, pagination, and `--limit`. +- Use `rsdoctor-agent` for bundle data access only after `rsdoctor-data.json` exists; prefer parallel independent fetches; bound output with `--filter`, pagination, and `--limit`. After discovery, pass the selected `--compiler ` to every direct command and `query` call; omit it only for a legacy report whose discovered name is `null`. - Default analysis stays within the Default Evidence Set. For non-default analysis, choose minimal fields from [references/rsdoctor-data-types.md](references/rsdoctor-data-types.md) and patterns from [references/common-analysis-patterns.md](references/common-analysis-patterns.md). - Treat chain tracing, broad commands, optimization edits, splitChunks experiments, and build re-runs as opt-in follow-ups that require user confirmation. - For duplicate packages and tree-shaking issues, identify issues first; trace reference/import chains only after user confirmation. @@ -111,6 +122,9 @@ Recovery rules: - `rsdoctor-data.json` missing: do not run `rsdoctor-agent`; ask for the data path or run Generation Gate, then use the matching install reference if setup is needed. - Command not found: run Analysis Gate, then retry with `rsdoctor-agent`. - `query` reports unknown tool: run `list` and use a catalog tool name, or switch to direct ` ` mode. +- `COMPILER_REQUIRED`: run `compilers list`, select one compiler using the rules above, and retry consistently with `--compiler`. +- `COMPILER_NOT_FOUND`: refresh the compiler list and use an exact returned name; do not guess from `displayName`. +- `COMPILER_DATA_NOT_FOUND`: ask the user to restore or regenerate the selected compiler data file. - JSON read error: verify file path, JSON validity, and permissions. - Run installs, builds, version checks, and `rsdoctor-agent...` commands only in the host's authorized command environment when it has the required project, dependency, and network access. If the available environment lacks that access, stop and ask the user instead of attempting to bypass the sandbox or permission boundary. Clearly identify the missing permission or access; if an Rsdoctor dependency must be installed, tell the user which dependency is required and provide the appropriate package-manager command for them to run. diff --git a/skills/rsdoctor-analysis/references/command-map.md b/skills/rsdoctor-analysis/references/command-map.md index d41480e..e4ca96f 100644 --- a/skills/rsdoctor-analysis/references/command-map.md +++ b/skills/rsdoctor-analysis/references/command-map.md @@ -15,6 +15,7 @@ Top-level command mode: `query` catalog (current): +- `compilers_list` - `chunks_list` - `packages_direct_dependencies` - `packages_duplicates` @@ -29,10 +30,18 @@ Option scopes: - `--data-file `: - required for `query`, direct ` `, and `ai ` - not required for `list`, `ai --describe`, `ai --schema` +- `--compiler `: exact compiler name returned by `compilers list`; pass it to every analysis command when the report contains named compiler metadata - `--input `: optional for `query` - `--filter <...>`: supported by every data-fetch function; use it to return only required fields selected from `@rsdoctor/types` / [rsdoctor-data-types.md](rsdoctor-data-types.md) - `--compact`: add whenever possible to keep CLI JSON compact. Do not use it with `tree-shaking retained-modules`; use `--filter` and `--limit` instead. +## Compilers + +- `compilers list --data-file ` -> Discover compiler names, resolved data files, and availability before fetching analysis evidence. Tool name: `compilers_list`. +- A single named compiler is selected automatically by the CLI, but still use its exact name consistently after discovery. For multiple compilers, select one according to the user's target and pass `--compiler ` to every direct command or `query` call. +- A legacy report appears as one entry with `name: null`; omit `--compiler` for that report. +- Do not merge results from different compilers unless the user explicitly asks for cross-compiler analysis. + ## Chunks - `chunks list` -> List all chunks. Pagination: `--page-number`, `--page-size` From eb799ac208fa26499fe505da47858114b0fc7030 Mon Sep 17 00:00:00 2001 From: easy1090 Date: Fri, 16 Oct 2026 11:36:05 +0800 Subject: [PATCH 2/3] fix: clarify cross-compiler analysis passes --- skills/rsdoctor-analysis/SKILL.md | 12 ++++++------ skills/rsdoctor-analysis/references/command-map.md | 6 +++--- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/skills/rsdoctor-analysis/SKILL.md b/skills/rsdoctor-analysis/SKILL.md index 5fdf332..f0127f4 100644 --- a/skills/rsdoctor-analysis/SKILL.md +++ b/skills/rsdoctor-analysis/SKILL.md @@ -17,7 +17,7 @@ Response order (required): High-Priority Issues -> Proposed Solutions -> Optiona 4. If data is missing, stop analysis: do not run `rsdoctor-agent` analysis commands, do not run the Analysis Gate, and either ask for the data path or run the Generation Gate below only when setup/generation is required. 5. After a real data file exists, run Analysis Gate at most once before the first `rsdoctor-agent` data-fetch command: verify global `@rsdoctor/agent-cli` with `npm view @rsdoctor/agent-cli version` and `rsdoctor-agent --version`; install latest only if missing/outdated, a version-related error occurs, or the user asks to refresh. 6. Discover compilers before analysis with `rsdoctor-agent compilers list --data-file `, then follow the Compiler selection rules below. -7. Fetch only the Default Evidence Set first; run independent fetches in parallel when possible. Pass the selected `--compiler ` to every data-fetch command. +7. For each selected compiler, fetch only the Default Evidence Set first; run independent fetches in parallel when possible. Pass that compiler's `--compiler ` to every data-fetch command in its evidence pass. 8. Run the ROI Triage Gate below before selecting deep-dive commands or recommendations. Use it to rank issue categories by measured impact, then synthesize findings in the required response order. Performance rules: parallelize independent checks, cache only derived facts (`dataFile`, `dataFileMtime`, `pluginName`, `pluginVersion`, dependency/config/plugin modification times), and invalidate cache when paths disappear, modification times change, the user asks to refresh, or cached values fail. Speculative plugin checks must not trigger generation; use them only after confirming the data file is missing. @@ -27,10 +27,10 @@ Performance rules: parallelize independent checks, cache only derived facts (`da Treat compiler discovery as the first data query, not part of the parallel evidence fetch: - If the report has one named compiler, use its exact `name` for the entire analysis. -- If the report has multiple compilers, use the compiler explicitly named by the user. When the request identifies a target such as client, server, or worker but does not match an exact compiler name, map it only when the discovery result makes the match unambiguous; otherwise ask the user to choose from the returned names. +- If the report has multiple compilers, resolve each target named by the user to an exact compiler name. When the request identifies a target such as client, server, or worker but does not match an exact name, map it only when the discovery result makes the match unambiguous; if no target is given or a match is ambiguous, ask the user to choose from the returned names. - If a legacy report returns one compiler with `name: null`, omit `--compiler`. -- Never combine or compare compiler results unless the user explicitly requests cross-compiler analysis. Keep the same selected compiler across the Default Evidence Set and all follow-up queries. -- Before fetching evidence, verify the selected compiler's `available` field is `true`. If it is false, ask the user to restore or regenerate that compiler data file. +- For a single-compiler analysis, keep the same selected compiler across the Default Evidence Set and all follow-up queries. If the user explicitly requests cross-compiler analysis, select each requested compiler using the rules above (or all returned compilers when the user requests all), run a separate evidence pass with its own `--compiler `, then compare clearly labeled results. Never mix results from different compilers within a pass. +- Before fetching evidence, verify that every selected compiler's `available` field is `true`. If any is false, ask the user to restore or regenerate that compiler data file. ## ROI triage gate @@ -95,7 +95,7 @@ Default Evidence Set: Scope rules: -- Use `rsdoctor-agent` for bundle data access only after `rsdoctor-data.json` exists; prefer parallel independent fetches; bound output with `--filter`, pagination, and `--limit`. After discovery, pass the selected `--compiler ` to every direct command and `query` call; omit it only for a legacy report whose discovered name is `null`. +- Use `rsdoctor-agent` for bundle data access only after `rsdoctor-data.json` exists; prefer parallel independent fetches; bound output with `--filter`, pagination, and `--limit`. After discovery, pass the compiler selected for that evidence pass as `--compiler ` to every direct command and `query` call; omit it only for a legacy report whose discovered name is `null`. - Default analysis stays within the Default Evidence Set. For non-default analysis, choose minimal fields from [references/rsdoctor-data-types.md](references/rsdoctor-data-types.md) and patterns from [references/common-analysis-patterns.md](references/common-analysis-patterns.md). - Treat chain tracing, broad commands, optimization edits, splitChunks experiments, and build re-runs as opt-in follow-ups that require user confirmation. - For duplicate packages and tree-shaking issues, identify issues first; trace reference/import chains only after user confirmation. @@ -122,7 +122,7 @@ Recovery rules: - `rsdoctor-data.json` missing: do not run `rsdoctor-agent`; ask for the data path or run Generation Gate, then use the matching install reference if setup is needed. - Command not found: run Analysis Gate, then retry with `rsdoctor-agent`. - `query` reports unknown tool: run `list` and use a catalog tool name, or switch to direct ` ` mode. -- `COMPILER_REQUIRED`: run `compilers list`, select one compiler using the rules above, and retry consistently with `--compiler`. +- `COMPILER_REQUIRED`: run `compilers list`, select the requested compiler or compilers using the rules above, and retry each evidence pass consistently with its own `--compiler`. - `COMPILER_NOT_FOUND`: refresh the compiler list and use an exact returned name; do not guess from `displayName`. - `COMPILER_DATA_NOT_FOUND`: ask the user to restore or regenerate the selected compiler data file. - JSON read error: verify file path, JSON validity, and permissions. diff --git a/skills/rsdoctor-analysis/references/command-map.md b/skills/rsdoctor-analysis/references/command-map.md index e4ca96f..36214cc 100644 --- a/skills/rsdoctor-analysis/references/command-map.md +++ b/skills/rsdoctor-analysis/references/command-map.md @@ -30,7 +30,7 @@ Option scopes: - `--data-file `: - required for `query`, direct ` `, and `ai ` - not required for `list`, `ai --describe`, `ai --schema` -- `--compiler `: exact compiler name returned by `compilers list`; pass it to every analysis command when the report contains named compiler metadata +- `--compiler `: exact compiler name returned by `compilers list`; pass the compiler selected for that evidence pass to every analysis command when the report contains named compiler metadata - `--input `: optional for `query` - `--filter <...>`: supported by every data-fetch function; use it to return only required fields selected from `@rsdoctor/types` / [rsdoctor-data-types.md](rsdoctor-data-types.md) - `--compact`: add whenever possible to keep CLI JSON compact. Do not use it with `tree-shaking retained-modules`; use `--filter` and `--limit` instead. @@ -38,9 +38,9 @@ Option scopes: ## Compilers - `compilers list --data-file ` -> Discover compiler names, resolved data files, and availability before fetching analysis evidence. Tool name: `compilers_list`. -- A single named compiler is selected automatically by the CLI, but still use its exact name consistently after discovery. For multiple compilers, select one according to the user's target and pass `--compiler ` to every direct command or `query` call. +- A single named compiler is selected automatically by the CLI, but still use its exact name consistently after discovery. For a single-compiler analysis of a multi-compiler report, select one according to the user's target and pass `--compiler ` to every direct command or `query` call in that evidence pass. - A legacy report appears as one entry with `name: null`; omit `--compiler` for that report. -- Do not merge results from different compilers unless the user explicitly asks for cross-compiler analysis. +- For an explicit cross-compiler comparison, run separate evidence passes with each requested compiler's name, then compare clearly labeled results. Do not mix compiler results within a pass. ## Chunks From 027e3d51d04659944b3b768bbb938747f6a9e626 Mon Sep 17 00:00:00 2001 From: yifancong Date: Thu, 22 Oct 2026 17:18:44 +0800 Subject: [PATCH 3/3] fix(rsdoctor-analysis): scope local JSON to selected compiler --- skills/rsdoctor-analysis/SKILL.md | 1 + skills/rsdoctor-analysis/references/command-map.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/skills/rsdoctor-analysis/SKILL.md b/skills/rsdoctor-analysis/SKILL.md index f0127f4..f7be818 100644 --- a/skills/rsdoctor-analysis/SKILL.md +++ b/skills/rsdoctor-analysis/SKILL.md @@ -30,6 +30,7 @@ Treat compiler discovery as the first data query, not part of the parallel evide - If the report has multiple compilers, resolve each target named by the user to an exact compiler name. When the request identifies a target such as client, server, or worker but does not match an exact name, map it only when the discovery result makes the match unambiguous; if no target is given or a match is ambiguous, ask the user to choose from the returned names. - If a legacy report returns one compiler with `name: null`, omit `--compiler`. - For a single-compiler analysis, keep the same selected compiler across the Default Evidence Set and all follow-up queries. If the user explicitly requests cross-compiler analysis, select each requested compiler using the rules above (or all returned compilers when the user requests all), run a separate evidence pass with its own `--compiler `, then compare clearly labeled results. Never mix results from different compilers within a pass. +- For local JSON evidence in each pass, including E1001/E1002 summaries, read only the selected compiler entry's resolved data file returned by `compilers list`. Do not read the originally supplied aggregate or index file as compiler-scoped evidence. - Before fetching evidence, verify that every selected compiler's `available` field is `true`. If any is false, ask the user to restore or regenerate that compiler data file. ## ROI triage gate diff --git a/skills/rsdoctor-analysis/references/command-map.md b/skills/rsdoctor-analysis/references/command-map.md index 36214cc..7b5530b 100644 --- a/skills/rsdoctor-analysis/references/command-map.md +++ b/skills/rsdoctor-analysis/references/command-map.md @@ -90,7 +90,7 @@ Option scopes: ## Errors - `errors list` -> All errors and warnings -- `errors by-code --code ` -> Filter by code. For default E1001/E1002 summaries, prefer local JSON summarization. +- `errors by-code --code ` -> Filter by code. For default E1001/E1002 summaries, prefer local JSON summarization from the selected compiler entry's resolved data file in `compilers list`, never from the aggregate or index file. - `errors by-level --level ` -> Filter by level ## Rules