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

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.