samuhs/mad-science
Hypothesis-driven data science skills: sharpen a hypothesis, write the experiment contract, slice it into a pipeline, implement it expectation-first in notebooks, review it, and turn results into an article.
Review the project docs and experiments for gaps between what is documented, what was implemented, and the state of the art. Use when the user wants a critical assessment of the whole project, wants to check for missing experiments, bad assumptions, or weak evidence.
Develop production-grade Jupyter notebooks for data science research that follow state-of-the-art code practices (cell structure, modularization, reproducibility) and are designed to transition cleanly into production artifacts (API, worker, DAG). Use when creating, restructuring, or reviewing data science notebooks.
Review experiment code and Jupyter notebooks on two axes in parallel sub-agents: standards (does the code follow the repo's documented coding standards?) and quality (reproducibility, fixed seeds, data leakage, security, scalability, error handling). Use when the user wants to review an experiment, notebook or ML pipeline before moving on.
Development guided by the scientific method and explicit expectations. Use when the user wants to build or validate an analysis/model test-first, states a "hypothesis", "expectation" or "assumption" about the data, or asks for a principled data-science workflow (hypothesis → prediction → verification).
Render a read-only interactive graph of an experiment pipeline doc: dependencies, status and critical path at a glance. Use when the user wants to see the experiment steps as a graph, or says 'experiment graph', 'graph the experiments', 'visualize the pipeline', 'experiment status', 'experiment dependencies' or 'picture of the stages'.
Break an experiment doc into small vertical slices (stages, phases, experiments) with goals, metrics, status and dependencies, tracked in docs/experiments-pipeline. Use when the experiment contract is settled and the user wants a run plan, wants to know which experiments can run in parallel, or wants to update experiment status.
Grill the user relentlessly about a data science or ML hypothesis until it is clear, falsifiable and tied to goal metrics: premises, baseline and success criteria. Use when starting an experiment, when the user wants to stress-test a hypothesis or idea, or says 'grill me', 'challenge my hypothesis' or 'is this testable'.
Implement or fix an experiment in a Jupyter notebook from its experiment doc and pipeline, expectation-first: run every cell, review the result with /exp-review, then commit. Use when the experiment is planned and it is time to write the code.
Investigate a question against high-trust primary sources and capture the findings as a Markdown file in the repo. Use when the user wants a topic researched, or to find the state of the art on a hypothesis.
Set up a repository for the mad-science data science skills: experiment tracker folder, domain glossary, agent instructions block and .env.example. Run once per repo before the other skills, or when the user says 'set up mad-science' or 'configure this repo for experiments'.
Send a Google Chat card through the webhook set in .env (GCHAT_WEBHOOK_URL) when the agent is waiting for human input, with the open question and the project name. Use to get pinged during long agent sessions, or when the user asks for Google Chat notifications.
Use when asked to generate, draft, or rewrite a scientific/technical article in Computer Science (conference paper, journal paper, or survey) from a topic/idea plus the repository's code, experiments, and results. Also use when asked to structure, review, or de-slop an existing draft. Triggers: "write the paper", "write an article", "generate the article from the repo", "turn this experiment into a paper", "review/reformat my draft".
Turn the current conversation into an experiment doc (hypothesis, premises, baseline, success metrics, experiment stories) and publish it to the project docs, with no new interview. Use after /hypothesys, or when the user says 'write the experiment doc', 'document this experiment' or 'turn this into a doc'.
Orientation map and canonical catalogue of the mad-science data science skills. Use when the user asks how the skills fit together, which command to run next, where to start an experiment, or needs a quick overview of the hypothesis-to-notebook flow.