| 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
- 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.
- Draft the file at
docs/preregistrations/<YYYYMMDDTHHMMSS>Z-<plan>-<scenario>-<arm>.md
using the template in _shared/apxm-preregistration-rules.md.
- Confirm the protocol with the user — explicitly, before
committing. Surface goal, primary metric, success threshold,
exclusions, and the artifact path.
- Commit with a message in repo style:
prereg(planNN): <plan> <scenario> — <descriptor>.
- Record the commit SHA. It will be cited in the write-up under
docs/evaluation/.
- 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.
