Context Compare

Skill: Context compare (with and without)

Purpose

Measure what a piece of context is doing, instead of asserting it. Run the same question two ways, once without the context (for example, no metric definition) and once with it, and report the delta: did the spread collapse, did the runs start citing the definition, did the verdict go from drifts to stable. The setup whose presence collapses the drift is the context that moves the answer. Convergence is stability, not correctness.

Invocation

/context-compare "<the question>" --with <the definition> [N] Default N = 5. The context under test is a meaning-only definition, usually a metric definition: the user states it in conversation, points at a definition YAML file, or names an entry already in the metric dictionary. The baseline is the analyst with that definition absent from the dictionary.

Example: /context-compare "What's our retention rate?" --with "Retention Rate (30d): share of accounts at least 30 days old that were active in the trailing 30 days"

How to run it

This skill is glue plus bookkeeping, and the whole procedure is manual: you stage the definition into the active dataset's metric dictionary, run the reliability procedure once per arm, compute the delta between the two arms, and restore the dictionary. The run step is the reliability skill (a sibling of this one); the per-arm statistics come from that skill's bundled script. The user never types a command; you do each step. This skill ships no scripts of its own.

Script path. The stats script is bundled with the reliability skill: helpers/stats/reliability_stats.py (the same module the reliability skill uses). If the import fails (some sandboxed environments): read the script file from the reliability skill, write a copy into a scripts/ folder inside the working folder, and run it from there. The script is self-contained. In every case run it from the working-folder root, so its audit-log append lands in .knowledge/reliability/log.jsonl.

Step 0 - back up the metric dictionary

Everything below edits .knowledge/datasets/{active}/metrics/. Before touching anything, copy the whole metrics/ directory aside, for example to .knowledge/comparisons/<question-slug>/<UTC-timestamp>/metrics-backup/. This backup is what Step 4 restores; nothing this skill stages may outlive the comparison.

Step 1 - baseline arm (without the context)

Make sure the definition under test is absent: read metrics/index.yaml, and if the metric is already defined there, remove its index entry and its {id}.yaml for this arm (the Step 0 backup keeps the original).

Then run the reliability check for this arm: launch N fresh, independent sub-sessions in parallel using the reliability skill's Step 1 brief verbatim (same fresh-context rules, each sub-session sees only the question and returns the same headline / measured / definition_source block; for a comparison they must also not read .knowledge/comparisons/ before answering). Record the N results to .knowledge/comparisons/<question-slug>/<ts>-baseline/runs.json, in the same shape the reliability skill uses: {"question": "<the question>", "runs": [{"run":1,"headline":"...","measured":"...","definition_source":"..."}, ...]}

Compute this arm's statistics deterministically with the bundled script:

python3 helpers/stats/reliability_stats.py .knowledge/comparisons/<question-slug>/<ts>-baseline

It writes stats.json and report.md into the run dir. Never estimate these numbers.

Step 2 - with-context arm (definition staged)

Stage the definition into the metric dictionary using the metric-spec registration format: write .knowledge/datasets/{active}/metrics/{id}.yaml (name, plain-English definition, formula, unit, source tables, reference SQL if given) and add the id / name / category entry to metrics/index.yaml. Meaning only: the definition says how to measure, never a result number.

Run N fresh sub-sessions again with the identical brief, into .knowledge/comparisons/<question-slug>/<ts>-with-context/runs.json, and compute that arm's statistics with the same script.