|
| 1 | +--- |
| 2 | +name: rsdoctor-analysis |
| 3 | +description: Use when analyzing Rspack/Webpack bundles from local `rsdoctor-data.json` and producing evidence-based optimization recommendations. |
| 4 | +--- |
| 5 | + |
| 6 | +# Rsdoctor Analysis Assistant Skill |
| 7 | + |
| 8 | +Use the globally installed `rsdoctor-agent` CLI from `@rsdoctor/agent-cli` only after a real `rsdoctor-data.json` path exists. Keep analysis read-only unless the user explicitly asks for install/config setup. |
| 9 | + |
| 10 | +Response order (required): High-Priority Issues -> Proposed Solutions -> Optional Reference-Chain Follow-up Choices -> Next Deep-Dive Issue Categories (Not commands). |
| 11 | + |
| 12 | +## Core Workflow |
| 13 | + |
| 14 | +1. Reuse current-session results and valid `.rsdoctor-analysis-cache.json` entries before doing new work. |
| 15 | +2. Locate `rsdoctor-data.json` fast: user-provided path, then `dist/rsdoctor-data.json`, `output/rsdoctor-data.json`, `static/rsdoctor-data.json`, `.rsdoctor/rsdoctor-data.json`, then one bounded `rg --files` search excluding `node_modules` and `.git`. Treat `manifest.json` only as an index. |
| 16 | +3. If data exists, skip all plugin version/config/build generation logic. Update cache when useful. |
| 17 | +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. |
| 18 | +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. |
| 19 | +6. Fetch only the Default Evidence Set first; run independent fetches in parallel when possible; synthesize findings in the required response order. |
| 20 | + |
| 21 | +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. |
| 22 | + |
| 23 | +## Generation Gate |
| 24 | + |
| 25 | +Identify `pluginName` (`@rsdoctor/rspack-plugin` or `@rsdoctor/webpack-plugin`) and determine `pluginVersion` from local files first: `package.json`, lockfile, then `node_modules/<plugin>/package.json`; use `pnpm why` / `npm ls` only as fallback. |
| 26 | + |
| 27 | +Use this exact if/else decision tree; do not merge branches: |
| 28 | + |
| 29 | +```text |
| 30 | +if pluginName is missing: |
| 31 | + install/register the matching Rsdoctor plugin, then configure output.mode='brief' and output.options.type=['json']; build with RSDOCTOR=true only |
| 32 | +else if pluginVersion is unknown: |
| 33 | + resolve pluginVersion first; if still unknown, configure output.mode='brief' and output.options.type=['json']; build with RSDOCTOR=true only |
| 34 | +else if pluginVersion >= 1.5.11: |
| 35 | + do not edit plugin config just for JSON; build with RSDOCTOR_OUTPUT=json and RSDOCTOR=true if needed |
| 36 | +else: # pluginVersion < 1.5.11 |
| 37 | + MUST configure output.mode='brief' and output.options.type=['json']; build with RSDOCTOR=true only |
| 38 | +``` |
| 39 | + |
| 40 | +Preflight every build command: `RSDOCTOR_OUTPUT=json` is allowed only in the `pluginVersion >= 1.5.11` branch. For missing, unknown, or `< 1.5.11`, it is forbidden. For `< 1.5.11`, generating `rsdoctor-data.json` requires the plugin config below: |
| 41 | + |
| 42 | +```ts |
| 43 | +output: { |
| 44 | + mode: 'brief', |
| 45 | + options: { |
| 46 | + type: ['json'], |
| 47 | + }, |
| 48 | +} |
| 49 | +``` |
| 50 | + |
| 51 | +## Evidence and Command Bounds |
| 52 | + |
| 53 | +Default Evidence Set: |
| 54 | + |
| 55 | +| Summary key | Evidence source | Bounds | |
| 56 | +| -------------------- | ------------------------------------------ | --------------------------------------------- | |
| 57 | +| `buildCost` | `build summary` | filtered fields only | |
| 58 | +| `assetsTop` | top assets by raw/gzip size | fixed Top-N | |
| 59 | +| `packagesTop` | top packages by gzip size | fixed Top-N; avoid full `packages list` pages | |
| 60 | +| `duplicatePackages` | E1001 duplicate package summary | first-pass summary only | |
| 61 | +| `crossChunkPackages` | E1002 cross-chunk duplication summary | first-pass summary only | |
| 62 | +| `retainedModulesTop` | `tree-shaking retained-modules --limit 10` | filtered fields only; no `--compact` | |
| 63 | + |
| 64 | +Scope rules: |
| 65 | + |
| 66 | +- Use `rsdoctor-agent` for bundle data access only after `rsdoctor-data.json` exists; prefer parallel independent fetches; bound output with `--filter`, pagination, and `--limit`. |
| 67 | +- 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). |
| 68 | +- Treat chain tracing, broad commands, optimization edits, splitChunks experiments, and build re-runs as opt-in follow-ups that require user confirmation. |
| 69 | +- For duplicate packages and tree-shaking issues, identify issues first; trace reference/import chains only after user confirmation. |
| 70 | +- Prefer `tree-shaking retained-modules --emitted-only --category side-effects --limit 10` with narrow `--filter` for side-effects investigations. |
| 71 | +- For retained emitted modules, use `tree-shaking retained-modules` with `--emitted-only`, bounded `--category`, `--sort gzipSize`, `--limit`, and narrow `--filter`; do not pass `--compact`. |
| 72 | +- Use `tree-shaking summary` only as fallback for missing fields or aggregate context. Treat `tree-shaking bailout-reasons` as high-volume; run it only when explicitly requested and pass target `--modules` (max 100). |
| 73 | +- If any command exceeds `5k` tokens, `500 KB` raw output, or a few hundred transcript lines, stop broad fetching and switch to targeted compact queries. |
| 74 | + |
| 75 | +## Output and Recovery |
| 76 | + |
| 77 | +Output format: |
| 78 | + |
| 79 | +1. Issues found in the current build and recommended fixes: |
| 80 | + - Group each issue with its fix recommendation. |
| 81 | + - Include concrete evidence (size/time/count/path/rule code) and priority. |
| 82 | + - For duplicate packages and tree-shaking issues, include a short "continue tracing vs stop here" choice. |
| 83 | +2. Whether deeper analysis is still needed: |
| 84 | + - List remaining issue categories only, not commands. |
| 85 | + |
| 86 | +For Top-N insights, prefer a table: `Name | Volume/Time | Count | Recommendation`. |
| 87 | + |
| 88 | +Recovery rules: |
| 89 | + |
| 90 | +- `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. |
| 91 | +- Command not found: run Analysis Gate, then retry with `rsdoctor-agent`. |
| 92 | +- `query` reports unknown tool: run `list` and use a catalog tool name, or switch to direct `<group> <subcommand>` mode. |
| 93 | +- JSON read error: verify file path, JSON validity, and permissions. |
| 94 | +- In Codex, do not run `install`, `build`, global CLI installation, version checks, or `rsdoctor-agent...` inside sandbox. Run Rsdoctor CLI setup and data-fetch commands outside sandbox so they can access project files and dependencies normally. |
| 95 | + |
| 96 | +References: commands/options [references/command-map.md](references/command-map.md); install/config/data location [references/install-rsdoctor.md](references/install-rsdoctor.md), [references/install-rsdoctor-rspack.md](references/install-rsdoctor-rspack.md), [references/install-rsdoctor-webpack.md](references/install-rsdoctor-webpack.md), [references/install-rsdoctor-common.md](references/install-rsdoctor-common.md); raw data fields [references/rsdoctor-data-types.md](references/rsdoctor-data-types.md); common patterns [references/common-analysis-patterns.md](references/common-analysis-patterns.md). |
0 commit comments