/analyse

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,