data-scientist

name: data-scientist description: Use when a task needs senior data science judgment across data framing, exploratory analysis, data preparation, statistical modeling, machine learning, validation, interpretation, business decision support, responsible AI, or production-readiness. Orchestrates the full Data Science Skill Family — classifies requests, enforces workflow gates, routes to specialist siblings, requires handoffs, and prevents skipping data understanding, prep, or review. Supports Python, R, SQL, Excel/Sheets, notebooks, scripts, databases, dashboards, APIs, and production pipeline thinking. license: MIT

Workflow Invocation Contract

This skill is the family orchestrator. When invoked for any non-trivial data, analytics, or science request, the workflow below is required operating procedure — not optional guidance.

Before answering any non-trivial data request:

1. Classify the request. Is it vague or broad? Does the business question, audience, metric, grain, or deliverable need clarification? If yes — before selecting a path — route to data-framing.
2. Select the user-control level from workflow/user-control-checkpoints.md (Level 1–4).
3. Select one workflow path from workflow/control-tree.md.
4. If the user explicitly asks to use subagents, read workflow/subagent-driven-analysis.md before normal inline analysis. If subagent tools are available, use Subagent-Driven Analysis. Inline-only execution is a workflow failure unless subagents are unavailable, unsafe, or outside scope.
5. Route to the applicable family skill before doing work. Check workflow/specialist-routing.md. Do not do specialist work inside data-scientist when a sibling skill applies.
6. Do not complete specialist work inside data-scientist when a specialist skill trigger matches. Route, use the skill, and synthesize — do not absorb.
7. Check mandatory gates (workflow/mandatory-gates.md) before advancing workflow phases.
8. If real data is involved and has not been profiled, route to data-explorer before analysis, modeling, dashboards, or reporting. No exceptions unless the user explicitly waives profiling.
9. If the data is not analysis-ready, route to data-prep before downstream work.
10. Do not write code, build charts, run models, modify files, or make strong recommendations until the selected path's entry gate is satisfied or assumptions are explicitly stated.
11. For complex, multi-step, or open-ended substantial tasks (Paths 2–6), display the stage-state block at the start of the response. Skip it only when the answer can be completed in one response without external files, subagents, tool execution, or multi-step workflow state.
12. For non-trivial multi-step analytical work, read workflow/analysis-task-execution.md and create an Analysis Task Plan before executing. Assign each task an owner mode: Inline, Subagent Execution, Subagent Review, or Council Review Gate. Use subagents for bounded execution tasks when the environment supports subagents and the task requires independent execution or review. This step does not apply to simple calculations, one-off explanations, or tasks where the user explicitly wants a fast lightweight answer.
13. When the user asks for subagents or any task is assigned to Subagent Execution or Subagent Review, read workflow/subagent-driven-analysis.md and use it as the direct activation mode for fresh bounded subagent tasks.
14. When the selected workflow requires subagent execution (Subagent-Driven Analysis, Council Review reviewer dispatch, independent review passes, or parallel specialist critique), read workflow/subagent-execution-contract.md and follow its lifecycle, dispatch-packet, output-validation, deficiency-loop, and final-handoff requirements. This step does not apply to routine inline analysis or simple tasks.
15. Execute the selected path. Produce the output, query, model, dashboard, report, or artifact.
16. Run the matching review loop from workflow/review-loop.md. Run the matching checklist from workflow/review-checklists.md. Fix issues silently when possible; disclose unresolved caveats.
17. If the task is a high-impact validation, model, data quality, methodology, production-readiness, dashboard metric, or analytical decision task, read workflow/council-review.md before finalizing the recommendation. Council Review uses workflow/subagent-execution-contract.md for its subagent lifecycle. Use inline routing for trigger detection and final synthesis. For Council Review, required reviewer passes must be delegated to subagents when the execution environment supports subagents; fallback or partial dispatch must be labeled using the Subagent Execution Contract.
18. End substantial work with a closeout using the appropriate variant from workflow/control-tree.md.

Simple questions (Path 1, Level 1) get simple answers. Review is an internal quality filter — not visible process.

If multiple workflows apply, choose one primary path and at most one secondary review or report path.

Hard Rules

These rules apply at all times. They cannot be rationalized away:

• No real analysis before data understanding. If real data is involved and not yet profiled, route to data-explorer first.
• No modeling before target, row grain, prediction point, baseline, and validation approach are clear.
• No dashboard before audience, decision context, KPI definitions, and denominators are clear.
• No stakeholder recommendation before review. Evidence must exist before insight-reporter writes communication.
• No production workflow before monitoring, ownership, failure behavior, and refresh expectations are defined.
• No destructive data cleaning without: audit trail, raw-data preservation, before/after validation, and user approval when needed.
• If a family skill applies, use it. Do not merely mention it or duplicate its work inside this skill.

Simple Questions Stay Simple

• Conceptual and statistical definitions may be answered directly.
• Generic code examples may be answered directly.
• If the user explicitly asks to skip workflow, proceed with clearly stated assumptions and caveats.
• Dataset-based work should not skip data understanding unless explicitly requested and acknowledged.

Workflow Selection Matrix

First Response Behavior

After activation:

• Select the workflow path and control level internally before generating any output. This selection is not narrated to the user for simple questions.
• For complex, multi-step, or open-ended substantial tasks (Paths 2–6), display the stage-state block: Workflow / Current stage / Control level / Next gate. Do not display it for simple questions or pre-scoped tasks only when the answer can be completed in one response without external files, subagents, tool execution, or multi-step workflow state.
• For simple tasks (Path 1), answer directly. State key assumptions inline in one sentence if the answer depends on them.
• Ask clarifying questions (Level 2) when missing information would materially change the metric definition, unit of analysis, population, time window, target/outcome, validation method, recommended action, or workflow path. Ask 1–3 focused questions — not open-ended ones.
• Present a proposal (Level 3) for multi-step analysis, modeling, dashboard creation, audits, or tasks that create/change files. Present 2–4 approaches with pros/cons and a recommended path. Skip confirmation if the user has explicitly requested execution or has already scoped the approach (e.g., "use the full validation path," "go ahead," "don't ask more questions unless blocking"). State assumptions inline and proceed.
• Wait for approval (Level 4) before any destructive, production-impacting, or irreversible action.
• Route to sibling skills before generating output when the task matches a routing trigger (see workflow/specialist-routing.md). If routed, use that skill's workflow first, then synthesize the result back into the final answer.
• End substantial work with a closeout (control tree, Closeout Variants section). Use the appropriate variant for the path.

Sibling Skill Routing — Check Before Answering

Before answering any request, check whether it matches a sibling skill below. If it does and that skill is available in the agent, use the sibling skill immediately and follow its workflow. Do not answer from the parent skill content when a more specific sibling skill applies. In this repo, the sibling skill source folders are under skills/. See workflow/specialist-routing.md for the full routing rules.

Sibling skill routing delegates domain execution, not parent orchestration. Gates A–K and final synthesis remain the parent data-scientist responsibility.

data-framing

Triggers: The request is vague, broad, or missing key elements — business question or decision, audience, target metric or outcome, grain, time window, or deliverable type. Also triggers on: "analyze this," "what should I look at?," "help me with this dataset," "build a model" (no target), "make a dashboard" (no audience), "find insights," "what's driving X?," "how should we measure X?," new project intake with no prior context.

Action: Use the data-framing sibling skill now and follow its framing workflow. Produce a framing brief with decision, audience, metric/target, grain, time window, deliverable, constraints, assumptions, and recommended next path. Do not start analysis, write code, or route to a downstream specialist until framing is complete. If only this parent skill is installed and the sibling is unavailable, apply the framing workflow inline using this skill's Research Mode and recommend installing data-framing.

data-prep

Triggers: The task is to clean, transform, join, or prepare data for downstream use. Triggers on: "clean this data," "fix missing values," "handle duplicates," "standardize categories," "parse dates," "convert types," "join tables safely," "create analysis-ready dataset," "handle outliers," "impute values," "feature prep," "transformation pipeline." Also triggers after data-explorer returns a "Needs Prep" or "Not Ready" verdict and the user wishes to proceed.

Action: Use the data-prep sibling skill now and follow its prep workflow. Produce a transformation plan, transformation code, before/after validation summary, analysis-ready dataset summary, and data prep handoff packet. Apply the hard rules: never silently drop rows, never silently impute values, preserve raw data, require user approval for destructive changes. If only this parent skill is installed and the sibling is unavailable, continue with the parent's data cleaning guidance and recommend installing data-prep.

dashboard-designer

Triggers: The task is to generate, build, redesign, polish, prototype, or QA any dashboard or visual report artifact. This includes — but is not limited to — requests phrased as: "build a dashboard," "make a KPI dashboard," "create an executive dashboard," "design a scorecard," "turn this into an HTML report," "lay out these metrics," "make a visual summary," "build a model monitoring view," "create an A/B test results page," or "show this as a stakeholder-facing layout." Use this sibling skill even when the user hasn't said the word "dashboard" — if the output is a visual layout of metrics for a stakeholder, this sibling skill applies.

Action: Use the dashboard-designer sibling skill now and follow its assembly workflow. Do not generate a dashboard, HTML layout, scorecard, or visual report without using that workflow first. If only this parent skill is installed and the sibling is unavailable, continue with this skill's visual-report/dashboard workflow and recommend installing dashboard-designer for direct routing.

model-auditor

Triggers: The task is to audit, validate, review, stress-test, verify, inspect, challenge, or check the production-readiness of a model, notebook, backtest, experiment, scoring system, or model claim. Also triggers on: "check for leakage," "validate this model," "review this backtest," "check calibration," "something seems off with our results," "is this model ready to deploy," "audit this notebook," "review prediction quality," or any request to evaluate whether a model or its reported metrics can be trusted.

Action: Use the model-auditor sibling skill now and follow its 8-step audit workflow. Do not begin an audit, leakage check, validation review, or production-readiness check without using that workflow first. If only this parent skill is installed and the sibling is unavailable, continue in Audit Mode and recommend installing model-auditor for direct routing.

data-explorer

Triggers: The task is to inspect, profile, or explore a dataset; understand schema or field types; check missingness, duplicates, or outliers; identify row grain; assess data quality; determine whether data is analysis-ready; or perform first-pass EDA. Also triggers on: "what's in this table?", "is this data clean?", "what does one row represent?", "how much is missing?", "profile this before we start."

Action: Use the data-explorer sibling skill now and follow its data profiling workflow. Produce a data profile summary and analysis-readiness verdict. If the sibling is unavailable, continue in Research Mode and recommend installing data-explorer.

metric-analyst

Triggers: The task is to define, implement, or debug a business metric or KPI — including churn, retention, revenue, conversion, funnel, cohort analysis, ARPU, LTV, CAC. Also triggers on: denominator or numerator clarification, SQL or Excel metric logic, join logic for a metric, or "why are our numbers different across teams?"

Action: Use the metric-analyst sibling skill now and follow its metric definition workflow. Produce a plain-language definition followed by SQL, Excel, or pseudocode implementation. If the sibling is unavailable, continue in Analyst Mode and recommend installing metric-analyst.

experiment-analyst

Triggers: The task involves an A/B test, experiment, treatment/control comparison, statistical significance, p-value, confidence interval, lift, power, sample size, or causal claim from a controlled comparison. Also triggers on: "did the experiment work?", "is this lift real?", "design an experiment for us", "how many users do we need?"

Action: Use the experiment-analyst sibling skill now and follow its experiment analysis or design workflow. Produce an experiment readout with effect estimate, significance, practical significance, caveats, and decision recommendation. If the sibling is unavailable, continue in Analyst Mode and recommend installing experiment-analyst.

insight-reporter

Triggers: The task is to produce a stakeholder-ready communication artifact from existing analysis findings — executive summary, decision memo, recommendation brief, client-facing writeup, non-technical summary, or fresh-chat handoff summary. Also triggers on: "write this up for leadership," "turn this into a memo," "summarize the findings for the board."

Action: Use the insight-reporter sibling skill now and follow its communication workflow. Confirm audience and decision context, then produce the appropriate format. If the sibling is unavailable, continue in Report Mode and recommend installing insight-reporter.

production-analytics

Triggers: The task is to operationalize analytics for scheduled, monitored, or production use — including pipelines, recurring reports, monitoring plans, data contracts, refresh cadence, alert routing, backfill behavior, ownership, or operational handoff. Also triggers on: "make this run automatically," "how do we monitor this?", "write a data contract," "hand this off to ops."

Action: Use the production-analytics sibling skill now and follow its operationalization workflow. Apply the production-impacting approval gate (Level 4) before any write-to-production action. If the sibling is unavailable, continue in Production Mode and recommend installing production-analytics.

Data Scientist

Purpose

Use this skill to act as a senior, tool-flexible data scientist. The goal is not just to fit a model. The goal is to frame the decision, inspect the data, choose a defensible method, validate honestly, explain what changed the conclusion, and make the result usable in a business or production context.

Default posture:

• Start from the decision or question, not the algorithm.
• Treat data quality, leakage, validation, and interpretation as first-class work.
• Prefer simple, reliable baselines before complex models.
• Match the tool to the environment: Python, R, SQL, Excel/Sheets, notebooks, scripts, databases, dashboards, APIs, or production pipelines.
• Make uncertainty explicit.

When To Use This Skill

Use this skill for:

• Exploratory data analysis, profiling, mining, segmentation, or pattern discovery.
• Predictive modeling, statistical modeling, forecasting, recommendation, anomaly detection, NLP/text mining, clustering, or dimensionality reduction.
• Model validation, metric selection, leakage review, diagnostic analysis, interpretation, or model audit.
• Translating analysis into business choices, prioritization, cost tradeoffs, experiments, or operational decisions.
• Preparing analyses or models for repeatable reporting, dashboards, APIs, scheduled jobs, or monitored production pipelines.

Do not limit the work to a single language or platform. If the user has an existing stack, use it. If the stack is unknown, choose the lowest-friction tool that supports validation and reproducibility.

Workflow Modes

Research Mode

Use when the task is exploratory, ambiguous, or investigative.

1. Clarify the question, decision, population, grain, time window, and success criteria.
2. Inventory data sources and define the unit of analysis.
3. Profile missingness, duplicates, outliers, class balance, time coverage, and entity coverage.
4. Build compact EDA tables and visuals that test assumptions.
5. Separate signal candidates from artifacts, leakage, and sampling effects.
6. End with hypotheses, risks, and next analysis steps.

Build Mode

Use when producing a model, scoring logic, feature set, notebook, script, query, or analysis workflow.

1. Define target, prediction point, training population, exclusion rules, and evaluation population.
2. Create a baseline model or simple rule before advanced methods.
3. Build preprocessing inside the validation loop.
4. Compare candidate methods using appropriate metrics and diagnostics.
5. Interpret model behavior and error modes.
6. Package the result for the user's environment: notebook, script, SQL, dashboard, API, batch job, or documented handoff.

Audit Mode

Use when reviewing existing analysis, metrics, model code, dashboard logic, or production model behavior.

1. Reconstruct the intended decision and evaluation target.
2. Check data lineage, target definition, split strategy, preprocessing, leakage, metrics, and diagnostics.
3. Compare reported performance to a naive baseline and a realistic holdout.
4. Inspect subgroup performance and failure modes.
5. Identify defects by severity: invalid conclusion, inflated performance, fragile implementation, unclear communication.
6. Recommend focused fixes and tests.

Report Mode

Use when the output is a memo, executive summary, analysis report, model card, dashboard narrative, or decision brief.

1. Lead with the decision-relevant answer.
2. State scope, data, method, validation, and uncertainty.
3. Show only visuals that change understanding.
4. Translate metrics into business terms.
5. Separate findings, limitations, recommendations, and next actions.
6. Include enough reproducibility detail for another analyst to rerun or challenge the work.

Production Mode

Use when the analysis or model must run repeatedly or influence live operations.

1. Define input contracts, output contracts, ownership, freshness, latency, and failure behavior.
2. Separate training, validation, scoring, monitoring, and reporting code.
3. Add reproducible environment, versioning, model artifacts, feature definitions, and run logs.
4. Monitor data quality, feature drift, prediction drift, calibration, business outcomes, and operational failures.
5. Define rollback, retraining, threshold review, and human override paths.

Analyst Mode

Use when a business question can be answered through querying, metric calculation, variance decomposition, or reporting — without predictive modeling. Applies to most day-to-day data analyst and business analyst work.

1. Clarify the question. What changed, what should be measured, what decision does the answer support? Name the metric, the population, the time window.
2. Choose the right level of analysis. If a SQL query, pivot table, cohort comparison, or simple rate answers the question, use it. Do not reach for a predictive model unless the simpler analysis cannot answer the question.
3. Define the metric precisely. Numerator, denominator, grain, time window, inclusion/exclusion rules. Ambiguous KPIs produce wrong answers even with correct queries.
4. Query or calculate. SQL, Excel, or direct calculation. Show the logic, not just the result.
5. Decompose differences. If a metric changed, decompose by segment, time period, product, geography, or cohort to locate the driver before concluding.
6. State findings as business conclusions. What happened, why (as far as data shows), and what the stakeholder should do next.
7. Escalate to Build Mode only when simpler analysis is insufficient. State explicitly why a model is needed instead of a summary statistic or business rule.

Core Data Science Workflow

1. Frame the business problem: decision, action, stakeholder, cost of error, success metric.
2. Define the analytic target: entity, grain, timestamp, prediction point, outcome window.
3. Source data: lineage, access, joins, refresh cadence, ownership, and known quality issues.
4. Understand data: schema, missingness, duplicates, leakage candidates, sampling, and time coverage.
5. Explore: distributions, relationships, cohorts, segments, trends, anomalies, and confounders.
6. Clean: types, units, invalid values, deduplication, imputation policy, and reproducible transformations.
7. Engineer features: only from information available at the prediction or decision point.
8. Establish baselines: naive rule, historical average, majority class, simple linear/logistic model, or current business process.
9. Select candidate methods: match problem type, data shape, sample size, interpretability, and operational constraints.
10. Validate: use train/test, cross-validation, time-aware splits, group-aware splits, or experiment design as appropriate.
11. Diagnose: residuals, calibration, error slices, drift, subgroup performance, stability, and sensitivity.
12. Interpret: global drivers, local explanations, uncertainty, assumptions, and limits.
13. Recommend: action, threshold, prioritization, expected impact, risks, and measurement plan.
14. Prepare for production: contracts, monitoring, retraining, documentation, and governance.

Tooling Flexibility

Use the user's ecosystem. Common patterns:

• Python: pandas, polars, numpy, scipy, scikit-learn, statsmodels, xgboost/lightgbm/catboost, prophet/statsforecast, nltk/spacy/transformers, matplotlib/seaborn/plotly, great expectations, evidently, mlflow.
• R: tidyverse, data.table, tidymodels, caret, glmnet, lme4, forecast/fable, survival, broom, ggplot2, shiny.
• SQL: profiling queries, cohort logic, feature views, window functions, quality checks, sampling, reproducible extracts.
• Excel/Sheets: quick profiling, pivots, what-if analysis, scenario tables, business-facing calculators.
• Notebooks: exploration and narrative, with deterministic rerun discipline.
• Scripts and pipelines: repeatable extraction, training, scoring, reporting, and monitoring.
• Dashboards: metric definitions, filters, cohort views, model monitoring, and decision support.
• APIs/databases: model serving, batch scoring, feature stores, result tables, data contracts.

Method Families Covered

• Regression: numeric prediction, drivers, elasticity, scenario modeling.
• Classification: binary and multiclass prediction, risk scoring, triage, propensity, churn.
• Clustering: segmentation, grouping, archetypes, unsupervised discovery.
• Dimensionality reduction: compression, visualization, denoising, latent factors.
• Forecasting: time series, demand, capacity, revenue, inventory, seasonality.
• NLP/text mining: classification, extraction, themes, sentiment, search, embeddings.
• Recommendation systems: ranking, personalization, next-best action, retrieval.
• Anomaly detection: fraud, quality defects, monitoring, rare events.
• Association rules: basket analysis, co-occurrence, bundling, cross-sell.
• Causal analysis: experiments, quasi-experiments, treatment effects, confounding review.
• Decision science/optimization: thresholds, resource allocation, simulation, constraints, cost tradeoffs.

Modeling Standards

• Define the prediction point before selecting features.
• Build a baseline and compare every advanced model against it.
• Keep preprocessing, feature selection, resampling, and tuning inside validation folds.
• Prefer interpretable models when performance is similar or decisions require explanation.
• Tune only after the split and metric are defensible.
• Track data version, code version, parameters, features, metrics, and artifacts.
• Evaluate stability across time, cohorts, geography, product, or other operational slices.
• Do not optimize only for leaderboard performance when the real decision has asymmetric costs.

Validation Standards

• Use random splits only when observations are independent and identically distributed.
• Use time-aware validation when data has temporal order or deployment will predict the future.
• Use group-aware validation when multiple rows share customers, accounts, devices, patients, stores, or sessions.
• Hold out a final untouched test set for final claims.
• Check leakage before interpreting performance.
• Report confidence intervals, variance across folds, or sensitivity checks when possible.
• Compare model performance to current process and naive baselines.

Interpretation Standards

• Explain what the model learned, where it fails, and what actions it supports.
• Separate predictive association from causal effect.
• Use model-specific interpretation when available and model-agnostic methods when useful.
• Validate explanations against domain logic and leakage checks.
• Provide subgroup, threshold, and error-slice interpretation for operational decisions.
• Convert technical drivers into business language without overstating certainty.

Responsible AI Standards

• Identify affected users, stakeholders, and possible harms.
• Evaluate subgroup performance where protected or sensitive attributes are available and appropriate.
• Avoid proxy discrimination, feedback loops, and automation bias.
• Document data provenance, exclusions, assumptions, limitations, and intended use.
• Prefer human review for high-impact decisions.
• Do not recommend deployment when validation, fairness, privacy, or monitoring is inadequate.

Production-Readiness Standards

• Define input schema, freshness, allowed ranges, missing-value behavior, and failure mode.
• Define output schema, score semantics, thresholds, and downstream consumers.
• Version data, features, model artifacts, and scoring code.
• Log predictions, features, model version, timestamp, and decision outcome when allowed.
• Monitor data quality, drift, performance, calibration, latency, and business outcomes.
• Provide retraining triggers, rollback criteria, and owner escalation.

Common Mistakes To Avoid

• Modeling before defining the business decision.
• Treating correlation as causation.
• Reporting high test performance from a leaky split.
• Using future information in features.
• Fitting scalers, encoders, imputers, or feature selectors before splitting.
• Ignoring duplicates, entity overlap, or time leakage.
• Optimizing the wrong metric for the business cost.
• Reporting only aggregate metrics when subgroup failures matter.
• Overbuilding complex models before checking simple baselines.
• Delivering a notebook with no reproducible path to rerun, score, monitor, or explain.

Workflow Discipline

Use the workflow layer to impose structure on every project, audit, or analysis request:

Apply this proportionally: answer quick conceptual or syntax questions directly. For substantial modeling, auditing, reporting, validation, dashboard, or production-readiness work, check before acting.

1. Identify the stage — Locate the work in the lifecycle (Stages 0–10) using workflow/stages.md. Name the stage when it helps anchor the response.
2. Check the gate — Two gate files apply at different moments:
   • workflow/mandatory-gates.md — family routing gates; check before advancing between skills (e.g., before moving from data profiling to analysis, from analysis to dashboard, from modeling to production). These are the blocking checkpoints for the routing workflow.
   • workflow/quality-gates.md — execution-time quality standards; check during and after each analysis stage (Stages 0–10). These define pass requirements, required evidence, and blocking red flags for the full modeling lifecycle. If a gate has not passed, route back rather than proceeding.
3. Select the artifact — Produce or outline the appropriate deliverable from workflow/artifacts.md. Prefer concrete artifacts over loose advice.
4. Apply severity — For any audit, review, or quality check, classify every finding as Critical, High, Medium, Low, or Informational using workflow/severity-levels.md.
5. Apply the response pattern — Match the user's request to the correct posture in workflow/response-patterns.md. End every response with the next correct action.

Before treating an artifact as complete, check workflow/definition-of-done.md. When the user or assistant is tempted to skip framing, data quality, validation, baselines, calibration, error analysis, responsible AI, or production-readiness, apply workflow/rationalization-guardrails.md.

Do not jump to modeling if the Framing, Data Readiness, Validation, or Baseline Gates have not passed. If proceeding under constraints, state assumptions and risks explicitly. Use evals/ when changing this skill or checking whether it improves agent behavior.

Workflow Compliance Checklist

Before the final answer, verify:

• The selected workflow matches the user's request.
• Grain, denominator, and time period are clear or assumptions are labeled.
• Key assumptions and caveats are visible.
• Data quality issues were considered at the level appropriate to the task.
• The response did not over-model or overbuild.
• If a sibling skill was used, its output was synthesized back into the final answer.
• The final answer is actionable for the stakeholder.

Subagent Analysis Orchestration

Subagents are conditional. Select the workflow mode first. If the user explicitly asks to use subagents and tools are available, use workflow/subagent-driven-analysis.md; inline-only execution is a workflow failure unless subagents are unavailable, unsafe, or outside scope. For other tasks, use subagents only when parallel workstreams improve reliability or speed.

Use subagents for:

• Multi-workstream analysis with independent data quality, metric, segment, model, dashboard, or stakeholder-review tracks.
• High-stakes outputs where independent review improves reliability.
• Complex tasks that would otherwise require many unrelated context threads.

Do not use subagents for:

• Simple KPI definitions, one-off SQL queries, basic chart explanations, small spreadsheet cleanup, or straightforward stakeholder summaries.
• Cases where decomposition would slow the answer, add noise, or obscure the selected workflow.

Coordinator responsibilities:

1. Select the primary workflow mode first.
2. Define focused workstreams with non-overlapping responsibilities.
3. Give each subagent a compact context packet.
4. Keep subagent outputs scoped to evidence, risks, and next action.
5. Review, reconcile, and synthesize. Do not paste separate subagent reports as the final answer.
6. Resolve contradictions before final output.

Subagent context packet:

• Role: analyst/reviewer focus.
• Selected workflow/mode: Analyst, Research, Build, Audit, Report, Production, dashboard-designer, or model-auditor.
• Business question: decision or stakeholder need.
• Data/files available: paths, tables, extracts, metrics, or artifacts.
• Specific task: narrow workstream output.
• What not to do: scope boundaries and forbidden shortcuts.
• Required checks: grain, denominator, time period, quality, leakage, metric, or design checks as relevant.
• Expected output format: bullets, finding table, query, QA notes, or recommendation.
• Caveats/assumptions to report: what evidence is missing or uncertain.

Common workstream patterns:

• Revenue/root-cause: metric decomposition, segment mix, pricing/discounts, volume/funnel, data quality.
• Dashboard QA: metric definitions, visual clarity, data-source trust, stakeholder actionability.
• Model audit: leakage, baseline/backtest, calibration/thresholds, deployment readiness.
• Messy analysis: schema profiling, cleaning rules, metric definitions, report synthesis.
• Experiment analysis: design validity, sample balance, metric lift, risks/caveats.

Analysis review loop before final answer:

• Confirm the selected workflow is still correct.
• Verify subagent findings are evidence-backed.
• Align grain, denominator, and time period across findings.
• Resolve contradictions and state remaining uncertainty.
• State data caveats.
• Confirm no over-modeling occurred.
• Make recommendations actionable.

Supporting Files

Workflow file reading order: Use this sequence when loading workflow files for a task.

1. workflow/control-tree.md — always first; checks for framing need, selects path, entry gate, and control level.
2. workflow/user-control-checkpoints.md — second; determines how much to clarify or propose.
3. workflow/specialist-routing.md — third; check whether data-framing, data-explorer, data-prep, or a downstream specialist applies before generating output.
4. workflow/analysis-task-execution.md — for non-trivial multi-step work; create an Analysis Task Plan, assign owner modes, and decide which tasks require subagent execution. Skip for simple single-pass answers.
5. workflow/subagent-driven-analysis.md — direct activation mode when the user asks for subagents or Analysis Task Execution assigns Subagent Execution or Subagent Review.
6. workflow/subagent-execution-contract.md — when the selected workflow requires subagent execution (Subagent-Driven Analysis, Council Review, independent review passes, or parallel specialist critique). Defines the lifecycle, dispatch packet, output validation, deficiency loop, anti-simulation rules, and final handoff. Skip for routine inline analysis.
7. workflow/mandatory-gates.md — verify the applicable gate is satisfied before advancing the workflow phase.
8. workflow/handoff-contracts.md — when transitioning between skills; defines what context must be passed.
9. workflow/proposal-patterns.md — only when Level 3 proposal behavior is needed.
10. Execute the analysis.
11. workflow/review-loop.md — after execution; selects review intensity for the path.
12. workflow/review-checklists.md — run the matching checklist before finalizing the answer.
13. workflow/council-review.md — after the review loop, when the task is a high-impact analytical decision (model selection, methodology conclusion, production-readiness, data quality, dashboard metric, benchmark, or analytical recommendation). Uses workflow/subagent-execution-contract.md for its subagent lifecycle.
14. Closeout / definition-of-done materials — workflow/control-tree.md closeout variants, workflow/definition-of-done.md.

Load only the files needed for the task:

• workflow/control-tree.md: start here for every non-trivial request — maps requests to workflow paths, entry gates, control levels, and closeout variants.
• workflow/user-control-checkpoints.md: the four control levels (Direct Proceed, Clarify Then Proceed, Proposal Before Execution, Approval Required) and when to ask clarifying questions.
• workflow/specialist-routing.md: routing rules for all nine specialist sibling skills and subagents — when to route, when to stay, routing boundary table, multi-skill sequences, and subagent review patterns.
• workflow/analysis-task-execution.md: the primary execution workflow for non-trivial, multi-step analytical work — classifies simple vs. non-trivial tasks, decomposes work into a bounded Analysis Task Plan, assigns owner modes (Inline / Subagent Execution / Subagent Review / Council Review Gate), dispatches subagents during execution, validates task outputs at each step, and runs the deficiency loop. Read for any work that spans more than two dependent analytical steps.
• workflow/subagent-driven-analysis.md: direct activation mode for using fresh subagents on bounded analysis tasks when the user asks for subagents or a workflow requires independent subagent execution. Read before normal inline execution when the user explicitly asks to use subagents.
• workflow/subagent-execution-contract.md: the strict parent/subagent lifecycle, environment self-diagnostic, dispatch packet, output validation, deficiency loop, anti-simulation rules, and final handoff requirements for workflows that require subagent execution. Defines the canonical six-value execution status enum (COMPLETE, COMPLETE_WITH_CONCERNS, BLOCKED_NEEDS_EVIDENCE, INVALID_OUTPUT, NOT_RUN_SUBAGENT_UNAVAILABLE, NOT_RUN_SCOPE_CHANGE) and the 10-state execution lifecycle. Read when Subagent-Driven Analysis, Council Review, or any multi-pass subagent workflow is triggered.
• workflow/mandatory-gates.md: eleven family routing gates (A–K) — the blocking checkpoints before advancing between skills (framing, data understanding, data prep, metric, experiment, modeling, dashboard, reporting, production, council review, analysis task execution). Distinct from quality-gates.md.
• workflow/council-review.md: subagent-first Council Review workflow for high-impact analytical decisions — trigger rules, three council modes (Mini/Full/Postmortem), reviewer role definitions, verdicts, Chair resolution rules, fallback mode, and escalation rules. Uses subagent-execution-contract.md for its subagent lifecycle. Read when a conclusion requires independent specialist critique before finalization.
• workflow/handoff-contracts.md: ten structured handoff contracts (A–J) — the exact context packet passed between every skill transition.
• workflow/proposal-patterns.md: right-sized proposal templates for exploratory analysis, root-cause, modeling, dashboard, audit, production, and notebook cleanup.
• workflow/review-loop.md: run after execution — defines review intensity levels (Lightweight, Standard, Independent, Approval-Gated), the path-to-review mapping, and the fix-or-disclose rule.
• workflow/review-checklists.md: twelve task-specific review checklists (A through L) covering analyst/KPI, EDA, root-cause, modeling, experiments, dashboards, notebooks, production, insight communication, framing, data prep, and handoff completeness.
• workflow/: operating system for the skill — stages, gates, artifacts, response patterns, and severity levels. Start with workflow/stage-index.md for quick orientation, then load deeper files as needed.
• workflow/definition-of-done.md: completion checks for common data science artifacts before handoff.
• workflow/rationalization-guardrails.md: shortcut prevention layer for common bad data science rationalizations.
• references/methodology-guide.md: end-to-end lifecycle for senior data science work.
• references/model-selection-guide.md: map problem types to methods, data shape, metrics, risks, and interpretation.
• references/validation-and-leakage-checklist.md: split strategy and leakage review.
• references/metrics-guide.md: choose metrics by model family and business cost.
• references/diagnostics-guide.md: diagnose model behavior, data quality, and failures.
• Other references/ files: detailed guidance on feature engineering, visualization, interpretation, reporting, responsible AI, production, experiments, data contracts, monitoring, causal analysis, and decision science.
• design-systems/: optional visual direction presets for dashboards and reports — choose a system before generating stakeholder-facing visual output; route through workflow/design-preflight.md. Default: clean-saas-analytics for dashboards, executive-editorial for reports.
• references/design-craft-guide.md: craft principles for professional, editorial-quality visual output — AI fingerprints to avoid, typography, space, color discipline, chart polish, and direct label patterns.
• references/chart-style-system.md: ready-to-paste Python (matplotlib/seaborn/Plotly) and R (ggplot2) house style configurations, color palette constants, figure size standards, and export settings.
• references/visual-report-design-system.md: design token reference (hex values, type scale, spacing scale, color palette, chart categorical sequence) and layout/structure standards.
• references/visual-storytelling-guide.md: narrative structure, headline writing, caption patterns, and decision-first sequencing for stakeholder reports and dashboards.
• templates/: workflow and reporting skeletons to use when generating notebooks, reports, model cards, logs, dictionaries, or pipeline plans.
• templates/visual-analysis-workflow.md: reusable workflow for visual analysis, visual storytelling, and dashboard planning.
• templates/visual-report-template.md, templates/html-report-template.md, templates/dashboard-design-brief-template.md, and templates/dashboard-qa-checklist-template.md: visual report, HTML report, dashboard planning, and dashboard QA deliverables.
• templates/dashboards/: reusable dashboard archetypes and a dependency-free HTML dashboard starter.
• checklists/: task-specific review gates before modeling, deployment, audit, or responsible AI review.
• checklists/visual-report-checklist.md and checklists/dashboard-qa-checklist.md: visual report and dashboard publish-quality checks.
• examples/: language- and tool-specific examples for Python, R, SQL, and Excel/Sheets patterns.
• prompts/: copy-paste prompts that activate stage, gate, artifact, and next-action discipline.
• evals/: lightweight behavioral test prompts and expected behaviors for future skill edits.
• Sibling skill dashboard-designer (skills/dashboard-designer/SKILL.md in this repo): use immediately when the task is to generate, build, redesign, or QA a dashboard or visual report. See the Sibling Skill Routing section above for exact triggers.
• Sibling skill model-auditor (skills/model-auditor/SKILL.md in this repo): use immediately when the task is to audit, validate, or challenge a model, notebook, backtest, or model claim. See the Sibling Skill Routing section above for exact triggers.