/sox-replay-build

Turns a finished SOX test into a reusable .skill ZIP. The replay skill is not a copy of the workpaper: it’s the recipe that produced it. The deterministic procedure scripts ride along verbatim (the same SHA-256 they ran with the first time), the locked test-attribute lists and sampling methodology are baked into a generated skill definition, and the whole thing re-runs the same test against a new period’s inputs. It generates no new Python. The judgmental pieces, reasoning, sample IDs, the actual evidence pixels, are deliberately not captured, because they have to regenerate each period.

When to use

When a /sox-testing run has completed and produced a workpaper you’d run again next quarter, half, or year; when you want the deterministic procedures byte-for-byte identical between periods, tamper-evident via SHA; or when you want to hand the test to a colleague or another workspace as a single-file artifact. If the test is one-off with no plan to repeat, skip this: the workpaper itself is the deliverable.

Inputs

Flag	Required	Notes
<workpaper.xlsx>	Yes	The output of /sox-testing, or a record-centric workpaper in the same family: must have a Summary tab and at least one detail or record tab.
--specs <path>	No	The specs.json passed to the evidence writers. Strongly recommended for evidence-based tests: the only reliable record of each test’s field list.
--evidence-type <type>	No	xlsx, video, none, or auto (default). Errors out on ambiguity so you pass it explicitly.
--control-id <id>	No	Explicit control ID for a workpaper that does not carry one unambiguous Control ID: cell or preamble identifier. Wins outright when passed.
--period <period>	No	The period this workpaper covers (e.g. 2026-Q1), stamped into the replay’s origin so it records what it was built from.
--output <path>	No	Output path for the .skill ZIP. Defaults to <workpaper-dir>/<control-id>-replay.skill.

Example

/sox-replay-build workpaper.xlsx --specs specs.json --period 2026-Q1 reads the workpaper’s Summary and detail tabs, copies each deterministic script into a .skill ZIP after re-verifying its SHA-256 (aborting on any mismatch), bakes the test plan and methodology into a generated skill, and writes the finished skill’s own sha256 back into the source workpaper as external tamper evidence.

Good to know

• Pass --specs for evidence-based tests. It’s the only reliable record of each test’s UI-field list; without it the builder falls back to the test name and marks the entry (verify field list), and the auditor running the replay is asked to confirm the fields.
• Reasoning and evidence pixels are never captured: by design. Locking last quarter’s prose into next quarter’s workpaper would be a controls failure, not a feature; each period’s judgment and evidence are fresh.
• A SHA mismatch aborts the build. A replay built on a tampered script is worse than no replay at all, so the tamper check is hard.
• The artifact’s hash is anchored outside the artifact. The finished .skill’s sha256 is written back into the source workpaper, so next period a reviewer can confirm the installed skill matches what this run emitted.
• The replay is a thin orchestrator. At runtime it delegates to /sox-python, /sox-annotate-xlsx, /sox-from-video, and /sox-from-web by name, running a compatibility check first since a major plugin change could move those interfaces.
• Both workpaper shapes normalize to the same plan. The builder detects the shape before it reads anything else. A legacy workpaper with one detail tab per (sample, test) pair and a record-centric one whose Summary links into a six-column attribute table per sampled record produce the same test plan; the shape it came from is stamped into the replay’s provenance as origin_workpaper_topology. A workbook that mixes both forms, or matches neither, aborts with the detector’s errors before any output is written: no .skill file, no partial ZIP.
• Evidence-only tests replay without a scripts directory. --scripts-dir matters only when the workpaper actually references deterministic scripts, whether by a detail tab’s Script / SHA-256 fields, a Procedure tab, or a record row’s Evidence cell naming a .py file. A purely evidence-based workpaper, in either shape, packages with no scripts directory at all.
• --control-id is the explicit fallback. The control ID is resolved from the workpaper’s own Control ID: cells or a single unambiguous Summary preamble identifier. More than one candidate, or none, stops the build and asks for --control-id instead of guessing.

Related

• /sox-testing: the engine whose completed run this packages for replay.
• /sox-python: the deterministic scripts locked, verbatim and SHA-verified, into the replay.
• /sox-annotate-xlsx: the evidence writer whose specs.json records the field lists the replay locks.

Not audit or legal advice. Workpapers and assessments produced by these skills require review by qualified financial professionals before being relied on for SOX 404 compliance.