Forward Impact Engineering

Chart a Metric and Check Variation

You need to chart a metric and see whether the latest point is within expected variation. fit-xmr reads a time-series CSV, computes natural process limits from the data itself, and tells you whether the newest observation is routine noise or worth investigating.

No external targets required. The limits come from how the metric actually behaves.

Prerequisites

  • Node.js 18+
  • A CSV with at least 15 data points (fewer points are accepted but limits will not be computed)

Prepare the CSV

fit-xmr expects the header date,metric,value,unit,run,note with one row per observation: 

date,metric,value,unit,run,note
2026-01-06,cycle_time,4.2,days,,
2026-01-07,cycle_time,3.8,days,,
2026-01-08,cycle_time,5.1,days,,first Monday spike
Field Required Notes
date yes ISO 8601 (YYYY-MM-DD). Sort key.
metric yes Metric name. One CSV may carry multiple metrics; they are grouped.
value yes Numeric. Non-numeric values are rejected by validate.
unit yes Free text (count, days, pct, ...). Empty unit is rejected.
run no URL or identifier of the run that produced this observation.
note no Free text. Use it to record what you discovered when a signal fires.

Validate the file before analysis:

npx fit-xmr validate observations.csv

A non-zero exit code means the file does not match the schema.

Chart a single metric

Render the chart to see where every point falls relative to the limits: 

npx fit-xmr chart observations.csv --metric cycle_time

When the CSV carries exactly one metric, --metric is optional.

The output is a 14-line X+mR chart:

 UPL 12.5 ──────────────────────────────●───────────────
          │
+1.5σ 9.4 │        ·           ·  ·              ·
    μ 6.4 ┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
-1.5σ 3.4 │  ·  ·     ·  ·  ·        ·     ·  ·     ·  ·
          │
  LPL 0.3 ──────────────────────────────────────────────

  URL 7.5 ─────────────────────────────────●────────────
          │                    ·        ·
    R 2.3 ┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
          │     ·  ·  ·  ·  ·     ·  ·        ·  ·  ·  ·
      0.0 ──────────────────────────────────────────────
             1  2  3  4  5  6  7  8  9 10 11 12 13 14 15
  • Top half (X chart) -- each observation against the natural process limits and zone boundaries. · is routine; ● is a signal.
  • Bottom half (mR chart) -- consecutive point-to-point changes (|x_i - x_{i-1}|) against the upper range limit.
  • The shared time axis at the bottom serves both halves.

If your terminal mishandles Unicode, add --ascii:

npx fit-xmr chart observations.csv --metric cycle_time --ascii

Check whether the latest point is a signal

The analyze command combines the chart with limits, signals, and a classification: 

npx fit-xmr analyze observations.csv --metric cycle_time

For structured output that agents and scripts can parse:

npx fit-xmr analyze observations.csv --metric cycle_time --format json

The JSON report for each metric carries:

  • stats -- mu, R, sigmaHat, UPL, LPL, URL, zoneUpper, zoneLower.
  • latest -- the most recent observation as { date, value, mr }. The mr field is the moving range at that point, answering "is today's change unusual?"
  • signals -- keyed by rule (xRule1, xRule2, xRule3, mrRule1). Each entry carries slots (1-indexed positions) and a description.
  • classification -- stable, signals, chaos, or insufficient.

Read classification first. If it says stable, the latest point is within expected variation and no action is needed. If it says signals, look at the signals object to see which rules fired and where.

The three detection rules

fit-xmr applies the three rules from Wheeler's Understanding Variation:

Rule What it catches Applied to
X-Rule 1 A point outside the natural process limits (UPL or LPL) X chart
X-Rule 2 8 consecutive points on the same side of the centerline X chart
X-Rule 3 3 of any 4 consecutive points strictly beyond +/-1.5 sigma on one side X chart
mR-Rule 1 A moving range point exceeds URL mR chart

Treat each fired rule as a prompt to investigate, not a verdict.

When Rule 2 or Rule 3 fires, all participating slots are listed -- the run as a whole carries the diagnostic information, not just the final point.

Classifications

Classification Meaning What to do
stable No rules activated. The process is predictable. Leave it alone. Intervening makes things worse.
signals At least one X-chart rule activated. Investigate what changed.
chaos mR Rule 1 activated. The variation itself is unstable. Investigate the outsized moves before trusting any limits.
insufficient Fewer than 15 points. Limits are not computed. Keep recording.

Summarize across metrics

When you track multiple metrics in one CSV, summarize produces a markdown table: 

npx fit-xmr summarize observations.csv

Each row shows the metric, sample count, latest value, centerline, limits, classification, and a compact signal summary (R1x2, R2x8, etc.). Metrics with fewer than 15 points are listed separately so they do not crowd the active signals.

Orientation commands

List what is in the file before charting:

npx fit-xmr list observations.csv

Prints one row per metric with the observation count and date range.

What to do when signals appear

  1. Look at the chart. The visual pattern tells you more than the rule name. A Rule 2 run of 8 points above the centerline looks different from a single Rule 1 breach, and the response is different too.
  2. Annotate the CSV. Fill in the note field on the observation where the shift happened with what you discovered. The note is the durable record.
  3. Recompute after a confirmed shift. If the process has genuinely changed (a new deployment, a policy change), re-run analysis against post-shift data only. Otherwise the centerline averages across two different processes and the limits describe neither.

Do not set targets based on the natural process limits. They describe what the process does, not what it should do.

Do not react to individual data points when the classification is stable. Routine variation is common-cause noise; treating it as a problem and intervening makes the process worse on average.

Next steps

This guide covers the bounded task of charting a metric and reading the latest point. For the full workflow of building persistent process memory for an agent team -- recording observations over time, detecting level shifts, and acting on findings across daily cycles -- see Persistent Process Memory.