swe-workflow-skills 0.2.0 → 0.3.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 |

package/VERSION

@@ -1 +1 @@
-0.2.0
+0.3.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,10 +8,21 @@ 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.** It must be empty or match
+`^[a-z0-9_-]{1,32}$` (role keys are short kebab-case names). If it does not match —
+any spaces, quotes, `$`, backticks, slashes, or other characters — do NOT run the
+script below with it: reply that the role name is invalid and show the available
+roles by running only `node "@@RESOLVE@@" roles` (with `ROLES_JSON="@@ROLES@@"`
+exported).
+
+If the argument is valid, run this script exactly once via Bash, replacing
+`__ROLE__` with the validated argument (or with nothing when no argument was
+given), 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):
 
 ```bash
-ROLE="$ARGUMENTS"
+ROLE="__ROLE__"
+case "$ROLE" in *[!a-zA-Z0-9_-]*) echo "invalid role name" >&2; exit 1;; esac
 RESOLVE="@@RESOLVE@@"; SKILLS="@@SKILLS@@"; SETTINGS="@@SETTINGS@@"
 ROLES="@@ROLES@@"; ACTIVE="@@ACTIVE_ROLE@@"
 export ROLES_JSON="$ROLES"
@@ -32,3 +43,4 @@ 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: the script deliberately never embeds `$ARGUMENTS` directly (slash-command templates interpolate it as text, so a crafted argument would execute in the shell). The value reaches the script only via the validated `__ROLE__` transfer above; the in-script `case` guard is defense-in-depth.

package/install.mjs

@@ -161,6 +161,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;
@@ -298,15 +309,24 @@ 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.3.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
 

package/skills/exploratory-data-analysis/SKILL.md

@@ -0,0 +1,110 @@
+---
+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."
+when_to_use: "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."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash
+---
+
+# Exploratory Data Analysis
+
+Understand a dataset before trusting it with a model or a decision. The output
+of EDA is not a pile of statistics — it is a documented understanding: what the
+data is, what's wrong or surprising in it, and a set of explicit hypotheses to
+test next. Every step below feeds that document.
+
+## Workflow
+
+### 1. Frame the goal and the grain
+
+Before profiling anything, write down what decision or model this data will
+feed, and establish the **grain**: what does one row represent (an order? a
+customer? a customer-month?)? Duplicate keys and mixed grains invalidate every
+later statistic. If the eventual use is prediction, note *when* the prediction
+would be made — that timestamp drives the leakage checks in step 5.
+
+### 2. Profile structurally
+
+Column types, ranges, cardinality, and summary statistics for every column —
+cheaply, before any deep dive. Triage wide tables by metadata first (null rate,
+cardinality, type) and prioritize columns by relevance to the goal; don't
+profile 400 columns equally.
+
+If the data doesn't fit in memory: push aggregations down to the warehouse
+(SQL), or use an out-of-core/lazy engine (DuckDB, Polars). When you sample,
+**sample representatively** — random or stratified, never `head()` (files are
+usually ordered by time or id) — and state the caveat that rare events and
+extreme outliers can be missed under sampling; verify those against the full
+data with targeted queries.
+
+### 3. Map the missingness structure
+
+Null counts are the start, not the answer. Distinguish:
+
+- **Random gaps** — sporadic nulls, roughly uniform across segments.
+- **Structural missingness** — a column populated only for some segment, after
+  some date, or by some source system. Cross-tab null rates against segments
+  and time to find these.
+- **Informative missingness** — where the *fact* that a value is missing
+  predicts the outcome (e.g., income missing for churned users). Flag it; it
+  may be a feature, or it may be leakage.
+
+Also check for disguised missing values: sentinel codes (0, -1, 999,
+"unknown", empty string) that aren't NULL.
+
+### 4. Distributions and outliers
+
+For key numeric columns: quantiles, histograms, and an outlier pass (IQR or
+similar). For categoricals: frequency tables and rare-level counts. Decide for
+each outlier cluster whether it is a data error, a unit mismatch, or a genuine
+tail — **never drop outliers before classifying them**; genuine tails are often
+the interesting part. Check skew before assuming any statistic (mean, std) is
+representative.
+
+### 5. Target definition, balance, and leakage
+
+If the data will feed a model:
+
+- **Define the target explicitly** (e.g., "churn = no order in 90 days after
+  cutoff") and check its **class balance** — a 2% positive rate changes the
+  whole modeling and evaluation approach downstream.
+- **Hunt for leakage**: any column recorded at-or-after the outcome
+  (cancellation reason, final status, updated_at aggregates), and proxies that
+  encode the outcome indirectly. Test: "would this value exist at prediction
+  time?" If unsure, trace how the column is produced. A too-good correlation
+  with the target is a leakage smell, not a win.
+
+### 6. Relationships, not just profiles
+
+Univariate profiles alone don't generate hypotheses. Examine bivariate
+structure: correlations among candidate features, and each candidate feature
+against the target (grouped rates, means by decile, simple cross-tabs). Note
+confounders — a feature↔target association may be explained by segment or
+time. This is where most real hypotheses come from.
+
+### 7. Write the hypotheses and hand off
+
+Close with a short findings document: data issues found, columns excluded and
+why (especially leakage suspects), and **explicit hypotheses phrased as
+testable statements** ("weekend signups churn more", "the price effect is
+driven by segment X") plus open questions for the data owners. Formal testing
+of those hypotheses is `statistical-analysis` territory; feature/training
+pipeline work is `ml-pipeline-design`.
+
+## Principles
+
+- **KISS**: value counts and group-by rates beat clever visualizations for
+  finding problems fast.
+- **YAGNI**: profile to the goal — an exhaustive 400-column report nobody reads
+  is not EDA.
+- **Honest accounting**: record what you did NOT check (columns skipped,
+  sample-size limits) in the findings doc.
+
+## Cross-skill boundaries
+
+- Bad data in a *pipeline or dashboard* (freshness, contracts, dbt tests,
+  lineage) → **data-quality** — that's an operational trust problem, not
+  exploration of an unfamiliar dataset.
+- Formal hypothesis testing, experiment design, significance → **statistical-analysis**.
+- Turning the analysis into scheduled production code → **notebook-to-production**.
+- Schema design for storing the data → **data-modeling**.

package/skills/exploratory-data-analysis/evals/evals.json

@@ -0,0 +1,43 @@
+{
+  "skill_name": "exploratory-data-analysis",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I just got a CSV export of our customer orders — about 200k rows, 30 columns — and I've never seen this data before. We eventually want a churn model out of it. Where do I start?",
+      "expected_output": "Should run a structured EDA workflow: profile columns first, examine missingness patterns and distributions, look at the target definition and class balance, flag potential leakage columns, and turn findings into explicit hypotheses — not jump to modeling.",
+      "assertions": [
+        "Profiles the dataset first (column types, ranges, cardinality, summary statistics) before giving any modeling advice",
+        "Examines missingness patterns and distinguishes random gaps from structural ones (e.g., a column only populated for some segment)",
+        "Checks distributions and flags outliers or skew with concrete methods (quantiles, histograms, IQR or similar)",
+        "Warns about target leakage — columns that would not be available at prediction time must be identified and excluded",
+        "Examines how the churn target would be defined and its class balance before any modeling",
+        "Looks at relationships between candidate features and the target, not just univariate profiles",
+        "Produces explicit hypotheses or follow-up questions from the findings rather than only reporting statistics"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "I need to understand a warehouse extract with 400 columns and 3 million rows by Friday, and pandas kills my laptop when I load it. What's the plan?",
+      "expected_output": "Should scale the EDA workflow instead of abandoning it: triage columns cheaply first, work on a representative sample or push aggregations to the warehouse, and prioritize by the analysis goal rather than exhaustively profiling everything.",
+      "assertions": [
+        "Recommends sampling or chunked/out-of-core processing instead of loading everything into memory",
+        "Notes the sample must be representative (random or stratified) and flags the caveat that rare events and outliers can be missed under sampling",
+        "Triages the 400 columns cheaply (types, null rates, cardinality) before deep-diving any of them",
+        "Prioritizes columns by relevance to the stated goal rather than profiling all 400 equally",
+        "Suggests pushing heavy aggregations down to the warehouse via SQL, or using a lazy/out-of-core engine (e.g., Polars, DuckDB, Dask)",
+        "Still covers the core EDA checklist (types, missingness, distributions, key relationships) on the reduced view"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Our finance dashboard has shown wrong revenue numbers all week — the nightly job loads orders into the warehouse and something is off upstream. Can you help me analyze the data and find the problem?",
+      "expected_output": "Should recognize this as a pipeline-level data-trust problem, not exploration of an unfamiliar dataset — hand off to the data-quality skill (dbt tests, freshness, schema drift, contracts, lineage) rather than starting a dataset-profiling workflow.",
+      "assertions": [
+        "Recognizes this as a data-quality / pipeline-trust problem rather than exploratory analysis of a new dataset",
+        "Hands off to or invokes the data-quality skill instead of running a generic EDA workflow",
+        "Points at concrete data-quality directions (dbt tests, source freshness, schema drift, upstream contract, lineage/blast radius) as the right path",
+        "Does not respond with a dataset-profiling/distributions workflow as the primary answer"
+      ]
+    }
+  ]
+}