Agent Operating Guide
/sox-python
Run a deterministic SOX procedure as code, sample draw, three-way match, recomputation, threshold check, and append a reproducible Procedure tab carrying the source, output, runtime, exit code, and a SHA-256.
Whenever a SOX procedure is deterministic, the same inputs always produce the same output,
running it as code instead of by hand makes the step reproducible. This skill writes the
Python, runs it, and appends a Procedure-N tab to the workpaper xlsx carrying the full
source, captured stdout/stderr, runtime, exit code, and a SHA-256 of the script for
tamper-evidence. A reviewer, or an external auditor, can re-run the exact script and
reproduce the result. It is the tick-and-tie engine that /sox-testing
delegates every deterministic step to.
When to use
Section titled “When to use”- Sample selection: a random or systematic draw from a population, with a recorded seed.
- Re-performance: recomputing a reconciliation, accrual, depreciation schedule, or balance.
- Three-way match: tying PO, receipt, and invoice across files.
- Threshold tests: “did any transaction over $X bypass the approval limit?”
- Duplicate detection: same vendor, same amount, same week.
- Exception roll-ups: counting or summarizing exceptions across many sub-steps.
- Date-window checks: “was every entry posted within N days of period end?”
If the work is judgmental, interpreting a contract clause, weighing evidence quality, classifying a deficiency, this is the wrong tool; use /sox-testing.
Inputs
Section titled “Inputs”| Flag | Required | Notes |
|---|---|---|
<step description> |
Yes | A natural-language description of what the step should compute. |
--inputs <files> |
No | Paths to input data files (CSVs, xlsx populations). |
--workpaper <path> |
No | The workpaper xlsx to append to. Defaults to workpapers/<control-id>/workpaper.xlsx. |
--seed <n> |
No | Explicit RNG seed when randomness is involved. Defaults to a deterministic seed derived from control ID + step + period, recorded on the tab. |
Example
Section titled “Example”/sox-python "draw a random sample of 25 invoices from the Q4 population" writes a seeded
draw script, runs it, and appends a Procedure tab recording the seed, the selected sample
IDs, the full script source, its captured output, and the script’s SHA-256: the reproducible
record a reviewer re-runs to confirm the draw.
Good to know
Section titled “Good to know”- It refuses a green result over a crash. A “pass” written over a nonzero exit code is a
corrupt audit trail, so the runner rejects it: declare
fail/n/a, or pass--allow-nonzero-exitfor procedures that legitimately use exit codes as data. - Reasoning is required on every run. A SOX workpaper without reasoning is not a workpaper; the runner errors if none is supplied.
- Run all procedures before annotating evidence. Saving over an already-annotated
workpaper would strip the movable evidence shapes, so the runner refuses unless you
override: order your
/sox-pythonruns ahead of the evidence annotators. - The script is kept on disk. It lands next to the workpaper so a reviewer can re-run it independently of Excel.
- No sandbox. The script runs with full filesystem and network access: don’t give a “deterministic” procedure network calls.
Related
Section titled “Related”- /sox-testing: the engine that delegates every deterministic step here.
- /sox-annotate-xlsx: annotates evidence into the same detail tabs, after the procedures run.
- /sox-replay-build: locks these scripts, SHA-verified, to replay the test next period.
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.