---
name: nutmeg-analyse
description: "Explore and interpret football data, and judge players or teams from stats: rankings, 'who is the best', 'is he a poor finisher', comparisons, headlines and social posts about stats. Use for match events, team and player comparisons and tactical patterns, at the user's level."
argument-hint: "[analysis question or topic]"
allowed-tools: ["Read", "Write", "Bash", "Glob", "Grep", "Agent", "mcp__plugin_nutmeg_football-docs__search_docs", "mcp__football-docs__search_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"]
---

# Analyse

Help the user explore and interpret football data. Adapt depth and approach to their experience level from `.nutmeg.user.md`.

## Accuracy

Read and follow `${CLAUDE_PLUGIN_ROOT}/docs/accuracy-guardrail.md` before answering any question about provider-specific facts (IDs, endpoints, schemas, coordinates, rate limits). Always use `search_docs` — never guess from training data.

When you report or compare a metric that has a football-docs metric card (`list_metrics`), read it with `get_metric` and name the variant ID; do not compare values from different variants, and say so when two sources disagree because they use different variants.
## First: check profile

Read `.nutmeg.user.md`. If it doesn't exist, continue with sensible defaults (Python and pandas, intermediate level) and suggest running `/nutmeg` setup at the end.

## Adapt to experience level

### Beginners

Guide them step by step. Start with simple questions:
- "Which team scores the most goals?" (count goals, sort)
- "Who takes the most shots?" (filter shots, group by player)
- "Where do goals come from?" (plot shot locations)

Avoid jargon. Explain xG before using it. Show them what the data looks like before analysing it.

**Common beginner mistake:** Drawing conclusions from tiny samples. A player with 2 goals from 3 shots doesn't have a 67% conversion rate worth reporting. Always flag sample size.

### Intermediate

They know the basics. Help with:
- Comparative analysis (this team vs league average)
- Contextual metrics (per-90, possession-adjusted)
- Multi-variable analysis (passing profile + pressing intensity)
- Basic visualisations (shot maps, pass networks, xG timelines)

**Common intermediate mistake:** Confusing correlation with causation. High possession doesn't *cause* wins. Help them think about mechanisms.

### Advanced / Professional

Focus on rigour:
- Statistical significance (is this difference real or noise?)
- Controlling for confounders (opponent quality, game state, home/away)
- Model selection and validation
- Communicating uncertainty

**Common advanced mistake:** Over-engineering. Sometimes a bar chart answers the question better than a neural network.

## Analysis frameworks

### Single match analysis

1. **Match narrative:** xG timeline (when did each team create chances?)
2. **Shot map:** Location, xG value, outcome for each shot
3. **Passing network:** Who connected with whom, average positions
4. **Pressing analysis:** Where did each team win the ball back?
5. **Key events:** Goals, red cards, substitution impact

### Team season analysis

1. **Performance trajectory:** Rolling xG, points, form over the season
2. **Style profile:** Possession %, PPDA, directness, set piece reliance
3. **Squad analysis:** Minutes distribution, key players by contribution
4. **Home vs away:** Performance split
5. **Score state:** How does the team play when winning vs losing?

### Player analysis

1. **Per-90 stats:** Normalise by minutes, not matches
2. **Percentile ranks:** Where does this player rank among peers (same position, same league)?
3. **Radar charts:** Multi-dimensional profile (goals, assists, passes, pressures, etc.)
4. **Progressive actions:** Passes, carries, and runs that move the ball significantly forward
5. **Minimum minutes filter:** 900 minutes (10 full matches) is a common threshold

### Comparison analysis

1. **Define the question first.** "Is Player A better than Player B?" is too vague. Better: "Who creates more high-quality chances from open play?"
2. **Control for context.** Per-90 stats, adjust for team quality, league quality.
3. **Use appropriate baselines.** Compare to positional averages, not all players.
4. **Acknowledge limitations.** Different roles, different teammates, different systems.

## Visualisation guidance

| Chart type | Best for | Football use case |
|-----------|---------|-------------------|
| Shot map | Spatial data on pitch | Where shots were taken, sized by xG |
| Pass network | Relationships | Who passes to whom, team shape |
| xG timeline | Match narrative | Running xG through a match |
| Radar chart | Multi-dimensional comparison | Player or team profiles |
| Bar chart | Ranking / comparison | League tables, top scorers |
| Heatmap | Density / frequency | Player touch maps, action zones |
| Scatter plot | Two-variable relationship | xG vs actual goals, creativity vs volume |
| Beeswarm | Distribution | Player stat distributions by position |

### Visualisation principles

- Label axes clearly. Include units.
- Always show what the data IS, not just what you want it to say.
- Use football pitch backgrounds for spatial data (mplsoccer in Python, ggsoccer in R).
- Colour choices: use team colours when comparing clubs, sequential palettes for values.
- Credit your data source.

## Before you publish a claim

Read `${CLAUDE_PLUGIN_ROOT}/docs/metric-misuse.md` and check each stat against it. If the user asks you to write a claim a stat cannot support (a post, headline or case), say so first and propose the better measure; draft only what the evidence supports.

## Help the user understand

Follow `${CLAUDE_PLUGIN_ROOT}/docs/understanding.md`: explain results with the user's own numbers, offer an
explainer page they can edit and share at the moments it lists (a surprising result, a result they must explain
to others), and never change a method or drop a caveat after seeing the results without saying so.

## Data honesty

Football data can tell you whatever you want it to. Guard against this:

1. **State your question before looking at the data.** Don't go fishing for interesting patterns.
2. **Report null results.** "We found no significant difference" is a valid finding.
3. **Show the raw numbers alongside fancy metrics.** xG is meaningless without goals for context.
4. **Be specific about what you're measuring.** "Pressing intensity" measured how? Over what period?
5. **Acknowledge what the data can't tell you.** Event data doesn't capture off-ball movement, communication, or tactical intelligence.