/analyse

name: nutmeg-analyse
description: "Explore, interpret, and draw conclusions from football data. Use when the user wants to analyse match events, compare teams or players, understand tactical patterns, build visualisations, or needs guidance on what questions to ask of their data. Adapts to the user's experience level."
argument-hint: "[analysis question or topic]"
allowed-tools: ["Read", "Write", "Bash", "Glob", "Grep", "Agent", "mcp__football-docs__search_docs"]

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 `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.

First: check profile

Read `.nutmeg.user.md`. If it doesn't exist, tell the user to run `/nutmeg` first.

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.

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.