Delta Computation

Compute period-over-period deltas, percent changes, and trend direction from previously pulled metric files, producing a clean summary artifact.

When to use

• A prior task has already pulled raw metrics (e.g. daily or weekly exports) into files and you need to compare periods.
• Someone asks for week-over-week, month-over-month, or campaign-over-campaign change in a metric.
• You need to flag metrics that moved beyond a threshold (spikes, drops, plateaus) before reporting them.
• A trend summary or change log needs to be derived from two or more metric snapshots.

Tools

• read-file - loads the raw metric files (current period and prior period) that were pulled earlier.
• shell-execute - runs a small script to align periods, compute absolute and percent deltas, and derive trend direction.
• write-file - writes the resulting delta table or trend summary artifact for downstream reporting.

Playbook

1. Identify the two (or more) metric files to compare using read-file — confirm each covers a distinct, comparable period (same metric definitions, same granularity).
2. Parse both files with read-file and check they share the same schema (same columns/keys); if not, note the mismatch and stop rather than compare mismatched fields.
3. Use shell-execute to run a small script (Python, Ruby, or awk/jq depending on file format) that joins the two periods on the shared key (e.g. campaign, channel, date).
4. In the same shell-execute script, compute absolute delta (current minus prior) and percent delta (delta divided by prior, guarding against divide-by-zero when prior is 0).
5. Classify each row's trend direction (up, down, flat) using a small threshold (e.g. under 2% counts as flat) inside the shell-execute script.
6. Sort or highlight the largest movers (by absolute or percent delta) so the summary leads with what matters most.
7. Write the resulting delta table (with columns: metric, prior value, current value, absolute delta, percent delta, trend) to a new file using write-file.
8. If any input file was missing, empty, or malformed, do not fabricate numbers — write a note in the output file explaining what could not be computed and why.
9. Summarize the top movers and overall trend in your completion message, pointing to the artifact written with write-file as the source of truth.

Failure modes

• Input file missing or unreadable via read-file -> do not guess values; report which file is missing and stop.
• shell-execute script errors (schema mismatch, type errors) -> fix the join/parsing logic once; if it persists, write-file a note describing the mismatch instead of silently skipping rows.
• Prior-period value is zero, making percent delta undefined -> report absolute delta only and mark percent delta as "n/a" rather than dividing by zero.
• Periods are not actually comparable (different date ranges, different metric definitions) -> flag this explicitly in the output rather than computing a misleading delta.

Done when

• A delta artifact has been written via write-file containing prior value, current value, absolute delta, percent delta, and trend direction for each metric.
• Any metrics that could not be computed (missing data, undefined percent change) are explicitly noted rather than silently omitted.
• The largest movers are clearly identified so the summary can lead with the most relevant changes.