Skip to content
AssureSwarm Docs

Agent Operating Guide

/audit-workpaper-annotate

Annotate a workpaper's specific tabs or sections with stable reference markers so a finding can cite exact evidence, then upload the annotated copy to a workflow step.

Solve the “we can only cite the whole document, not the specific tab” problem. Given a supporting workpaper (Excel or Word), the skill walks you through mapping each tab or section to the workflow step it supports, adds non-destructive reference markers (a hidden _canvas_refs sheet in xlsx, or comments plus a reference table in docx), and uploads the annotated copy to the relevant step via upload_document. Your original file stays on disk untouched.

When to use

Section titled “When to use”

When a finding needs to point at exactly the cells or sections that are its evidence, rather than attaching a whole workbook and saying “see the SOX controls tab.” The markers it leaves are what /coach-render-package reads in --cite mode to bind claims to their source sections.

Inputs

Section titled “Inputs”
Flag Required Notes
--workpaper <path> Yes The file to annotate (.xlsx or .docx).
--audit <audit-id> Yes The audit whose workflow steps the sections map to.

The tab-or-section → step mapping is gathered interactively; the skill resolves step ids from the audit’s workflow via get_step_context.

Example

Section titled “Example”

/audit-workpaper-annotate --workpaper fieldwork.xlsx --audit aud_2026_rev enumerates the workbook’s tabs, asks which step each one supports, writes an annotated copy (fieldwork_annotated.xlsx) with a hidden reference sheet, and uploads it to the first mapped step: registering a reference to the same document on each additional mapped step so it shows up as supporting evidence everywhere it belongs.

Good to know

Section titled “Good to know”
  • The annotation is non-destructive: original cells and text are preserved; markers are added as metadata (a hidden sheet, comments, a marker table).
  • Re-annotating an already-annotated workpaper preserves the prior mappings and just refreshes the metadata.
  • Evidence lives as documents attached to workflow steps: files via upload_document, URL-only references via a stepdocumentlink suggestion. There is no separate evidence item type.
Section titled “Related”