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
- Match narrative: xG timeline (when did each team create chances?)
- Shot map: Location, xG value, outcome for each shot
- Passing network: Who connected with whom, average positions
- Pressing analysis: Where did each team win the ball back?
- Key events: Goals, red cards, substitution impact
Team season analysis
- Performance trajectory: Rolling xG, points, form over the season
- Style profile: Possession %, PPDA, directness, set piece reliance
- Squad analysis: Minutes distribution, key players by contribution
- Home vs away: Performance split
- Score state: How does the team play when winning vs losing?
Player analysis
- Per-90 stats: Normalise by minutes, not matches
- Percentile ranks: Where does this player rank among peers (same position, same league)?
- Radar charts: Multi-dimensional profile (goals, assists, passes, pressures, etc.)
- Progressive actions: Passes, carries, and runs that move the ball significantly forward
- Minimum minutes filter: 900 minutes (10 full matches) is a common threshold
Comparison analysis
- Define the question first. "Is Player A better than Player B?" is too vague. Better: "Who creates more high-quality chances from open play?"
- Control for context. Per-90 stats, adjust for team quality, league quality.
- Use appropriate baselines. Compare to positional averages, not all players.
- 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:
- State your question before looking at the data. Don't go fishing for interesting patterns.
- Report null results. "We found no significant difference" is a valid finding.
- Show the raw numbers alongside fancy metrics. xG is meaningless without goals for context.
- Be specific about what you're measuring. "Pressing intensity" measured how? Over what period?
- Acknowledge what the data can't tell you. Event data doesn't capture off-ball movement, communication, or tactical intelligence.
1---2name: nutmeg-analyse3description: 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.4---56# Analyse78Help the user explore and interpret football data. Adapt depth and approach to their experience level from `.nutmeg.user.md`.910## Accuracy1112Read 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.13## First: check profile1415Read `.nutmeg.user.md`. If it doesn't exist, tell the user to run `/nutmeg` first.1617## Adapt to experience level1819### Beginners2021Guide them step by step. Start with simple questions:22- "Which team scores the most goals?" (count goals, sort)23- "Who takes the most shots?" (filter shots, group by player)24- "Where do goals come from?" (plot shot locations)2526Avoid jargon. Explain xG before using it. Show them what the data looks like before analysing it.2728**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.2930### Intermediate3132They know the basics. Help with:33- Comparative analysis (this team vs league average)34- Contextual metrics (per-90, possession-adjusted)35- Multi-variable analysis (passing profile + pressing intensity)36- Basic visualisations (shot maps, pass networks, xG timelines)3738**Common intermediate mistake:** Confusing correlation with causation. High possession doesn't *cause* wins. Help them think about mechanisms.3940### Advanced / Professional4142Focus on rigour:43- Statistical significance (is this difference real or noise?)44- Controlling for confounders (opponent quality, game state, home/away)45- Model selection and validation46- Communicating uncertainty4748**Common advanced mistake:** Over-engineering. Sometimes a bar chart answers the question better than a neural network.4950## Analysis frameworks5152### Single match analysis53541. **Match narrative:** xG timeline (when did each team create chances?)552. **Shot map:** Location, xG value, outcome for each shot563. **Passing network:** Who connected with whom, average positions574. **Pressing analysis:** Where did each team win the ball back?585. **Key events:** Goals, red cards, substitution impact5960### Team season analysis61621. **Performance trajectory:** Rolling xG, points, form over the season632. **Style profile:** Possession %, PPDA, directness, set piece reliance643. **Squad analysis:** Minutes distribution, key players by contribution654. **Home vs away:** Performance split665. **Score state:** How does the team play when winning vs losing?6768### Player analysis69701. **Per-90 stats:** Normalise by minutes, not matches712. **Percentile ranks:** Where does this player rank among peers (same position, same league)?723. **Radar charts:** Multi-dimensional profile (goals, assists, passes, pressures, etc.)734. **Progressive actions:** Passes, carries, and runs that move the ball significantly forward745. **Minimum minutes filter:** 900 minutes (10 full matches) is a common threshold7576### Comparison analysis77781. **Define the question first.** "Is Player A better than Player B?" is too vague. Better: "Who creates more high-quality chances from open play?"792. **Control for context.** Per-90 stats, adjust for team quality, league quality.803. **Use appropriate baselines.** Compare to positional averages, not all players.814. **Acknowledge limitations.** Different roles, different teammates, different systems.8283## Visualisation guidance8485| Chart type | Best for | Football use case |86|-----------|---------|-------------------|87| Shot map | Spatial data on pitch | Where shots were taken, sized by xG |88| Pass network | Relationships | Who passes to whom, team shape |89| xG timeline | Match narrative | Running xG through a match |90| Radar chart | Multi-dimensional comparison | Player or team profiles |91| Bar chart | Ranking / comparison | League tables, top scorers |92| Heatmap | Density / frequency | Player touch maps, action zones |93| Scatter plot | Two-variable relationship | xG vs actual goals, creativity vs volume |94| Beeswarm | Distribution | Player stat distributions by position |9596### Visualisation principles9798- Label axes clearly. Include units.99- Always show what the data IS, not just what you want it to say.100- Use football pitch backgrounds for spatial data (mplsoccer in Python, ggsoccer in R).101- Colour choices: use team colours when comparing clubs, sequential palettes for values.102- Credit your data source.103104## Data honesty105106Football data can tell you whatever you want it to. Guard against this:1071081. **State your question before looking at the data.** Don't go fishing for interesting patterns.1092. **Report null results.** "We found no significant difference" is a valid finding.1103. **Show the raw numbers alongside fancy metrics.** xG is meaningless without goals for context.1114. **Be specific about what you're measuring.** "Pressing intensity" measured how? Over what period?1125. **Acknowledge what the data can't tell you.** Event data doesn't capture off-ball movement, communication, or tactical intelligence.
withqwerty