swe-workflow-skills 0.2.0 → 0.4.0

package/README.md

@@ -1,10 +1,10 @@
 # SWE Workflow Skills for Claude Code
 
 [![roles-check](https://github.com/SWEStash/swe-workflow-skills/actions/workflows/roles-check.yml/badge.svg)](https://github.com/SWEStash/swe-workflow-skills/actions/workflows/roles-check.yml)
-![skills](https://img.shields.io/badge/skills-62-blue)
+![skills](https://img.shields.io/badge/skills-65-blue)
 [![license: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
 
-A curated library of **62 Claude Code Agent Skills** that walk Claude through the
+A curated library of **65 Claude Code Agent Skills** that walk Claude through the
 software lifecycle the way a disciplined senior engineer would — planning, design,
 TDD, review, security, deployment, incidents, and the project-management work around
 them.
@@ -43,8 +43,8 @@ full-SDLC breadth that popular collections don't cover:
   know of aim for (they tend to go deep on the coding inner loop; see
   [Acknowledgements](#acknowledgements)).
 - **Role-scoped.** `/role backend` (or `frontend`, `devops`, `ml`, `ai`, `data`,
-  `security`, `architect`, `em`, `pm`, `strategy`, `qa`, `mobile`, `designer`) promotes
-  a working set to auto-trigger; the rest stay one route away.
+  `data-scientist`, `security`, `architect`, `em`, `pm`, `strategy`, `qa`, `mobile`,
+  `designer`) promotes a working set to auto-trigger; the rest stay one route away.
 - **Cross-platform install.** The installer and SessionStart hook are **pure Node** — the
   one runtime Claude Code already requires — so they run identically on Linux, macOS, and
   Windows (no bash, Python, or `sed`).
@@ -62,7 +62,7 @@ web, claude.ai chat, and Cowork):
 **Want the whole library with the orchestrator** (CLI) — no clone needed:
 
 ```bash
-npx swe-workflow-skills install --global   # all 62 skills + router + /role + the SessionStart hook
+npx swe-workflow-skills install --global   # all 65 skills + router + /role + the SessionStart hook
 ```
 
 Or from a clone: `node install.mjs --global`.
@@ -120,7 +120,7 @@ review) live in the `skill-router` skill and **[ROLES.md](docs/ROLES.md)**.
 
 ## What's included
 
-62 skills — **[full catalog → SKILLS.md](docs/SKILLS.md)**:
+65 skills — **[full catalog → SKILLS.md](docs/SKILLS.md)**:
 
 | Area | Count | Examples |
 |------|-------|----------|
@@ -130,6 +130,7 @@ review) live in the `skill-router` skill and **[ROLES.md](docs/ROLES.md)**.
 | Design | 3 | ui-ux-design, frontend-architecture, accessibility-design |
 | MLOps | 3 | ml-pipeline-design, ml-experiment-tracking, ml-model-deployment |
 | AI Engineering | 2 | llm-app-engineering, ai-evaluation |
+| Data Science | 3 | exploratory-data-analysis, statistical-analysis, notebook-to-production |
 | Data Engineering | 2 | data-pipeline-design, data-quality |
 | Mobile | 2 | mobile-architecture, mobile-release |
 | Evaluation & Monitoring | 2 | observability-design, test-data-strategy |
@@ -143,6 +144,7 @@ review) live in the `skill-router` skill and **[ROLES.md](docs/ROLES.md)**.
 - **[EVALS.md](docs/EVALS.md)** — how the skills are tested (RED/GREEN, pressure tests, CI gate).
 - **[AUTHORING.md](docs/AUTHORING.md)** — write or modify a skill (descriptions, budget, progressive disclosure, evals).
 - **[RELEASING.md](docs/RELEASING.md)** — versioning policy and how to cut a release. Changes are tracked in **[CHANGELOG.md](CHANGELOG.md)**.
+- **[SECURITY.md](SECURITY.md)** — the security model: trust boundaries, what runs automatically, supply-chain guarantees, and how to report a vulnerability.
 
 ## Evaluation
 

package/VERSION

@@ -1 +1 @@
-0.2.0
+0.4.0

package/catalog.json

@@ -8,7 +8,7 @@
     },
     {
       "name": "ai-evaluation",
-      "description": "Define how to evaluate ML models and GenAI/LLM apps — golden datasets, offline metrics, RAG evaluation (faithfulness, answer relevance, context precision/recall) with ragas/deepeval/promptfoo, LLM-as-judge design and calibration, eval regression gates in CI, online A/B and human feedback. Triggers: evaluate the model, eval my chatbot, RAG evals, ragas, LLM as judge, golden dataset, eval suite, is the new prompt better, hallucination rate, benchmark our AI app. Logging/comparing runs → ml-experiment-tracking; building the app → llm-app-engineering.",
+      "description": "Define how to evaluate ML models and GenAI/LLM apps — golden datasets, offline metrics, RAG evaluation (faithfulness, relevance, context precision/recall) with ragas/deepeval/promptfoo, LLM-as-judge design and calibration, eval regression gates in CI, online A/B and human feedback. Logging/comparing runs → ml-experiment-tracking; building the app → llm-app-engineering; general experiment statistics → statistical-analysis. Triggers: evaluate the model, eval my chatbot, RAG evals, ragas, LLM as judge, golden dataset, eval suite, is the new prompt better, hallucination rate, benchmark our AI app.",
       "path": "ai-evaluation/SKILL.md"
     },
     {
@@ -121,6 +121,11 @@
       "description": "Estimate engineering effort with agile techniques — story points, t-shirt sizing, three-point estimation, capacity planning. Triggers: estimate this, how long will this take, story points, t-shirt sizing, effort estimation, capacity planning, sprint planning, budget estimate, forecast, velocity, when will this be done.",
       "path": "effort-estimation/SKILL.md"
     },
+    {
+      "name": "exploratory-data-analysis",
+      "description": "Explore and profile an unfamiliar dataset before modeling or analysis — structural profiling, missingness structure, distributions and outliers, feature–target relationships, leakage awareness, and explicit hypothesis generation. Pipeline-level data trust (broken dashboards, tests, contracts, freshness) → data-quality; formal inference on the hypotheses → statistical-analysis. Triggers: explore this dataset, EDA, profile the data, what's in this data, first look at the data, understand this CSV, distributions, outliers, missing values, correlation, data leakage.",
+      "path": "exploratory-data-analysis/SKILL.md"
+    },
     {
       "name": "feature-planning",
       "description": "Break features into well-scoped tasks with acceptance criteria, risk assessment, and dependency mapping. Triggers: plan this, break this down, scope this feature, create tasks for, sprint planning, how should I implement this feature, user stories, acceptance criteria, dependency mapping, feature breakdown. Creates the plan — executing an already-approved plan checkpoint by checkpoint → plan-execution.",
@@ -178,7 +183,7 @@
     },
     {
       "name": "ml-pipeline-design",
-      "description": "Design reproducible ML training and data pipelines — ingestion, validation, feature engineering, training, evaluation, continuous training orchestration. Triggers: training pipeline, ML data pipeline, feature engineering, ETL for ML, continuous training, data validation, feature store, preprocessing, notebook to pipeline, orchestrate training, Kubeflow, pipeline DAG, point-in-time features. Analytics/BI ELT and dbt warehouse pipelines → data-pipeline-design.",
+      "description": "Design reproducible ML training and data pipelines — ingestion, validation, feature engineering, training, evaluation, continuous training orchestration. Analytics/BI ELT and dbt warehouse pipelines → data-pipeline-design; refactoring general analysis/reporting notebooks (no model training) to production code → notebook-to-production. Triggers: training pipeline, ML data pipeline, feature engineering, ETL for ML, continuous training, data validation, feature store, preprocessing, notebook to training pipeline, orchestrate training, Kubeflow, pipeline DAG, point-in-time features.",
       "path": "ml-pipeline-design/SKILL.md"
     },
     {
@@ -191,6 +196,11 @@
       "description": "Ship mobile apps through the app stores — signing and provisioning, store review and rejection handling, phased/staged rollouts with halt criteria, crash monitoring, versioning and build numbers, beta channels (TestFlight, Play tracks), forced updates, and the no-instant-rollback reality of mobile. Triggers: app store release, publish to App Store, Play Store, TestFlight, staged rollout, app review rejected, code signing, provisioning profile, mobile release, hotfix a mobile bug. General semver/registry/library publishing → release-management.",
       "path": "mobile-release/SKILL.md"
     },
+    {
+      "name": "notebook-to-production",
+      "description": "Refactor analysis notebooks into production-grade code — triage what deserves productionizing, extract modules with tests, parameterize hardcoded values, pin environments for reproducibility, and schedule unattended runs with alerting. Owns general analysis/reporting notebooks; notebooks that feed model TRAINING (feature engineering + training DAGs, scheduled retraining) → ml-pipeline-design. Triggers: productionize this notebook, notebook to script, notebook to module, refactor my notebook, parameterize notebook, papermill, schedule this analysis, reproducible analysis, notebook is a mess.",
+      "path": "notebook-to-production/SKILL.md"
+    },
     {
       "name": "observability-design",
       "description": "Design production observability — SLIs, SLOs, SLAs, error budgets, OpenTelemetry traces/metrics/logs, structured logging, alerting, dashboards. Triggers: SLO, SLI, SLA, error budget, observability, monitoring, OpenTelemetry, OTel, tracing, distributed tracing, structured logging, alerting, dashboard, metrics, correlation ID, alert fatigue.",
@@ -223,7 +233,7 @@
     },
     {
       "name": "project-review",
-      "description": "Review a built project's execution health before a milestone — scope alignment, roadmap / execution-plan adherence, implementation maturity (what's production-ready vs stub/deferred), and the evidence it actually works (tests, coverage, validation results, changelog). Triggers: project review, execution review, are we on track, implementation vs roadmap, scope drift, readiness review, what's actually built, validation results review, pre-launch review. Use strategic-review for vision/positioning/market; technical-debt-review for a pure code-health audit.",
+      "description": "Review a built project's execution health before a milestone — scope alignment, roadmap / execution-plan adherence, implementation maturity (what's production-ready vs stub/deferred), and the evidence it actually works (tests, coverage, validation results, changelog). Use strategic-review for vision/positioning/market; technical-debt-review for a pure code-health audit. Triggers: project review, execution review, are we on track, implementation vs roadmap, scope drift, readiness review, what's actually built, validation results review, pre-launch review.",
       "path": "project-review/SKILL.md"
     },
     {
@@ -253,17 +263,22 @@
     },
     {
       "name": "security-audit",
-      "description": "Comprehensive security analysis — OWASP Top 10, auth/authz flows, injection vulnerabilities, data exposure, secrets detection, dependency CVEs, hardening recommendations. Triggers: security audit, vulnerability, is this secure, security review, pentest prep, OWASP, harden this, check for vulnerabilities, injection, XSS, CSRF, auth security. Reviews EXISTING code/config — design-time analysis of a system not yet built → threat-modeling.",
+      "description": "Comprehensive security analysis — OWASP Top 10, auth/authz flows, injection vulnerabilities, data exposure, secrets detection, dependency CVEs, hardening recommendations. Reviews EXISTING code/config — design-time analysis of a system not yet built → threat-modeling. Triggers: security audit, vulnerability, is this secure, security review, pentest prep, OWASP, harden this, check for vulnerabilities, injection, XSS, CSRF, auth security.",
       "path": "security-audit/SKILL.md"
     },
     {
       "name": "skill-router",
-      "description": "Orchestrator and entry point for the swe-workflow skills library — consult FIRST when starting any non-trivial software task; most skills load name-only and only activate when invoked here. Triggers: starting a feature, planning, an architecture or design decision, implementing, debugging, reviewing, refactoring, testing, security, deployment, an incident, shipping, or unsure which skill fits. Routes intent to the right skill(s) and invokes them by name; shows the Golden Path chains.",
+      "description": "Orchestrator and entry point for the swe-workflow skills library — consult FIRST when starting any non-trivial software task; most skills load name-only and only activate when invoked here. Routes intent to the right skill(s) and invokes them by name; shows the Golden Path chains. Triggers: starting a feature, planning, an architecture or design decision, implementing, debugging, reviewing, refactoring, testing, security, deployment, an incident, shipping, or unsure which skill fits.",
       "path": "skill-router/SKILL.md"
     },
+    {
+      "name": "statistical-analysis",
+      "description": "Design and analyze experiments and statistical tests — test selection with stated assumptions, sample size and power, effect sizes and confidence intervals over bare p-values, and pitfall discipline (multiple comparisons, p-hacking, peeking/optional stopping). Owns experiment statistics generally; live A/B evaluation of AI/LLM apps (quality metrics, judges, feedback) → ai-evaluation. Triggers: hypothesis test, t-test, chi-square, p-value, statistical significance, confidence interval, sample size, power analysis, design an experiment, A/B test, multiple comparisons, is this difference real.",
+      "path": "statistical-analysis/SKILL.md"
+    },
     {
       "name": "strategic-review",
-      "description": "Review a project's strategic position before going public, launching, or raising — vision, mission, value proposition, scope positioning, the defensible wedge, and a live competitive / market comparative analysis. Triggers: strategic review, positioning, go public, go-to-market, market analysis, competitive landscape, value proposition, is there a moat, who are our competitors, platform absorption risk, market positioning, comparable products. Use project-review for execution/roadmap/implementation health; delegates deep market scans to deep-research.",
+      "description": "Review a project's strategic position before going public, launching, or raising — vision, mission, value proposition, scope positioning, the defensible wedge, and a live competitive / market comparative analysis. Use project-review for execution/roadmap/implementation health; delegates deep market scans to deep-research. Triggers: strategic review, positioning, go public, go-to-market, market analysis, competitive landscape, value proposition, is there a moat, who are our competitors, platform absorption risk, market positioning, comparable products.",
       "path": "strategic-review/SKILL.md"
     },
     {

package/commands/role.md

@@ -8,27 +8,61 @@ disable-model-invocation: true
 
 The user is managing the active swe-workflow skill role. The requested role argument is: `$ARGUMENTS`
 
-Run this script exactly once via Bash, then report the result to the user concisely (the new active role, and that the change hot-reloads so it applies to the next prompt):
+**Validate the argument before running anything — this is the security-critical
+step.** It must be empty or match `^[a-z0-9_-]{1,32}$` (role keys are short
+kebab-case names). If it contains ANYTHING else — a space, quote, `$`, backtick,
+slash, semicolon, or any other character — the argument is invalid: do NOT run any
+Bash command that contains the argument in any form (not in a variable, not as an
+argument, not anywhere). Instead reply that the role name is invalid and list the
+available roles by running only the fixed command `node "@@RESOLVE@@" roles` with
+`ROLES_JSON="@@ROLES@@"` exported — that command does not reference the argument at
+all.
+
+If the argument is valid (or empty), run the setup block once, then run the ONE
+branch below that matches, substituting the validated role for `__ROLE__` **only
+where shown** (always inside double quotes as the final argument of a `node`
+call — never assigned to a shell variable). Then report the result concisely (the
+new active role, and that the change hot-reloads so it applies to the next
+prompt):
 
 ```bash
-ROLE="$ARGUMENTS"
+# --- setup (no argument appears here) ---
 RESOLVE="@@RESOLVE@@"; SKILLS="@@SKILLS@@"; SETTINGS="@@SETTINGS@@"
 ROLES="@@ROLES@@"; ACTIVE="@@ACTIVE_ROLE@@"
 export ROLES_JSON="$ROLES"
-if [ -z "$ROLE" ]; then
-  echo "Active role: $(cat "$ACTIVE" 2>/dev/null || echo 'baseline (none)')"
-  echo "Available roles:"; node "$RESOLVE" roles
-elif [ "$ROLE" = "all" ] || [ "$ROLE" = "none" ]; then
-  node "$RESOLVE" apply "$SETTINGS" "$SKILLS" none && rm -f "$ACTIVE"
-  echo "Reset to baseline — only the pinned skills auto-trigger now."
-elif node "$RESOLVE" label "$ROLE" >/dev/null 2>&1; then
-  node "$RESOLVE" apply "$SETTINGS" "$SKILLS" "$ROLE" && printf '%s\n' "$ROLE" > "$ACTIVE"
-  echo "Active role set to '$ROLE' — its skills now auto-trigger."
+```
+
+Empty argument (no role given) — show current + available, no substitution:
+```bash
+echo "Active role: $(cat "$ACTIVE" 2>/dev/null || echo 'baseline (none)')"
+echo "Available roles:"; node "$RESOLVE" roles
+```
+
+Argument is `all` or `none` — reset to baseline:
+```bash
+node "$RESOLVE" apply "$SETTINGS" "$SKILLS" none && rm -f "$ACTIVE"
+echo "Reset to baseline — only the pinned skills auto-trigger now."
+```
+
+Any other validated role — apply it. `resolve.mjs` rejects an unknown role with a
+non-zero exit, so the `&&` short-circuits and the marker is only written for a role
+that actually resolved:
+```bash
+if node "$RESOLVE" apply "$SETTINGS" "$SKILLS" "__ROLE__" && printf '%s\n' "__ROLE__" > "$ACTIVE"; then
+  echo "Active role set — its skills now auto-trigger."
 else
-  echo "Unknown role '$ROLE'. Available roles:"; node "$RESOLVE" roles
+  echo "Unknown role. Available roles:"; node "$RESOLVE" roles
 fi
 ```
 
 Notes:
 - `skillOverrides` and the skill listing hot-reload when `settings.local.json` changes, so the new auto-trigger set takes effect on the next prompt without a restart.
 - This command is for the full (all-skills) CLI install. Hard-subset (`--role`) installs and the per-role marketplace plugins don't need it.
+- Security: `$ARGUMENTS` is never embedded directly (slash-command templates
+  interpolate it as text, so a crafted argument would execute in the shell). The
+  **primary control is the model-side regex validation above** — do it before
+  emitting any Bash. As a deterministic backstop, the validated value reaches the
+  shell only as the final quoted argv of a `node "$RESOLVE"` call, where
+  `resolve.mjs` (`roleOrDie`) rejects any string that is not a known role before
+  it is used — the value is never placed in a bare `ROLE=...` assignment. See
+  `SECURITY.md` for the residual (quote-escape) risk and why it is accepted.

package/install.mjs

@@ -52,6 +52,9 @@ Options:
   -p, --prune      After installing the selected set, remove previously-installed
                    library skills that are NOT in the new selection (never touches
                    your own custom skills). Use to narrow a prior all-skills install.
+  -f, --force      Overwrite a same-named skill directory that this installer did
+                   not create (by default such a collision is skipped, so your own
+                   custom skill with a library name is never clobbered).
   -k, --hook       (default) Install the SessionStart hook that re-asserts the
                    name-only baseline each session + injects the router nudge
                    (prints the settings snippet; never edits settings)
@@ -106,6 +109,7 @@ function toPosix(p) {
 let global = false;
 let hook = true;
 let prune = false;
+let force = false;
 let configDir = "";
 let role = "";
 const selected = [];
@@ -125,6 +129,7 @@ for (let i = 0; i < argv.length; i++) {
     if (role === undefined) fatal("--role requires a role name");
   } else if (a.startsWith("--role=")) role = a.slice("--role=".length);
   else if (a === "-p" || a === "--prune") prune = true;
+  else if (a === "-f" || a === "--force") force = true;
   else if (a === "-k" || a === "--hook") hook = true;
   else if (a === "--no-hook") hook = false;
   else if (a === "-l" || a === "--list") {
@@ -161,6 +166,17 @@ if (role) {
   }
 }
 
+// Positional args must be exact skill names, never paths: a traversal like
+// `install.mjs ../..` would pass the isDir guard below and the clean-copy rmSync
+// would then delete outside the destination. Reject before touching anything.
+if (selected.length > 0) {
+  const known = new Set(listSkillDirs());
+  const bad = selected.filter((s) => !known.has(s));
+  if (bad.length > 0) {
+    fatal(`unknown skill(s): ${bad.join(", ")}. Run 'install.mjs --list' to see skills.`);
+  }
+}
+
 // ---- resolve destination ---------------------------------------------------
 
 let claudeDir;
@@ -181,9 +197,46 @@ if (skillSet.length === 0) {
   skillSet = role ? resolvedSkills(rolesData, role) : listSkillDirs();
 }
 
+// ---- provenance manifest ---------------------------------------------------
+// Records which skill directories THIS installer created, so uninstall/--prune
+// only ever remove our own skills and a re-install never clobbers a user's custom
+// skill that happens to share a library name. See docs SECURITY.md (LOW-003).
+const MANIFEST = join(dest, ".swe-workflow-manifest.json");
+
+function readManifestSkills() {
+  if (existsSync(MANIFEST)) {
+    try {
+      const m = JSON.parse(readFileSync(MANIFEST, "utf-8"));
+      if (Array.isArray(m.skills)) return new Set(m.skills);
+    } catch {
+      /* unreadable manifest -> treat as absent */
+    }
+  }
+  return null; // null = no manifest present
+}
+
+const priorManifest = readManifestSkills();
+// A prior swe-workflow install (any version) leaves these machinery markers even
+// before manifests existed. If neither a manifest nor a marker is present, the dest
+// is not one we've installed into, so a same-named dir there must be the user's.
+const priorInstall =
+  priorManifest !== null ||
+  existsSync(join(dest, ".roles.json")) ||
+  existsSync(join(claudeDir, "hooks", "resolve.mjs"));
+
+// Do we own the skill dir currently at dest? Manifest is authoritative when present;
+// otherwise fall back to "is this dest a prior swe install at all?" so pre-manifest
+// upgrades still overwrite our own skills rather than skipping them.
+function installerOwns(skill) {
+  if (priorManifest !== null) return priorManifest.has(skill);
+  return priorInstall;
+}
+
 // ---- copy skills -----------------------------------------------------------
 
 let errors = 0;
+const installedNow = [];
+const skippedCollisions = [];
 for (const skill of skillSet) {
   const src = join(SKILLS_DIR, skill);
   if (!isDir(src)) {
@@ -191,24 +244,59 @@ for (const skill of skillSet) {
     errors++;
     continue;
   }
+  const destPath = join(dest, skill);
+  // Never clobber a same-named directory we didn't create unless --force.
+  if (isDir(destPath) && !force && !installerOwns(skill)) {
+    warn(
+      `skipping '${skill}': a skill of that name already exists and was not installed ` +
+        `by swe-workflow-skills. Use --force to overwrite it.`,
+    );
+    skippedCollisions.push(skill);
+    continue;
+  }
   // Clean copy: drop any prior version first so files removed upstream don't linger.
-  rmSync(join(dest, skill), { recursive: true, force: true });
-  cpSync(src, join(dest, skill), { recursive: true });
-  log(`Installed: ${skill} -> ${join(dest, skill)}`);
+  rmSync(destPath, { recursive: true, force: true });
+  cpSync(src, destPath, { recursive: true });
+  installedNow.push(skill);
+  log(`Installed: ${skill} -> ${destPath}`);
 }
 
 // --prune: narrow a prior install to the current selection. Only ever removes skills
-// that exist in our source tree (so the user's own custom skills are never touched).
+// that exist in our source tree AND that this installer created (so the user's own
+// custom skills — including any that share a library name — are never touched).
+const pruned = new Set();
 if (prune) {
   const keep = new Set(skillSet);
   for (const s of listSkillDirs()) {
-    if (!keep.has(s) && isDir(join(dest, s))) {
+    if (!keep.has(s) && isDir(join(dest, s)) && installerOwns(s)) {
       rmSync(join(dest, s), { recursive: true, force: true });
+      pruned.add(s);
       log(`Pruned: ${s} (not in selection)`);
     }
   }
 }
 
+// Rewrite the provenance manifest: every library skill we own that is still present.
+// = (what we owned before) ∪ (installed this run) − (pruned this run), intersected
+// with library skill dirs actually on disk. Skipped collisions never enter it.
+const libNames = new Set(listSkillDirs());
+const ownedSkills = new Set([...(priorManifest || []), ...installedNow]);
+const manifestSkills = [...ownedSkills]
+  .filter((s) => !pruned.has(s) && libNames.has(s) && isDir(join(dest, s)))
+  .sort();
+if (installedNow.length > 0 || priorManifest !== null || prune) {
+  let manifestVersion = "";
+  try {
+    manifestVersion = readFileSync(join(REPO_ROOT, "VERSION"), "utf-8").trim();
+  } catch {
+    /* VERSION is optional metadata in the manifest */
+  }
+  writeFileSync(
+    MANIFEST,
+    JSON.stringify({ installer: "swe-workflow-skills", version: manifestVersion, skills: manifestSkills }, null, 2) + "\n",
+  );
+}
+
 // ---- orchestrator machinery (only when skill-router is in the set) ---------
 
 const hasRouter = skillSet.includes("skill-router");
@@ -292,21 +380,39 @@ if (hook) {
   }
 }
 
+// Per-skill collision warnings scroll away during a full install; restate them once
+// at the end so an unowned same-named skill that was left in place is not missed.
+if (skippedCollisions.length > 0) {
+  warn(
+    `left ${skippedCollisions.length} existing skill(s) untouched (not installed by ` +
+      `swe-workflow-skills): ${skippedCollisions.join(", ")}. Re-run with --force to overwrite.`,
+  );
+}
+
 if (errors !== 0) process.exit(1);
 
 function copyIfExists(src, destPath) {
   if (existsSync(src)) cpSync(src, destPath);
 }
 
-// The SessionStart block to merge into settings.json. JSON.stringify keeps the path
-// correctly escaped on every OS (Windows backslashes included).
+// Double-quote a path for the POSIX shell that runs the hook command, escaping the
+// chars that stay active inside double quotes (\ $ ` "). Without the $/` escapes, a
+// config path containing e.g. `$(cmd)` would run that command substitution at every
+// session start. For \ and " this produces exactly what JSON.stringify used to (so
+// Windows paths render unchanged); cmd.exe keeps the backslash before $/`, but paths
+// with those chars are effectively POSIX-only.
+function shellQuote(p) {
+  return '"' + p.replace(/[\\$`"]/g, (c) => "\\" + c) + '"';
+}
+
+// The SessionStart block to merge into settings.json.
 function hookSnippet(path) {
   const block = {
     hooks: {
       SessionStart: [
         {
           matcher: "startup|resume|clear|compact",
-          hooks: [{ type: "command", command: `node ${JSON.stringify(path)}` }],
+          hooks: [{ type: "command", command: `node ${shellQuote(path)}` }],
         },
       ],
     },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "swe-workflow-skills",
-  "version": "0.2.0",
-  "description": "A curated library of 44 Claude Code Agent Skills for the software lifecycle, with orchestrator-routed activation that scales past the skill-listing budget.",
+  "version": "0.4.0",
+  "description": "A curated library of Claude Code Agent Skills covering the full software lifecycle, with orchestrator-routed activation that scales past the skill-listing budget.",
   "type": "module",
   "bin": {
     "swe-workflow-skills": "bin/cli.mjs"

package/roles.json

@@ -127,6 +127,20 @@
         "observability-design"
       ]
     },
+    "data-scientist": {
+      "label": "Data Scientist",
+      "description": "Skills for exploratory data analysis, statistical rigor, notebook productionization, and the experiment-tracking/data-quality/modeling work around them.",
+      "core": "technical",
+      "skills": [
+        "exploratory-data-analysis",
+        "statistical-analysis",
+        "notebook-to-production",
+        "ml-experiment-tracking",
+        "data-quality",
+        "data-modeling",
+        "ai-evaluation"
+      ]
+    },
     "security": {
       "label": "Security Engineer",
       "description": "Skills for design-time threat modeling, security audits, dependency/CVE management, blast-radius analysis, and incident handling.",

package/scripts/resolve.mjs

@@ -104,10 +104,15 @@ function sortKeysDeep(value) {
 
 export function loadSettings(settingsPath) {
   if (existsSync(settingsPath) && statSync(settingsPath).isFile()) {
+    const text = readFileSync(settingsPath, "utf-8");
     try {
-      return JSON.parse(readFileSync(settingsPath, "utf-8")) || {};
-    } catch {
-      return {};
+      return JSON.parse(text) || {};
+    } catch (e) {
+      // A corrupt (e.g. hand-edited) file must NOT read as empty: downstream
+      // writers would rebuild it from {} and silently destroy the user's
+      // settings. Throw so callers skip the write (the SessionStart hook
+      // catches this and leaves the file alone; the CLI surfaces it).
+      throw new Error(`unparseable JSON in ${settingsPath} — fix or remove it (${e.message})`);
     }
   }
   return {};

package/skills/ai-evaluation/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ai-evaluation
-description: "Define how to evaluate ML models and GenAI/LLM apps — golden datasets, offline metrics, RAG evaluation (faithfulness, answer relevance, context precision/recall) with ragas/deepeval/promptfoo, LLM-as-judge design and calibration, eval regression gates in CI, online A/B and human feedback. Triggers: evaluate the model, eval my chatbot, RAG evals, ragas, LLM as judge, golden dataset, eval suite, is the new prompt better, hallucination rate, benchmark our AI app. Logging/comparing runs → ml-experiment-tracking; building the app → llm-app-engineering."
+description: "Define how to evaluate ML models and GenAI/LLM apps — golden datasets, offline metrics, RAG evaluation (faithfulness, relevance, context precision/recall) with ragas/deepeval/promptfoo, LLM-as-judge design and calibration, eval regression gates in CI, online A/B and human feedback. Logging/comparing runs → ml-experiment-tracking; building the app → llm-app-engineering; general experiment statistics → statistical-analysis."
+when_to_use: "Triggers: evaluate the model, eval my chatbot, RAG evals, ragas, LLM as judge, golden dataset, eval suite, is the new prompt better, hallucination rate, benchmark our AI app."
 model: sonnet
 allowed-tools: Read, Grep, Glob, Write, Edit, Bash
 ---

package/skills/code-reviewing/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: code-reviewing
-description: "Structured code reviews enforcing DRY, KISS, YAGNI, SRP, best practices, and project conventions. Triggers: review this code, code review, check my code, what do you think of this implementation, review this PR, is this code good, feedback on my code, review staged changes before commit."
+description: "Structured code reviews enforcing DRY, KISS, YAGNI, SRP, best practices, and project conventions."
+when_to_use: "Triggers: review this code, code review, check my code, what do you think of this implementation, review this PR, is this code good, feedback on my code, review staged changes before commit."
 model: sonnet
 allowed-tools: Read, Grep, Glob, Write, Edit
 ---
@@ -13,10 +14,19 @@ Perform thorough, constructive code reviews that catch bugs, enforce principles,
 
 ### Step 1: Understand the Context
 
-Before reviewing line-by-line, understand the big picture:
+Working-tree changes right now (live at skill load; empty when the tree is clean,
+this isn't a git repo, or the review targets something else — e.g. pasted code or
+a PR):
+
+!`git diff --stat 2>/dev/null || true`
+
+If the summary above is empty or irrelevant to what you were asked to review,
+proceed with the code as provided. Before reviewing line-by-line, understand the
+big picture:
 
 - **What is this code supposed to do?** Read the PR description, linked issue, or ask the user.
-- **What changed?** If reviewing a diff, understand the scope of changes.
+- **What changed?** If reviewing a diff, understand the scope of changes — run the
+  full `git diff` (or `git diff --staged`) when the stat summary isn't enough.
 - **What's the surrounding code like?** Read adjacent files for conventions and patterns.
 
 ### Step 2: First Pass — Structural Review

package/skills/effort-estimation/SKILL.md

@@ -1,92 +1,49 @@
 ---
 name: effort-estimation
-description: "Estimate engineering effort with agile techniques — story points, t-shirt sizing, three-point estimation, capacity planning. Triggers: estimate this, how long will this take, story points, t-shirt sizing, effort estimation, capacity planning, sprint planning, budget estimate, forecast, velocity, when will this be done."
+description: "Estimate engineering effort with agile techniques — story points, t-shirt sizing, three-point estimation, capacity planning."
+when_to_use: "Triggers: estimate this, how long will this take, story points, t-shirt sizing, effort estimation, capacity planning, sprint planning, budget estimate, forecast, velocity, when will this be done."
 model: haiku
 allowed-tools: Read, Grep, Glob, Write, Edit
 ---
 
 # Effort Estimation
 
-Produce honest, useful estimates that help teams plan without creating false precision. Estimation in agile is about making informed decisions under uncertainty, not predicting the future exactly.
-
-## Core Philosophy
-
-**Estimates are forecasts, not commitments.** They communicate "based on what we know today, here's our best guess at the range of effort." They should always include uncertainty ranges, and they should improve as you learn more.
+Produce honest, useful estimates without false precision. Estimates are forecasts,
+not commitments — always ranges, always improving as you learn more.
 
 ## Workflow
 
 ### Step 1: Ensure Tasks Are Defined
 
-You can't estimate undefined work. Before estimating, ensure:
-
-- Tasks are broken down (use `feature-planning` if not)
-- Acceptance criteria exist for each task
-- Technical approach is at least sketched (spikes completed for unknowns)
-
-If the work is too vague to estimate, say so. "I can't estimate this until we do a spike" is a valid and responsible answer.
-
-### Step 2: Choose the Estimation Method
-
-| Method | Best For | Precision | Speed |
-|--------|----------|-----------|-------|
-| **T-shirt sizing** | Roadmap planning, early-stage sizing, large backlogs | Low (ranges) | Very fast |
-| **Story points** (Fibonacci) | Sprint planning, velocity tracking, mature teams | Medium (relative) | Moderate |
-| **Three-point estimation** | High-stakes estimates, budget requests, uncertain work | High (ranges with confidence) | Slow |
-| **Time-based** | Well-understood tasks with low uncertainty | High (hours/days) | Moderate |
-
-**Default recommendation**: T-shirt sizing for roadmap/quarter planning, story points for sprint planning. Three-point for budget requests and stakeholder communication.
+You can't estimate undefined work. Tasks must be broken down (use `feature-planning`
+if not), have acceptance criteria, and have at least a sketched technical approach.
+"I can't estimate this until we do a spike" is a valid and responsible answer.
 
-### Step 3: Apply the Method
+### Step 2: Choose the Method
 
-See [references/estimation-methods.md](references/estimation-methods.md) for detailed guidance on each method.
+T-shirt sizing for roadmap and early-stage sizing; story points (Fibonacci) for
+sprint planning and velocity tracking; three-point estimation for budget requests
+and high-uncertainty, high-stakes work; time-based only for well-understood tasks.
+See [references/estimation-methods.md](references/estimation-methods.md) for
+detailed guidance on each method.
 
-**Key principles across all methods:**
+### Step 3: Apply It
 
-1. **Estimate as a team**, not individually. The person most and least familiar with the area should both contribute — the gap reveals hidden complexity.
-2. **Estimate relative to known work**, not in absolute terms. "This is about twice as hard as that login feature we built" is more accurate than "this will take 3 days."
-3. **Include uncertainty explicitly.** "3-5 days" is more honest than "4 days."
-4. **Estimate the work, not the worker.** Story points measure the task's size, not who's doing it.
-5. **Re-estimate when you learn more.** Initial estimates are educated guesses. Update them as spikes complete and requirements clarify.
+Estimate per task, not the project as a single unit; relative to known work rather
+than in absolute terms; as a team where possible (the familiarity gap between
+estimators reveals hidden complexity); with uncertainty explicit. Re-estimate when
+spikes complete or requirements clarify.
 
-### Step 4: Handle Budget and Timeline Requests
+### Step 4: Translate for Stakeholders
 
-When stakeholders need dates or dollars, translate estimates thoughtfully:
-
-**From story points to time:**
-```
-Estimated story points for the project: 85
-Team velocity: ~30 points per sprint (2-week sprints)
-Sprints needed: 85 / 30 = ~3 sprints = 6 weeks
-
-Add buffer for unknowns (20-30%): 7-8 weeks
-Communicate as range: "6-8 weeks with the current team"
-```
-
-**From effort to cost:**
-```
-Effort estimate: 12-16 person-weeks
-Team loaded cost: $X per person-week
-Total: 12 × $X to 16 × $X
-Communicate as range: "$A - $B"
-```
-
-**Always provide ranges, never single numbers.** A single number becomes a commitment; a range communicates confidence.
+Convert to time or cost via team velocity or loaded cost, add a 20-30% buffer for
+unknowns, and communicate a range in stakeholder language — weeks and dollars, not
+story points. A single number becomes a commitment; a range communicates confidence.
 
 ### Step 5: Track and Calibrate
 
-Estimates improve with feedback. After each sprint or project:
-
-- Compare estimated vs actual effort
-- Identify systematic patterns (always overestimate UI? Always underestimate integrations?)
-- Adjust team velocity based on recent data (use the last 3-5 sprints, not all-time average)
-
-## Common Estimation Traps
-
-- **Anchoring**: The first number said influences everyone else. Use blind estimation (planning poker, simultaneous reveal).
-- **Planning fallacy**: People consistently underestimate. Use historical data to calibrate.
-- **Scope creep blindness**: Estimate the work as defined, then add buffer for scope growth — it always grows.
-- **Hero planning**: Estimating based on the best-case scenario with the best developer with zero interruptions. Estimate for a typical day with meetings and context switches.
-- **Precision theater**: Saying "47 hours" when you mean "roughly a week." False precision erodes trust faster than honest ranges.
+Compare estimated vs actual each sprint, look for systematic bias, and recalibrate
+velocity on the last 3-5 sprints, not the all-time average.
 
 ## Principles Applied