Agent Operating Guide
/sox-annotate-xlsx
Turn an xlsx of embedded evidence screenshots into an annotated SOX workpaper tab with movable red-rectangle Excel shapes and gutter labels over each tested field, never burned-in pixels.
Takes an xlsx workbook whose sheets contain evidence screenshots, configuration screens,
system reports, approval queues, identifies where each requested attribute sits on each
image, and writes a per-sample-per-test detail tab into a SOX workpaper. Each tab carries the
red-bordered narrative (Observation / Procedures Performed / Conclusion) on top and the
original screenshot below, marked with red-outline rectangle Excel shapes and bold red
gutter labels (field: observed value). The pixels are never touched: the boxes, labels,
and connector lines are native Excel shapes a reviewer can nudge, restyle, or delete. The
workpaper’s Summary tab is updated with the result and reasoning.
The skill never views an image itself. For each image it dispatches a sox-evidence-boxer to
locate the pixel rectangles and a sox-evidence-context to read each field’s value and
ambient signals, in parallel; a sox-evidence-reviewer then double-checks the box positions
against a rendered overlay. The skill auto-judges pass/fail from their JSON alone: keeping
the image bytes out of its context is the whole point of the leaf agents.
When to use
Section titled “When to use”When a tester hands you an xlsx with a system screenshot per sheet and the control test needs to mark exactly which on-screen fields were inspected, and you want the standard SOX deliverable (prose on top, annotated evidence below) with movable shapes, not burned pixels, so the tester can iterate.
Inputs
Section titled “Inputs”| Flag | Required | Notes |
|---|---|---|
<source-xlsx> |
Yes | A workbook with at least one sheet containing embedded images (.xlsx only, not password-protected). |
<fields...> |
Yes | The attributes to box on each screenshot. Comma-separated, or a path to a .txt / .json list. |
--workpaper <path> |
No | Destination for the detail tab. Defaults to workpapers/<control-id>/workpaper.xlsx. |
--sample <N> |
No | Which sample this evidence belongs to. Required for Summary-tab updates. |
--no-review |
No | Skip the on-by-default box-position review pass. |
--no-context |
No | Skip the on-by-default value-and-context scan; auto-judge then defers every field. |
--max-review-iters <N> |
No | Maximum reviewer passes per image (default 2, ceiling 3). |
Example
Section titled “Example”/sox-annotate-xlsx evidence.xlsx "Approver,Maximum Amount,Self Approval Block" --sample 1
extracts each sheet’s screenshot, dispatches a boxer and a context agent per image, reviews
the box positions, auto-judges each field against its expected value, and writes an s1
detail tab with red-rectangle shapes and gutter labels over the tested fields plus an updated
Summary row.
Good to know
Section titled “Good to know”- The review loop is on by default.
sox-evidence-reviewercatches box drift: common on dividerless layouts, and feeds it back for a revision, capped by--max-review-iters. Use--no-reviewfor tester-internal drafts where speed matters more than the catch rate. - Auto-judge clears four gates or defers. A field is written
pass/failonly when the observed value matches the expectation, the read is confident, the box position is confirmed, and no disqualifying context signal (disabled, unsaved, error, or an out-of-force status badge) fires. Otherwise it becomesneeds_humanfor you to resolve. - Boxes are bonded to their image. They move with it when rows are inserted or resized; a reviewer double-clicks into the group to nudge a single box.
- Multi-sample workpapers use
write-batch. Writing tabs one at a time would strip the shapes from previously annotated tabs: the batch path opens the workbook once and injects all shapes together. - No OCR. A poor-contrast or graphic field may be missed entirely; it’s reported as not-found, never invented.
Related
Section titled “Related”- /sox-testing: the engine that orchestrates this as its screenshot-evidence step.
- /sox-from-video: the same annotate pipeline sourced from video frames.
- /sox-from-web: the same pipeline sourced from live browser captures.
- /sox-from-folder: the same pipeline sourced from a mixed evidence folder.
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.