report-to-google-doc

Report To Google Doc

Use this skill only when the user explicitly needs a shareable Google Drive document from an existing HTML analytics report. The source must be an HTML report: a local file, a downloaded blob-hosted report, or a report produced by $build-report HTML mode. This skill does not convert a live MCP app report directly.

The expected path is HTML -> DOCX -> Drive upload. It is acceptable for Drive to host the upload as a DOCX-backed viewer file rather than a native Google Docs MIME type. Do not use the old Google Docs batch-update request path.

Workflow

1. Resolve the HTML report.

   Use an absolute local path. If the user provides a remote report, retrieve it first and pass the local HTML file to the helper. If the file is a sign-in page, redirect page, or tiny stub, stop and obtain the real report.

2. Run the bundled helper.

   python3 <REPORT_TO_GOOGLE_DOC_SKILL_DIR>/scripts/report_to_google_doc_plan.py \
     /absolute/path/to/report.html \
     --out-dir /tmp/report_to_google_doc_plan
   

   Omit --render-workers on the normal path. Only pass a worker count after benchmarking the same report family locally. If dependencies are missing, use a local virtual environment with beautifulsoup4, pillow, and python-docx; cairosvg or headless Playwright are optional renderers.

3. Inspect helper outputs.

   Required outputs:

   • skeleton.txt: source text with stable placeholders
   • manifest.json: parsed headings, tables, callouts, lists, styles, links, and rendered visual inventory
   • preflight_checks.json: source, width, DOCX, and rendered-image checks
   • report.docx: generated local Word document
   • docx_upload_plan.json: compact upload instructions
   • placeholder_queries.json: source mapping debug labels

   Do not upload until preflight_checks.json has status: "passed" with zero errors. Warnings must either be fixed or called out in the handoff.

4. Upload the DOCX.

   mcp__codex_apps__google_drive._upload_file({
     "file_uri": "/tmp/report_to_google_doc_plan/report.docx",
     "file_name": "Report Name.docx",
     "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
   })
   

   Treat the returned Drive URL as the deliverable. Do not attempt to force native Google Docs conversion, and do not fall back to _batch_update_document.

5. Validate the uploaded result.

   Confirm the uploaded file is readable and non-empty. Compare uploaded text against the source inventory: title, section headings, executive summary or answer callout, caveats, recommendations, source notes, and source links. Inspect the local report.docx structure when available: heading counts, lists, tables, hyperlink relationships, and image relationships should match manifest.json.

6. Hand off the link.

   Return the Drive/Docs URL and, when useful, the local DOCX path or source HTML path. Connector success alone is not enough; the handoff is complete only after the uploaded file and local DOCX structure have been checked against the source report. Keep routine check and preflight details in support artifacts. Do not list internal checks in the user-facing handoff unless a check failed, was unavailable, or produced a user-relevant caveat.

Standards

• Preserve every section, headline claim, metric card, metric definition, source note, chart takeaway, recommendation, caveat, and link from the HTML report.
• Preserve semantic formatting: headings, paragraphs, inline bold/emphasis, inline code, positive/negative colors, links, lists, callouts, metric-card grids, tables, notes, captions, and charts.
• Use DOCX-native structures wherever practical: headings, paragraphs, tables, bullets/numbered lists, links, inline images, paragraph shading, table cell shading, and text styles.
• Keep the report text column readable. Tables, charts, rendered table grids, screenshots, and visual blocks must not exceed the DOCX page text width.
• Preserve charts as inline images rendered from the source visual or its same-data SVG fallback, aligned to the same left edge as text and tables. A chart with missing bars, missing legend swatches, or all-black/all-white marks fails validation even if the DOCX contains an image object.
• Preserve multi-column report blocks. A two-column grid made only of titled mini-tables can remain a two-column rendered image capped to the text width; mixed two-column blocks with narrative text, pills, callouts, or non-table panels should preserve that content natively instead of dropping it.
• Do not expose customer-level details or sensitive links that were intentionally omitted from a sanitized report.
• Do not write Google Docs batch-update artifacts such as seed_requests.json, remote_write_plan.json, or all_requests*.json.

Repairs

Use these fixes when validation exposes a conversion issue:

Local Checks

python3 -m py_compile <REPORT_TO_GOOGLE_DOC_SKILL_DIR>/scripts/report_to_google_doc_plan.py
python3 <REPORT_TO_GOOGLE_DOC_SKILL_DIR>/scripts/report_to_google_doc_plan.py \
  /absolute/path/to/report.html \
  --out-dir /tmp/report_to_google_doc_plan_smoke
jq '.status, .summary' /tmp/report_to_google_doc_plan_smoke/preflight_checks.json
test -f /tmp/report_to_google_doc_plan_smoke/report.docx
test -f /tmp/report_to_google_doc_plan_smoke/docx_upload_plan.json
git diff --check -- plugins/data-analytics/skills/build-report/report-to-google-doc