icaire-reportify
Turn ICAIRE evidence and source material into audience-fit reports and visually integrated PDF deliverables. Use when preparing analyses, executive updates, decision briefs, operational handoffs, part
SKILL.mdskills/icaire-reportify/SKILL.md
GitHubICAIRE Reportify
Design and render an evidence-led ICAIRE report whose structure follows the reader's decision, not a fixed template.
Contract Checklist
- Identify the audience, reporting period, decision need, and confidentiality before choosing a structure.
- Choose a report archetype as a starting point, then change it when the evidence requires a different reading order.
- Separate confirmed facts from assumptions, inference, causal claims, risks, and open questions.
- Place every useful visualization next to the claim it supports, with an analytical caption.
- Treat figures the user identifies as essential as required report content.
- Prefer the ordered-block JSON model for new reports; preserve legacy JSON only when maintaining an existing report.
- Render a polished PDF, inspect the first page plus every dense or figure page, and fix clipping, illegibility, or orphaned captions.
- Use the ICAIRE green
#4A9549and local untracked ICAIRE/UNESCO lockups when available. - End with specific source limits or missing information when the evidence is incomplete.
Workflow
- Define the report job:
- capture audience, period, confidentiality, decision or update need, expected depth, and required deliverables
- select an initial archetype:
analysis,executive_update,decision_brief,operational_handoff,external_brief, orcustom - treat the archetype as a design prompt, not a mandatory section list
- Anti-patterns: defaulting every report to executive summary and risks, choosing structure before the decision need, treating an archetype as a locked template
- Gather and verify evidence:
- use material supplied by the user, then BigBrain or the ICAIRE connector when ICAIRE facts, meetings, initiatives, or prior language are missing
- extract claims, metrics, uncertainty, milestones, decisions, risks, dependencies, asks, and source limits
- distinguish operational source data from dashboard summaries and retrieve the authoritative record when feasible
- Anti-patterns: inventing KPI values or approvals, treating a dashboard as ground truth without reconciliation, hiding source gaps
- Select the story and visual evidence:
- decide the smallest set of claims the reader must understand
- choose tables or figures only when they materially clarify a comparison, sequence, distribution, uncertainty, or decision
- place each figure immediately after the claim or question it answers
- write captions that state the takeaway, measure, window, and important uncertainty rather than merely naming the chart
- Anti-patterns: adding decorative charts, putting all figures in an appendix by default, separating a figure from its interpretation, omitting a user-required visualization
- Storyboard ordered blocks:
- arrange headings, paragraphs, bullets, figures, tables, callouts, rules, spacers, and page breaks in reader order
- use callouts for a central finding, risk, decision, or causal boundary
- allow a figure to lead a section when it is the clearest entry point
- Anti-patterns: translating evidence into the legacy schema before storyboarding, forcing empty sections, duplicating the same claim across summary and body
- Draft with calibrated status language:
- explain what changed, why it matters, what remains uncertain, and what action follows
- use effect sizes and uncertainty for analytical claims when the data supports them
- call observed post-treatment movement an association or post-intervention progression unless a valid comparison identifies causal lift
- Anti-patterns: implying causality without a control, burying material risks, using external-facing certainty for internal unknowns
- Encode the preferred ordered-block JSON:
- keep
title,audience,period, and classification metadata at the top level - set
schema_version: 2, an optionalarchetype, optionalhighlights, and an orderedblocksarray - use relative figure paths when the images travel with the report JSON; they resolve from the JSON file directory
- if
blocksis present it is authoritative; do not also populate legacy body fields - Anti-patterns: mixing ordered blocks with legacy sections, using unresolved image paths, shrinking figures below legibility to avoid a page break
- keep
- Render and inspect:
- run
python3 scripts/render_report_pdf.py report.json report.pdf - use the Codex bundled Python runtime when local ReportLab is unavailable
- render pages to PNG with Poppler when available
- inspect the first page, every figure page, and dense pages for image scale, caption proximity, page breaks, spacing, clipping, and legibility
- Anti-patterns: delivering without opening the PDF, checking only the first page, accepting an orphaned caption or distorted figure
- run
- Verify and deliver:
- reconcile headline values with the source data and confirm sensitive claims are supported
- verify every required figure appears in the final PDF at readable size
- report the PDF path, included figures, concise findings, source limits, and visual-verification result
- Anti-patterns: claiming final when evidence is incomplete, reporting a source image as included without checking the PDF, omitting remaining decision gaps
Preferred JSON v2
Ordered blocks provide the report's reading order:
{
"schema_version": 2,
"archetype": "analysis",
"title": "Applied Ethical AI Quiz Reminder Experiment",
"audience": "ICAIRE Educate leadership",
"period": "First 24 hours",
"classification": "Internal",
"prepared_for": "ICAIRE Educate",
"prepared_by": "ICAIRE",
"highlights": [
{"label": "Progressed", "value": "49 (12.9%)"}
],
"blocks": [
{"type": "heading", "text": "What happened", "level": 2},
{"type": "paragraph", "text": "A concise evidence-grounded finding."},
{
"type": "figure",
"path": "stage-conversion.png",
"caption": "Figure 1. Progression was highest among learners already near completion; lines show 95% intervals.",
"width_mm": 160,
"max_height_mm": 180,
"page_break_before": false,
"keep_with_caption": true
},
{
"type": "table",
"headers": ["Stage", "Delivered", "Progressed"],
"rows": [["0 passed", "297", "7.4%"]],
"column_widths_mm": [70, 40, 53]
},
{
"type": "callout",
"tone": "teal",
"heading": "Causal boundary",
"body": "This is observed progression, not incremental lift."
},
{"type": "page_break"},
{"type": "bullets", "items": ["Decision or next action."]},
{"type": "rule"},
{"type": "spacer", "height_mm": 4}
]
}
Supported ordered block types are heading, paragraph, bullets, figure, table, callout, page_break, rule, and spacer. Figure paths may be absolute or relative to the report JSON. Images preserve aspect ratio and scale down to the requested maximum; they are never cropped.
Legacy v1 Compatibility
When blocks is absent, the renderer continues to accept executive_summary, sections, risks, decisions_needed, missing_information, assumptions, and sources in the established order. Use this only for existing reports that depend on that structure.
Brand And Rendering
- Primary accent:
#4A9549. - Optional untracked lockups:
assets/brand/report/icaire-lockup.pngassets/brand/report/unesco-lockup.png
- Render command:
python3 scripts/render_report_pdf.py report.json report.pdf
- Visual inspection when Poppler is available:
pdftoppm -png report.pdf report-page
Anti-Patterns
- Using the same Executive Summary, Risks, Decisions, and Missing Information sequence for every report.
- Treating report structure as data entry rather than information design.
- Placing all visualizations at the end when they explain earlier claims.
- Omitting a user-required figure or replacing it with prose.
- Mixing legacy body fields with ordered blocks and duplicating content.
- Distorting, cropping, or over-shrinking a figure.
- Inventing facts, dates, owners, approvals, partner positions, or KPI values.
- Hiding causal, measurement, or data-quality limitations.
- Delivering a PDF without visual verification.
Output
Return:
- the final PDF path;
- a concise findings summary appropriate to the audience;
- the captions or names of figures included in the PDF;
- source, causal, and missing-information limits;
- confirmation that the first, figure, and dense pages were visually inspected;
- any remaining blocker or deliberate omission.