Skip to content
AssureSwarm Docs

Agent Operating Guide

/sox-from-folder

Turn a mixed folder of SOX evidence into an annotated workpaper, hashing every file for custody, mapping each image to its sample and tests, and boxing the tested fields with movable Excel shapes.

Takes a directory dump of evidence, native screenshots, multi-page PDFs, xlsx decks, recordings, whatever the process owner exported, and turns the mappable part into the standard SOX workpaper format. Its distinctive job is attribution: nothing in a folder dump says which sample a file evidences, so a dedicated sox-evidence-mapper leaf agent reads each image and ties it to a sample and to the test(s) it supports before any extraction runs. Low-confidence and unmatched mappings are resolved with you, not the model. Every source file is SHA-256-hashed and mtime-stamped for chain of custody first; PDF pages are rendered; then the same boxer + context + reviewer pipeline as /sox-annotate-xlsx annotates each image with movable red-rectangle shapes: each carrying a custody caption and an Excel hyperlink back to its source file.

When to use

Section titled “When to use”

When a tester hands you a folder (or extracted zip) of evidence collected by someone else, with no manifest linking files to samples, and a test plan already exists, typically from /sox-testing, so the work remaining is map, extract, annotate, judge. A single xlsx deck goes to /sox-annotate-xlsx; one recording plus transcript to /sox-from-video; live browser collection to /sox-from-web. /sox-testing invokes this skill when handed --evidence.

Inputs

Section titled “Inputs”
Flag Required Notes
<evidence-dir> Yes The directory to inventory recursively.
--test-plan <path> Yes The locked plan from /sox-testing: its tests, fields, expected values, and usually the samples.
--samples <file> No The sample list (csv/xlsx/json), when not carried inside the test plan.
--template-profile <path> No A profile from /sox-from-template to write into a firm’s bespoke layout.
--no-review No Skip the on-by-default box-position review pass.
--no-context No Skip the value-and-context scan; auto-judge then defers every field. Never skips the mapper.
--max-review-iters <N> No Boxer revisions allowed per image in the review loop (default 2, ceiling 3).

Example

Section titled “Example”

/sox-from-folder ./evidence --test-plan workpaper/test-plan.json inventories and hashes the folder, renders any PDFs, maps each image to a sample and its tests via the mapper fan-out, asks you to resolve the low-confidence mappings, then boxes, reads, reviews, and auto-judges each tested field and writes annotated detail tabs: each image captioned with its source path and sha256 and hyperlinked back to the original file.

How it works

Section titled “How it works”

The skill inventories the directory recursively and records a SHA-256 and mtime for every source file before anything else touches it: that hash is the custody anchor the captions render later. Images pass straight through; PDFs are rendered to pages at 150 DPI; xlsx decks and recordings are routed to /sox-annotate-xlsx and /sox-from-video; anything unsupported is surfaced for you to decide on. It then dispatches one sox-evidence-mapper per image in parallel to attribute each file to a sample and its tests, and resolves every low-confidence, null-sample, or unknown-slug mapping with you before extraction: there is no mapper retry loop, so disagreements are a person’s to settle. Once the map is settled it runs the same sox-evidence-boxer + sox-evidence-context + sox-evidence-reviewer fan-out and four-gate auto-judge as /sox-annotate-xlsx, and the batch writer lays down the detail tabs with a code-written custody caption and a source-file hyperlink beside each image.

Good to know

Section titled “Good to know”
  • Mapping quality is bounded by what’s on the page. Evidence with no visible identifier maps to null and consumes a human decision: that’s by design; filename hints help the mapper but never outrank on-image content.
  • One sample per image. A population-wide report that should back several samples is duplicated per sample in your resolutions, never fanned across samples silently.
  • xlsx and video are routed, not inlined. Their tabs land in the same workpaper, but through their own pipelines: run them next.
  • Locked PDFs fail loudly. Password-protected or image-free PDFs fail rendering with an actionable error; ask the evidence owner for an unlocked copy.
  • Custody rides with the deliverable. The Source: … | sha256:… caption and the source-file hyperlink are written from the manifest, not model prose, and never burned into the pixels.
Section titled “Related”

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.