Handoff Schema for caption_audit_report/1 (Locked)
Every successful dashboard-caption-audit invocation emits this schema. Downstream skills (desktop-spellcheck, format-drift-scanner, viz-planner, dashboard-preflight, workbook-auditor) may consume it. Schema is versioned; unknown versions refused by downstream per HC#8.
Full Schema
schema_version: caption_audit_report/1
workbook_name: {name}
dashboards_audited: {N}
audit_metadata:
timestamp: {ISO-8601}
total_dashboards_in_workbook: {N}
worksheets_on_audited_dashboards: {N}
text_objects_audited: {N}
findings:
- rule_id: {DC-TITLE-01 | DC-CAPTION-02 | DC-WS-TITLE-03 | DC-WS-CAPTION-04 | DC-TEXT-EMPTY-05 | DC-DEFAULT-NAME-06 | DC-DEVICE-07 | DC-TITLE-08}
rule_name: {short_string}
severity: {Warning | Info}
dashboard_name: {name}
element_type: {dashboard | worksheet | text_object | device_layout_parent}
element_name: {name_or_null}
xml_evidence: {snippet_string}
desktop_fix: {step_by_step_instruction}
affected_variants: [{phone | tablet | empty}]
finding_counts:
warnings: {N}
info: {N}
unscanned_dashboards:
- dashboard_name: {name}
reason: {short_string, e.g. "get-dashboard-xml returned partial results"}
routing:
desktop_spellcheck: {true | false}
format_drift_scanner: {true | false}
viz_planner: {true | false}
dashboard_preflight: {true | false}
rationale: {short_string}
delivery:
tier_a_rendered: {true | false}
tier_b_saved: {true | false}
tier_b_file_path: {absolute_path_or_null}
tier_b_format: {md | txt | null}
run_metadata:
tool_failures: [{tool_name_or_empty}]
notes: {optional_free_text}
Field-by-Field
- schema_version. Always exactly
caption_audit_report/1. - workbook_name. Name of the audited workbook.
- dashboards_audited. Count of dashboards actually walked (excludes UNSCANNED).
- audit_metadata. Operational context (timestamp, total counts).
- findings. Every finding rendered in the report. Empty list
[]if fully labeled. - finding_counts. Aggregate by severity for quick consumption.
- unscanned_dashboards. HC#9 flagged dashboards with reason. Empty
[]when all dashboards walked cleanly. - routing. Downstream skill routing flags. Booleans set based on finding types:
desktop_spellcheck: trueonly when this run's Recommended Actions include adding NEW caption/title text (i.e., at least one DC-CAPTION-02, DC-WS-CAPTION-04, DC-TITLE-01, or DC-WS-TITLE-03 finding exists). Setfalsewhen the workbook is fully labeled or when all findings are non-text issues (e.g., only DC-DEFAULT-NAME-06 or DC-TEXT-EMPTY-05). The flag signals "spellcheck the text the user is about to add," not "text already exists somewhere in the workbook."format_drift_scanner: trueif caption fonts might drift after new captions added.viz_planner: trueif 5+ Warnings suggest structural redesign.dashboard_preflight: truealways (preflight consumes caption findings for assembly hygiene enrichment).
- delivery. Records Tier A/Tier B state; whether the file was saved and where.
- run_metadata. Operational metadata;
tool_failureslists any tool that failed mid-run. - notes. Optional free-text for edge cases.
Downstream Consumer Expectations
desktop-spellcheck. Consumes whenrouting.desktop_spellcheck: true. After the user adds missing captions, spellcheck the new text.format-drift-scanner. Consumes whenrouting.format_drift_scanner: true. New captions may drift font family or size from workbook baseline.viz-planner. Consumes whenrouting.viz_planner: true(5+ Warnings). Uses findings as design-review input.dashboard-preflight. Always consumes. Caption findings enrich assembly hygiene at pre-publish time.workbook-auditor. Consumes finding deltas across runs (workbook improvement or regression tracking).
Verdict Contracts
"Fully labeled workbook" (no findings):
findings: [].finding_counts.warnings: 0,finding_counts.info: 0.routing.dashboard_preflight: true(always).- All other routing flags:
false.
"Mixed findings workbook":
findingscontains at least one entry.finding_countsreflects severity distribution.routingflags set per finding-count thresholds.
"UNSCANNED partial audit":
unscanned_dashboardspopulated with at least one entry.findingsreflects only dashboards that were successfully walked.- Report includes UNSCANNED disclosure section.
notesmay include recovery guidance.
Refuse to Guess
If any required field cannot be populated, refuse delivery per HC#8. Never fake a finding. Never assign a rule_id that doesn't match the 8-rule catalog. Never bypass HC#11 (default-name always Warning).