apxm-preregistration

name	apxm-preregistration
group	Evaluation
description	Use before any claim-bearing APXM run (benchmark, evaluation, paper-bound number). Drafts, commits, and verifies a docs/preregistrations/ entry under the project's append-only norm.
user-invocable	true

APXM Preregistration

Load _shared/apxm-preregistration-rules.md and _shared/apxm-evaluation-rules.md before broad work.

When this skill is required

The run is claim-bearing if its output backs:

• A claim card under docs/claims/.
• A benchmark number cited in a PR description, README, or docs/.
• Any external write-up consuming this harness's evidence.
• A "X is faster than Y" / "X matches Y in quality" assertion.

If none apply, this skill is optional (but still useful for honesty).

Steps

1. Read 2–3 existing preregistrations in docs/preregistrations/ matching the workload type (priority-lane, review-council, tau2, cross-system, J/req). Match style and section ordering.
2. Draft the file at docs/preregistrations/<YYYYMMDDTHHMMSS>Z-<plan>-<scenario>-<arm>.md using the template in _shared/apxm-preregistration-rules.md.
3. Confirm the protocol with the user — explicitly, before committing. Surface goal, primary metric, success threshold, exclusions, and the artifact path.
4. Commit with a message in repo style: prereg(planNN): <plan> <scenario> — <descriptor>.
5. Record the commit SHA. It will be cited in the write-up under docs/evaluation/.
6. Hand off to the run-execution skill (e.g. apxm-priority-lane-bench, apxm-review-council-bench) only after the preregistration commit lands.

Scaffolding a new benchmark/demo

When the workload is new (not just a new prereg), scaffold it alongside:

• Host decision: apxm-eval (paper-bound — prereg required, claim card) vs apxm (runtime-internal microbench — no prereg/claim).
• Workload family → template: latency-paired-arm, throughput-sweep, cache-reuse-paired, or dispatch-correctness (templates under docs/preregistrations/_templates/).
• Layout: examples/python/benchmarks/<workload>/{__init__.py,run.py, workload.py,README.md} + docs/claims/<workload>.md stub.
• Hard contracts: paths resolve via apxm.contract.build_layout(__file__).evaluation_scenario(<workload>) (never raw os.path); paired-arm cache salt per (arm, opt); dekk apxm vllm check-no-legacy --strict in the driver CI block; no hardcoded allocator-range port literal (use the allocator).

What apxm-finish will check

• Matching file exists in docs/preregistrations/.
• Preregistration commit timestamp is before the first artifact in .apxm/evaluation/<scenario>/runs/<UTC>/.
• Write-up cites the preregistration commit SHA.

Anti-patterns

• Drafting the prereg after the run — the entire point is to freeze the protocol before seeing the numbers.
• Rewriting a committed prereg. Append a -corrective or -restart file with a reference instead.
• Drafting without recording the APXM and vLLM-submodule commit SHAs.
• Drafting without an "Exclusions / known confounds" section — known confounds left implicit always come back to bite the analysis.

See also

• docs/preregistrations/ — the existing corpus.
• apxm-claim-evidence — the downstream skill that promotes a successful run into a claim card.