Investigate
Find out why the metric in "$ARGUMENTS" moved, in an order that catches broken data before it gets explained.
Compute with code. Perform every calculation (totals, balances, ratios, variances, projections) with a script — Bash, Python or a spreadsheet formula written to a file — and include the computation alongside the result. Never do arithmetic mentally.
Prerequisites
The data: the metric's series and the rows or segment totals behind it, as files or pasted tables. When $ARGUMENTS or the request names a project, use that name as <project> whether or not its folder exists yet in .singularskills/analytics/ (create it when you write). With no project named: with exactly one folder there, use it; with several, ask which; with no folder at all, ask for a project name.
Read .singularskills/analytics/<project>/02-metrics.md for the metric's definition and 03-data.md for known data issues, when they exist.
Append this line to .singularskills/log.jsonl before you write the investigation (create the folder and file if missing): {"ts":"<ISO timestamp>","skill":"analytics-investigate","workflow":"analytics","phase":null,"project":"<project>","event":"started","artifact":"investigations/<date>-<slug>.md","note":""}, where <date> is today as YYYY-MM-DD and <slug> is two to four words naming the metric, never a person.
Process
Size the change: the metric before and after, the dates, and whether the move is outside its normal range (compare with the same span in earlier periods).
Rule out data problems before any cause:
- a tracking or logging change (an event renamed, a tag removed, a new app version)
- late or missing data in the latest period
- a definition change (a filter, a time zone, an exclusion) during the period
- duplicates or test traffic If one explains the move, stop: report it as the cause and say what to fix.
Decompose the change with a script written to
.singularskills/analytics/<project>/and included beside the results. Scripts read the user's files where they keep them and write only aggregates (counts, sums, rates and intervals): no row-level data, names, emails or raw IDs go into any file under.singularskills/. For a ratio or average, split the change into mix (segments' shares changed) and rate (the metric changed within segments), asreferences/metric-definitions.mdshows; then the segments in the metric's definition (platform, country, channel, plan, new versus returning), ranked by their contribution to the change.List candidate causes for what the decomposition shows: releases, campaigns, pricing, seasonality, outages, competitor moves, external events. For each, the evidence for and against from the data and the user's notes, and a likelihood (likely, possible, unlikely).
Say what would confirm the top cause: the check, the cut of data or the experiment that would settle it.
Write the investigation to
.singularskills/analytics/<project>/investigations/<date>-<slug>.mdwith sections Change, Data checks, Decomposition, Candidate causes and To confirm.
Output
The investigation written to .singularskills/analytics/<project>/investigations/<date>-<slug>.md. Present the most likely explanation first, with whether it is a data problem, a mix shift or a real change in behaviour, and what would confirm it.
After you have written the investigation, append the started line of Prerequisites to .singularskills/log.jsonl with "event":"finished": {"ts":"<ISO timestamp>","skill":"analytics-investigate","workflow":"analytics","phase":null,"project":"<project>","event":"finished","artifact":"investigations/<date>-<slug>.md","note":""}.
The investigation opens with this frontmatter (agent is the agent you run in, or unknown; this utility has no gate, so phase is null and gate is none):
---
skill: analytics-investigate
workflow: analytics
phase: null
project: <project>
started: <ISO timestamp>
finished: <ISO timestamp>
agent: <the agent you run in, or "unknown">
gate: none
---
The investigation ends with ## Decisions and ## Open questions, in this shape:
## Decisions
- <what was chosen> — <why> — <what was rejected>
## Open questions
- <what the next phase or a reviewer must settle>