/research

name: nutmeg-research
description: "Run football analysis as a research project that shows its work: a question, a plan with reasons, a claim ledger tying every number to evidence. Use for work to publish or decide on (shortlists, match or opposition reports, memos, charts, threads) or when sourced numbers are asked for."
argument-hint: "[the question to research]"
allowed-tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "AskUserQuestion", "mcp__plugin_nutmeg_football-docs__search_docs", "mcp__football-docs__search_docs", "mcp__plugin_nutmeg_football-docs__resolve_entity", "mcp__football-docs__resolve_entity", "mcp__plugin_nutmeg_football-docs__get_provider_docs", "mcp__football-docs__get_provider_docs", "mcp__plugin_nutmeg_football-docs__get_metric", "mcp__football-docs__get_metric", "mcp__plugin_nutmeg_football-docs__list_metrics", "mcp__football-docs__list_metrics"]

Research

Work like a research assistant, not an autopilot. The user must be able to check every input, every query and every number, and see why each choice was made. A research project keeps that trail in files the user and their teammates can open.

Read and follow `${CLAUDE_PLUGIN_ROOT}/docs/accuracy-guardrail.md`. Provider facts come from football-docs and IDs from the Reep Register, never from memory.

The nutmeg command

Run every project command through the plugin's core, in exactly this form:

python3 "${CLAUDE_PLUGIN_ROOT}/core/nutmeg.py" <command> ...

Below, `nutmeg <command>` is short for that line. Run `nutmeg --help` or `nutmeg <command> --help` for the options. If `python3` is missing or older than 3.10, tell the user that research projects need Python 3.10 or newer, and continue the task without a project.

When to start a project

Start one when the user wants analysis to publish or to decide on: a shortlist, a match or opposition report, a memo, a chart or thread for social media, or any answer they ask to be sourced. Do not start one for a quick question ("what is PPDA?", "what is Opta's qualifier for a cross?"), a code fix or a lookup.

1. Start the project

1. Pick a short slug, for example `shortlist-lb` or `arsenal-press-2025`. 2. Run `nutmeg new <slug> --question "<the question in one sentence>"`. 3. If the command says there is no team policy for data in git, ask the user with AskUserQuestion: keep data, run outputs and figure snapshots out of git (recommended for licensed club or provider data), or commit them with the project. Then run it again with `--data-in-git no` or `--data-in-git yes`.

The project lives in `research/<slug>/` and becomes the active project. `nutmeg status` shows it.

4. Run `nutmeg config show` and note the user's levels for plan, run and publish (section 10). They decide where you stop for approval.

2. Write the question card

Fill in `research/<slug>/question.md`: the question, the decision or output it informs, the data and scope (competitions, seasons, providers) and what is out of scope. Use the user's words. If the decision it informs is unclear, ask one question.

3. Write the plan with reasons

Every choice of metric, filter, join, threshold, source, method or chart is a plan choice. Add each with:

nutmeg plan choose --kind metric --choice "npxG per 90" \
  --why "Penalties distort per-player comparisons." \
  --rests-type docs --rests-ref "football-docs: <provider> <doc title>"

• `--why` is one sentence a data scientist can check. Say why this option and not the obvious

other one.

• `--rests-type` and `--rests-ref` say what the reason rests on:
• `docs`: a football-docs result (name the provider and the doc you used);
• `metric`: a football-docs metric card variant, by its ID from `get_metric` (for example

`--rests-type metric --rests-ref ppda.statsbomb-hudl`); use it for any metric that has a card, so readers see exactly which definition a number uses;

• `registry`: a Reep Register record;
• `rule`: a practitioner rule, such as `${CLAUDE_PLUGIN_ROOT}/docs/metric-misuse.md`;
• `paper`: a paper or post;
• `claim`: an earlier claim in this ledger;
• `user`: the user's instruction, quoted.
• Never invent a source. If nothing supports a choice, say so in the reason and use `user` only

when the user asked for it.

Run `nutmeg plan check` and fix what it reports. Make the choices before you run anything: the plan locks automatically at the first `nutmeg run`, and that locked plan is the primary specification. Choices added or changed later are allowed, but the publish card and the workspace list them as made after the lock (`nutmeg plan diff`). Then follow the user's plan level:

• L1 or L2: show the user the plan and ask them to approve or change it before you fetch or compute

anything.

• L3: show the plan with its reasons and carry on; the user can stop you at any time, and every run

still goes through the gate.

4. Run the analysis through the gate

For data from a scrape, a download or an unknown source, record it first with `nutmeg data add <file> --source "<where it came from>"`: its profile reports duplicated rows, repeated IDs and empty columns, which you then deal with (and say how) before analysis.

Put each analysis step in a `.py`, `.R` or `.sql` file in the repository, then run it with:

nutmeg run analysis.py --input data/events.csv --sql queries/shots.sql -- --season 2025

• `--input` once for each data file or folder the step reads. Nutmeg hashes each one.
• `--sql` once for each SQL file the script runs, so the user sees the exact query.
• `--sends host:columns` for any data the step sends to an outside service, for example

`--sends api.example.com:player_id,minutes`.

• Arguments after `--` go to the script.
• Write output files to the folder in `$NUTMEG_OUTPUT_DIR`, so the run records them.

Run `nutmeg run` on its own: no `&&`, `;`, pipes or redirects. Before it runs, the user sees a gate card with the services and data the step uses,