@kensaurus/skills 0.0.0-stage → 2.0.0

package/skills/audit-bundle-size/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: audit-bundle-size
+description: >
+  Analyse and shrink a web app's JavaScript bundle. Use when "reduce bundle
+  size", "tree shaking", "code splitting", "lazy loading", "slow initial
+  load", "chunk size", "LCP caused by JS", or "why is the bundle so big".
+  Runtime → audit-performance.
+license: MIT
+effort: high
+---
+
+# audit-bundle-size — Find and Eliminate Bundle Bloat
+
+**Degree of freedom: MIXED** — Offender triage and swap choice `[HIGH freedom]`;
+Phase 1 production build + analyser `[LOW freedom — run exactly]`.
+
+> **Audit-and-fix exception.** Measure the payload, then shrink it. Runtime
+> slowness → `audit-performance`.
+>
+> Fix only what the measurement named, in the files it named; a repo-wide
+> dependency sweep the report did not list is a different session. Edit
+> surgically — the offending import, `dynamic()` boundary, or chunk config —
+> rather than rewriting whole files. Pre-existing bugs met on the way go in
+> the report as follow-ups. Add or change tests only where the repo already
+> keeps them for that surface; scratch checks and generated analyser reports
+> (`client.html`, `bundle-report.html`) stay out of the commit. An
+> `ANALYZE=true`-guarded analyser config stays only if the repo already keeps one.
+
+**Every kilobyte of JavaScript the browser must download, parse, and compile
+before showing anything costs real users real time.** A large initial bundle is
+the #1 avoidable cause of slow LCP and poor Core Web Vitals. Find exactly what
+is bloating it and fix each item.
+
+## How to reason — Observe → Interpret → Classify → Severity
+
+1. **Observe** — quote First Load JS / chunk gzip and the treemap contributor (`file` + package)
+2. **Interpret** — is this unused code on the critical path, a duplicate, or a missing split?
+3. **Classify** — giant-vendor / full-library import / missing-lazy / unused-dep / dev-in-prod / duplicate
+4. **Severity** — by gzip on the initial route: >250 KB First Load JS = review; do not delete a feature to save KB
+
+## Worked example
+
+> **Observe:** Next.js First Load JS 420 KB gzip. Treemap: default `lodash`
+> import in `lib/utils.ts`; `moment` with all locales in the shared layout.
+> **Interpret:** two libraries pull unused code onto every route.
+> **Classify:** full-library import + oversized date lib.
+> **Severity:** High — over the 250 KB review threshold.
+> **Finding:** named `lodash/debounce` + replace `moment` with `dayjs`; remesure
+> First Load JS before claiming a save.
+
+---
+
+## Phase 0: Detect bundler and existing setup  [HIGH freedom]
+
+```
+package.json scripts.build   → build command and framework
+vite.config.*                → Vite + rollupOptions
+next.config.*                → Next.js (webpack / Turbopack)
+webpack.config.*             → standalone Webpack
+astro.config.*               → Astro (islands, Vite underneath)
+```
+
+Identify:
+- **Bundler**: Vite / Webpack / Rollup / esbuild / Turbopack / Next.js built-in
+- **Analyser available**: `rollup-plugin-visualizer`, `webpack-bundle-analyzer`,
+  `@next/bundle-analyzer`, `source-map-explorer`
+- **Framework**: Next.js (App / Pages), SvelteKit, Astro, Remix, Nuxt, Vite SPA
+
+---
+
+## Phase 1: Run a production build with analysis  [LOW freedom — run exactly]
+
+### Vite / Rollup
+
+If `rollup-plugin-visualizer` is not installed:
+```bash
+npm install --save-dev rollup-plugin-visualizer
+```
+
+Add temporarily to `vite.config.ts`:
+```typescript
+import { visualizer } from 'rollup-plugin-visualizer';
+// in plugins array:
+visualizer({ open: false, filename: 'dist/bundle-report.html', gzipSize: true })
+```
+
+Then build:
+```bash
+npm run build 2>&1 | tail -40
+```
+
+Read `dist/bundle-report.html` for the treemap, or parse `dist/stats.json` if
+the plugin is configured to output JSON.
+
+### Next.js
+
+```bash
+ANALYZE=true npm run build 2>&1 | tail -60
+```
+
+This requires `@next/bundle-analyzer` in `next.config.*`:
+```javascript
+const withBundleAnalyzer = require('@next/bundle-analyzer')({
+  enabled: process.env.ANALYZE === 'true',
+});
+module.exports = withBundleAnalyzer({ /* your config */ });
+```
+
+Read the generated `client.html` report. Key number: **First Load JS** per route.
+Next.js prints this in the build output — capture it for before/after comparison.
+
+### If no analyser is installed
+
+Use `source-map-explorer` on the build output:
+```bash
+npx source-map-explorer 'dist/**/*.js' --html dist/bundle-report.html
+```
+
+Or for a quick size summary:
+```bash
+find dist -name '*.js' | xargs ls -lh | sort -k5 -hr | head -20
+find dist -name '*.css' | xargs ls -lh | sort -k5 -hr | head -5
+```
+
+---
+
+## Phase 2: Parse the results — find the problems  [HIGH freedom]
+
+For each chunk or entry point, record:
+
+| Chunk | Raw size | Gzip size | Largest contributors |
+|-------|----------|-----------|---------------------|
+| main / page.js | ... | ... | [dep@version, ...] |
+| vendor | ... | ... | [dep@version, ...] |
+
+### Red flags to look for
+
+| Problem | Signal | Impact |
+|---------|--------|--------|
+| One giant vendor chunk | Single `vendor.js` > 200 KB gzip | High — blocks first paint |
+| Duplicate dependency | Same library listed twice (e.g. `lodash` + `lodash-es`) | Medium |
+| Full library import | `import _ from 'lodash'` (imports everything) | High |
+| Missing lazy routes | All routes in one bundle | High |
+| Unused package | Large dep that appears in bundle but only 1–2 exports used | High |
+| Dev-only dep in prod bundle | `faker`, `debug`, `chalk` in client code | Medium |
+| Moment.js | 67 KB gzip with all locales | Medium — replace with date-fns or dayjs |
+| Material UI / Ant Design full import | Full icon library loaded | High |
+| `react-icons` full package | 50+ MB raw, huge when not tree-shaken | High |
+
+**Also check:**
+- [ ] React Compiler on (delete manual memo it makes redundant — smaller bundle, fewer bugs)
+- [ ] Barrel imports routed through `experimental.optimizePackageImports` / direct paths (icon libs, lodash, date libs)
+- [ ] Route prefetch is deliberate — Next.js 16 prefetch is conservative by default; `<Link prefetch>` only on likely-next routes, and don't double-prefetch what Speculation Rules already cover
+
+Below-fold widgets → `dynamic()` with a Suspense skeleton; navigation prefetch/prerender → `enhance-web-instant-nav`.
+
+---
+
+## Phase 3: Research current alternatives  [HIGH freedom]
+
+For the largest offenders, check current alternatives:
+```json
+firecrawl:firecrawl_search
+{
+  "query": "replace <package-name> smaller alternative bundle size [current year]",
+  "limit": 3,
+  "sources": [{ "type": "web" }]
+}
+```
+
+Common swaps (research to confirm current state):
+- `moment` → `date-fns` or `dayjs` (much smaller, tree-shakeable)
+- `lodash` → native JS or `lodash-es` with named imports
+- Full icon set → per-icon imports or SVG sprites
+- `axios` → native `fetch` (if browser targets allow)
+- Large chart libs → check if a lighter alternative exists for the charts used
+
+---
+
+## Self-critique before applying  [LOW freedom — do not skip]
+
+1. **Measured** — First Load JS / gzip from a production build, not "looks big"
+2. **Behavior preserved** — dynamic import has a loading state; do not delete a feature to save KB
+3. **Right owner** — runtime slowness without payload evidence → `audit-performance`
+4. **Analyzer honest** — if the analyser was skipped, say what you used
+5. **Remeasure after each fix class** — no save claimed from inspection alone
+
+---
+
+## Phase 4: Fix — ordered by size saved  [HIGH freedom]
+
+### Fix 1: Named imports (tree shaking)
+
+```typescript
+// Before — pulls in the whole library
+import _ from 'lodash';
+import { BellIcon } from '@heroicons/react/24/solid'; // only needs Bell
+
+// After — only the export you need
+import debounce from 'lodash/debounce';
+import { BellIcon } from '@heroicons/react/24/solid'; // already correct for heroicons v2
+```
+
+For icon libraries that do not tree-shake well, use per-icon deep imports or
+an SVG sprite sheet.
+
+### Fix 2: Dynamic imports for routes (code splitting)
+
+**Next.js App Router** — code-splits by route automatically. If you have heavy
+components inside a page, split them:
+```typescript
+import dynamic from 'next/dynamic';
+const HeavyChart = dynamic(() => import('../components/HeavyChart'), {
+  loading: () => <ChartSkeleton />,
+  ssr: false, // if it uses browser-only APIs
+});
+```
+
+**Vite / React Router:**
+```typescript
+const LazyPage = React.lazy(() => import('./pages/LazyPage'));
+// Wrap in <Suspense fallback={<PageSkeleton />}>
+```
+
+**SvelteKit** — routes are code-split by default. For heavy components:
+```svelte
+{#await import('./HeavyComponent.svelte') then { default: Component }}
+  <Component />
+{/await}
+```
+
+### Fix 3: Replace or remove over-sized dependencies
+
+Follow the research from Phase 3. For any replacement:
+1. Read the new library's docs via Context7 or Firecrawl before touching code.
+2. Make the swap in one file, run `npm run build`, compare sizes before merging everywhere.
+
+### Fix 4: Bundle splitting configuration
+
+**Vite** — split large deps into their own cacheable chunks:
+```typescript
+build: {
+  rollupOptions: {
+    output: {
+      manualChunks: {
+        'react-vendor': ['react', 'react-dom'],
+        'router': ['react-router-dom'],
+        'charts': ['recharts'], // or whatever charting lib
+      },
+    },
+  },
+},
+```
+
+**Next.js** — configure `splitChunks` in `next.config.*` only if the default
+chunking is creating sub-optimal splits. Prefer `dynamic()` over manual config.
+
+### Fix 5: Remove dev-only packages from the client bundle
+
+Any package that should only run server-side or in tests must not be imported
+from client-side code. Move to `devDependencies` and verify it disappears from
+the bundle after rebuild.
+
+---
+
+## Phase 5: Measure the improvement  [LOW freedom — run exactly]
+
+After fixes, rebuild and re-run Phase 1:
+
+```
+Before: First Load JS = X KB gzip
+After:  First Load JS = Y KB gzip
+Saved:  Z KB (N%)
+```
+
+For each route (Next.js build output shows this), confirm the numbers improved.
+Run a quick Playwright check to confirm the app still works:
+
+```bash
+PW="npx --yes @playwright/cli@latest"
+$PW -s=bundle-check open --headed "<app-url>"    # then `goto` each key route
+$PW -s=bundle-check snapshot                      # no blank screen or error
+$PW -s=bundle-check console                       # no new errors
+```
+
+---
+
+## Quick-reference: size targets
+
+| Asset | Target | Review if |
+|-------|--------|-----------|
+| Initial JS (gzip) | < 100 KB | > 250 KB |
+| Route chunk (gzip) | < 50 KB | > 150 KB |
+| CSS total (gzip) | < 20 KB | > 50 KB |
+| Largest single image | < 200 KB | > 500 KB |
+| Total page weight | < 500 KB | > 1.5 MB |

package/skills/audit-cicd/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: audit-cicd
+description: >
+  Audit GitHub Actions CI/CD for cost, speed, and safety. Use when the Actions
+  bill or minutes are high, runners cost too much, CI is slow, cache storage
+  grows, or "CI/CD / workflow audit". Bypass or ratchet gaming →
+  audit-gate-logic.
+license: MIT
+effort: high
+---
+
+# CI/CD Audit Skill
+
+**Degree of freedom: MIXED** — Steps 1–3 judgment `[HIGH freedom]`; Step 0
+`gh` inventory and Step 4 deletes `[LOW freedom — run exactly]`.
+
+Systematic audit of GitHub Actions workflows to cut the Actions bill (minutes +
+storage) and speed up CI **without losing test coverage or deploy safety**.
+Uses the `gh` CLI for live billing, run history, and storage data.
+
+## How to reason
+
+1. **Observe** — quote the trigger, `runs-on`, `concurrency`, or `gh` minute/storage number
+2. **Interpret** — billed twice, doomed minutes, or a 10× runner on every push?
+3. **Classify** — double-bill / no-concurrency / expensive-runner / doomed-job / storage / correct
+4. **Severity** — by `$` × safety; never score a cut that drops coverage
+
+## Worked example
+
+> **Observe:** `build-mobile.yml` `runs-on: macos-15` on `push:` to every
+> branch; no `if:` gate; private repo.
+> **Interpret:** every push bills ~10× Ubuntu for an iOS job nobody requested.
+> **Classify:** expensive-runner on ordinary push.
+> **Severity:** Very high (~10×).
+> **Finding:** `build-mobile.yml` | macos on push | dispatch/tag-only | ~10×
+
+## Step 0: Inventory the account and pipelines  [LOW freedom — run exactly]
+
+Measure before optimizing. Only **private** repos consume the paid minute
+allowance; public repos get free minutes — don't spend effort there.
+
+```bash
+# Which repos actually cost money (private, active, recent pushes)?
+gh repo list <owner> --limit 200 --json name,visibility,isArchived,pushedAt \
+  --jq 'sort_by(.pushedAt)|reverse|.[]|select(.visibility=="PRIVATE" and .isArchived==false)|"\(.name)\t\(.pushedAt[0:10])"'
+
+# Per repo: active workflows, run volume (last 14d), and runner types
+gh api "repos/<owner>/<repo>/actions/workflows" --jq '.workflows[]|select(.state=="active")|.name'
+gh run list --repo <owner>/<repo> --created ">=YYYY-MM-DD" --limit 200 --json databaseId --jq 'length'
+
+# Storage (the other half of the bill)
+gh api "repos/<owner>/<repo>/actions/artifacts" --paginate --jq '[.artifacts[]|select(.expired==false)|.size_in_bytes]|add'
+gh api "repos/<owner>/<repo>/actions/cache/usage" --jq '.active_caches_size_in_bytes'
+```
+
+Rank repos by `runs × runner-multiplier`. A `macos-*` job counts ~10x a
+`ubuntu` job; `*-large`/bigger runners cost more than standard.
+
+## Step 1: Anti-pattern scan (per workflow)  [HIGH freedom]
+
+For each `.github/workflows/*.yml`, check for the recurring cost drivers:
+
+- [ ] **Double-billing triggers** — the *same jobs* run on both `push: [main]`
+      and `pull_request` for main (every merge bills twice). PR gates
+      verification; a separate `deploy.yml` handles main. If both are needed,
+      guard per-job with `if: github.event_name == '...'`.
+- [ ] **Missing `concurrency`** — no `cancel-in-progress`, so rapid pushes/PR
+      syncs stack full runs instead of superseding.
+- [ ] **Expensive runners on ordinary pushes** — `macos-*` / `*-large` firing
+      on every push instead of `workflow_dispatch` or version tags only.
+- [ ] **No path filters** — docs/config-only changes run the full heavy suite
+      (add `paths:` / `paths-ignore:`).
+- [ ] **Doomed jobs** — a costly job (visual/e2e/Lighthouse) runs in parallel
+      with a cheap gate and keeps burning minutes after the gate fails
+      (gate it with `needs: [...]`).
+- [ ] **Long/default artifact retention** — `upload-artifact` without
+      `retention-days` keeps outputs 90 days; heavy reports uploaded on
+      success (`if: always()`) instead of `if: failure()`.
+- [ ] **Self-uploading SARIF pile-ups** — e.g. gitleaks-action uploads a tiny
+      SARIF artifact every run for 90 days.
+- [ ] **Over-frequent crons** — daily `schedule:` where weekly suffices.
+- [ ] **Redundant rebuilds** — two jobs each run the same build instead of
+      building once and sharing via artifact (only when their build env is
+      identical — see Safety).
+
+## Step 2: Cost levers (highest impact first)  [HIGH freedom]
+
+| Lever | Fix | Impact |
+|-------|-----|--------|
+| macOS/large on push | Gate to `workflow_dispatch` / tags | Very high (~10x) |
+| Doomed heavy jobs | `needs: [cheap-gate]` so they skip on failure | High |
+| Double-billing triggers | Drop the redundant trigger (keep the gate) | High |
+| No concurrency | Add `cancel-in-progress` | Medium |
+| No path filters | `paths:` / `paths-ignore:` | Medium |
+| Daily crons | Move to weekly | Medium |
+| Artifact retention | `retention-days: 1–7` + `if: failure()` | Storage |
+| Repeated installs | Cache deps / Playwright browsers / build cache | Medium |
+
+## Step 3: Fix patterns  [HIGH freedom]
+
+```yaml
+# Concurrency — every workflow. CI/verification cancels superseded runs:
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+# Deploy/release: never cancel a live deploy. For combined verify-on-PR +
+# deploy-on-push workflows, cancel PR churn only:
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+```
+
+```yaml
+# Expensive runner: dispatch/tag-only, not every push
+build-ios:
+  runs-on: macos-15
+  if: ${{ inputs.platform == 'ios' || startsWith(github.ref, 'refs/tags/') }}
+  timeout-minutes: 60   # cap runaway 10x spend
+
+# Lean artifacts
+- uses: actions/upload-artifact@v4
+  if: failure()
+  with: { name: report, path: report/, retention-days: 3 }
+
+# Stop the gitleaks SARIF pile-up
+env: { GITLEAKS_ENABLE_UPLOAD_ARTIFACT: "false" }
+```
+
+## Step 4: Storage cleanup (destructive — confirm first)  [LOW freedom — confirm first]
+
+Artifacts and caches are ephemeral CI outputs; deleting them is safe but
+irreversible. Confirm with the user, then:
+
+```bash
+# Delete non-expired artifacts in a repo
+gh api "repos/<owner>/<repo>/actions/artifacts" --paginate \
+  --jq '.artifacts[]|select(.expired==false)|.id' \
+| xargs -I{} gh api -X DELETE "repos/<owner>/<repo>/actions/artifacts/{}"
+
+# Delete caches
+gh api "repos/<owner>/<repo>/actions/caches" --paginate --jq '.actions_caches[].id' \
+| xargs -I{} gh api -X DELETE "repos/<owner>/<repo>/actions/caches/{}"
+```
+
+## Safety rules (do NOT trade coverage or deploys for cost)
+
+- **Never delete, skip, or weaken a test** to save minutes. Make advisory
+  scans (`npm audit`, CVE scans) `continue-on-error` or move them to a
+  `schedule` — keep the check.
+- **Keep the deploy gate.** If `deploy.yml` triggers on the CI `workflow_run`
+  for `push`, do not remove the `push` trigger from CI.
+- **Only share a build across jobs when their build env is identical.** Reusing
+  an artifact built with different secrets/flags (prod env, QA build stamps)
+  ships or tests the wrong bundle.
+- **Update branch protection when renaming/merging jobs.** If a required status
+  check's job name changes, `PATCH` `required_status_checks.contexts` in the
+  same change or merges hang. Verify:
+  `gh api repos/<owner>/<repo>/branches/<main>/protection/required_status_checks --jq '.contexts'`
+- **Verify with live runs.** After pushing, confirm no `startup_failure`
+  (YAML parses) and that intended jobs skip/run:
+  `gh run view <id> --json jobs --jq '.jobs[]|"\(.conclusion // .status)  \(.name)"'`
+
+## Account backstops (one-time, GitHub UI)
+
+UI-only at the time of writing — check whether the settings API now covers
+them before telling the user it is manual.
+
+- **Default artifact/log retention** → Settings → Actions → General → drop from
+  90 days to ~14 (applies to all repos, including future ones).
+- **Spending budget** → Settings → Billing → Budgets → set an Actions budget
+  with 75/90/100% alerts; keep "Stop usage" off so production deploys never
+  hard-break.
+- **Rotate any secret leaked in a workflow/remote** (the user must revoke;
+  you can only strip it from configs).
+
+## Self-critique before reporting  [LOW freedom — do not skip]
+
+1. **Evidenced** — workflow YAML or `gh` count, not "CI feels expensive"
+2. **Reproducible** — same trigger/`runs-on` still present
+3. **Severity justified** — ranked by `$` × runner multiplier
+4. **Right owner** — silent bypass / ratchet → `audit-gate-logic`; hosting bill → `audit-infra-cost`
+5. **No-false-safety** — no test deleted or skipped to save minutes; storage delete confirmed
+
+## Output: CI/CD Cost Audit Report
+
+```markdown
+## CI/CD Audit: [owner]
+
+### Spend snapshot
+- Actions billable: ~$X/mo (private repos exhaust the included minutes)
+- Top spenders: [repo — ~$Y, driver], ...
+- Storage: [X GB artifacts / Y GB caches]
+
+### Findings (prioritized)
+| # | Repo | Workflow | Anti-pattern | Fix | Impact |
+|---|------|----------|--------------|-----|--------|
+| 1 | repo | build-mobile.yml | macOS on every push | dispatch/tag-only | ~10x |
+
+### Already healthy
+- [repos/workflows already using concurrency, gated runners, path filters]
+
+### Manual actions (user-only)
+- [ ] Default artifact/log retention → 14 days
+- [ ] Actions spending budget + alerts
+- [ ] Rotate leaked secret(s), if any
+
+### Expected outcome
+~$A → ~$B/mo, no loss of test coverage or deploy safety.
+```
+
+## Related
+
+- `audit-gate-logic` — does the gate actually stop what it claims (bypass / ratchet)
+- `audit-infra-cost` — hosting / DB / egress (not Actions minutes)
+- `test-visual-regression` — screenshot CI artifact retention
+- `audit-security` / `deploy-verify` / `workflow-pr` / `create-hook`
+