Agent Operating Guide
/sox-from-template
Profile a firm's bespoke xlsx workpaper layout into a reusable template profile and scaffold the population, so the testing skills write into the firm's own cells instead of the canonical layout.
A pre-processor that runs before the testing skills. Given a firm’s preferred xlsx
workpaper template, typically with one sample completed as a guide, it auto-detects the
layout’s shape, profiles each placeholder cell to a semantic field, and scaffolds copies for
the rest of the population. It emits two artifacts: a scaffolded workpaper xlsx and a
template-profile.json. The downstream skills accept a --template-profile flag; when set,
they bypass the canonical Summary + detail-tab layout entirely and write into the firm’s
cells. The template file itself is never mutated.
When to use
Section titled “When to use”When the tester or their firm has a preferred xlsx format, branding, custom column layout, narrative sections in specific places, that the plugin’s canonical output doesn’t match, and they’ve handed you a template with one record completed so the layout intent is unambiguous. If there’s no template and the standard output is fine, skip this and go straight to /sox-testing.
Inputs
Section titled “Inputs”| Flag | Required | Notes |
|---|---|---|
<template.xlsx> |
Yes | A workbook with at least one exemplar record (a filled tab, a filled matrix row, or a filled per-attribute tab). |
--population <N> |
No | Total samples to scaffold for. Defaults to the count of existing siblings or 1. |
--control-id <id> |
No | Stamps the profile and downstream writes. Auto-detected from a Control ID cell when present. |
--tests <list> |
No | Comma-separated test attributes, when the template’s result cells aren’t column-labeled. |
--shape-override <shape> |
No | Force the shape detector (per-sample-tabs, master-matrix, per-test-tabs, single-tab) when it reports ambiguity. |
--hints <json> |
No | Manual field-map overrides for cells the detector maps with low confidence. |
--outdir <dir> |
No | Working directory for the profile and scaffolded xlsx. |
Example
Section titled “Example”/sox-from-template firm-workpaper.xlsx --population 25 inspects the template, classifies its
shape, maps each placeholder cell to a semantic field, and scaffolds 25 sample tabs: then
surfaces the detected shape, the exemplar, and any low-confidence field mappings for you to
confirm before you run the testing skills with --template-profile.
Good to know
Section titled “Good to know”- Low confidence is a flag, not a failure. A field mapped below the confidence floor is
surfaced for you to spot-check, or you pass
--hintswith the right cells. - A “mixed” shape stops and asks. When the top two shape detectors are within 0.15, the
skill asks which interpretation to force via
--shape-overriderather than guessing. - Some template features don’t survive the clone. Copying a worksheet drops drawn shapes,
charts, and form controls: the scaffolder reports a
will_be_droppedlist so you can decide whether the template is a good fit before testing against the scaffold. .xlsmand linked images are out of scope. Save macro-enabled templates as.xlsx; URL-linked images (rather than embedded ones) aren’t supported.- Annotation compatibility is checked. When
annotation_compatibleisfalse, the template’s images can’t be safely overlaid with shapes: use the canonical layout for that evidence.
Related
Section titled “Related”- /sox-testing: the engine you run after profiling, threading the profile through.
- /sox-annotate-xlsx: a downstream writer that writes into the profiled cells.
- /sox-python: a downstream writer whose procedure output lands in the profiled cells.
- /sox-from-video: a downstream writer that inserts annotated frames into the profiled layout.
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.