Export

Skill: Export

Purpose

Export analysis results in different formats for different audiences. Converts pipeline outputs into ready-to-share deliverables.

Invocation

/export slides — generate/refresh Marp slide deck from latest analysis /export email — write an executive summary email (markdown) /export slack — write a concise Slack update (markdown) /export brief — write a 1-page decision brief (markdown) /export data — export analysis data tables as CSV /export gdoc — create a Google Doc with full Analysis Readout (charts, SQL, bookmarks) /export docx — generate a local .docx Word document (no Google upload) /export notion — publish a verified analysis as an approved Notion text page /export receipt — generate full analysis receipt (Reproduce-level audit trail) /export all — generate all text formats + data (does NOT include gdoc, notion, or receipt — use /export gdoc, /export notion, and /export receipt separately)

Instructions

Step 1: Find Source Material

Primary source detection (use exactly ONE of these, in order):

1. outputs/narrative_*.md — if exists, use the most recent by date (check filename date suffix)
2. outputs/analysis_*.md — if narrative absent, use most recent analysis
3. working/pipeline_summary.md — if no outputs/ files exist
4. working/storyboard_*.md — last resort if above are all missing

How to choose when multiple files exist: Sort by filename date (YYYYMMDD or YYYY-MM-DD suffix), use the latest. If no date in filename, use file modification time.

Supporting materials (collect when available, but NOT primary source):

• outputs/charts/*.png — chart images
• outputs/validation_*.md — confidence score
• outputs/close_the_loop_*.md — success tracking + action items
• working/sql_queries/*.sql — SQL queries

If no outputs exist:

• Check working/ for partial results
• If nothing found: "No analysis results to export. Run an analysis first or use /run-pipeline."

Read the primary source in full before generating any export.

Step 2: Generate Requested Format

Format: slides

• If deck already exists, ask: "Deck found at {path}. Regenerate or export as-is?"
• If no deck, invoke Deck Creator agent with latest narrative + charts
• Output: outputs/slides_{DATE}.md

Format: email

• Structure: Subject line + 3-paragraph body (context, key finding, recommendation)
• Tone: Executive-friendly, no jargon, action-oriented
• Include: 1-2 key numbers, the "so what", and a clear ask
• Output file: Write the email content to outputs/email_summary_{DATE}.md where {DATE} is today's date in YYYY-MM-DD format (e.g., email_summary_2026-04-04.md). This specific file path is important for consistent organization.

Format: slack

• Structure: ONE focused update with bold headline + 3-5 bullet points
• Short enough to read in a channel without expanding; one headline, a few bullets
• Use emoji sparingly (checkmarks, arrows only)
• Include: key metric, direction, and recommended action
• Include a data stamp for each key finding (abbreviated format): 50K | Jan-Mar 2026 | EVENTS | B (82)
• Output file: Write to outputs/slack_update_{DATE}.md where {DATE} is today's date in YYYY-MM-DD format (e.g., slack_update_2026-04-04.md)

Format: brief

• Structure: Title + Executive Summary (3 sentences) + Key Findings (numbered) + Recommendation + Next Steps + Appendix (data sources, methodology)
• One page: a reader should get the decision and the evidence without scrolling
• Output file: Write to outputs/decision_brief_{DATE}.md where {DATE} is today's date in YYYY-MM-DD format (e.g., decision_brief_2026-04-04.md)

Format: data

• Export all DataFrames from working/ as CSVs to the outputs/data/ directory
• Filename pattern: Use descriptive names based on what the data represents (e.g., conversion_by_platform.csv, funnel_steps.csv)
• Create outputs/data/README.md documenting each CSV file: columns, row count, use cases, data quality notes
• Export only the source DataFrames that were actually used in the analysis
• Output location: All CSV files in outputs/data/ directory plus outputs/data/README.md manifest

Format: gdoc

Creates a formatted Google Doc from the analysis with embedded charts, styled headings, internal bookmark links, and SQL code blocks. Follows the Analysis Readout template: Summary (30-second read) → Analysis (30-minute read) → Resources.

Formatting source of truth: the google-doc-export skill owns Doc formatting standards (heading hierarchy, image placement, spacing). This path produces that same look by building a local .docx (via gdoc_builder) and uploading with convert_to_google_doc=True — a distinct method from native MCP construction, not a restatement of it.

Step 0: Auth Check

Check if mcp__google-docs__* tools are accessible:

1. Run the auth-preflight skill (it probes with a create call, not a read).
2. If auth works: Proceed to Step 2a. Say nothing about auth.
3. If MCP tools unavailable or auth expired: Say "Connecting your Google account..." and run authorize_google_docs. Follow the browser OAuth flow.
4. If auth still fails after one attempt: Say "Google Docs connection failed. Generating a local Word document instead." Fall through to the docx format (generate .docx only, skip upload). Provide manual upload instructions: "You can upload {docx_path} to drive.google.com manually."

Step 2a: Re-export Detection

Check if outputs/gdoc_export.yaml exists:

import yaml, os
from helpers.pipeline.file_helpers import content_hash

yaml_path = "outputs/gdoc_export.yaml"
if os.path.isfile(yaml_path):
    with open(yaml_path) as f:
        state = yaml.safe_load(f)

    # Check if source has changed
    narrative_path = state.get("source_narrative")
    if narrative_path and os.path.isfile(narrative_path):
        current_hash = content_hash(open(narrative_path).read())
        if current_hash == state.get("source_hash"):
            # Source unchanged — ask user
            url = state.get("document_url", "")
            # Say: "Google Doc already exists at {url}. No analysis changes
            #        detected. Open it, or force re-create?"
            # If user says open: done. If force: continue to Step 2b.

Step 2b: Parse and Build .docx

from helpers.export.gdoc_narrative_parser import parse_pipeline_outputs
from helpers.export.gdoc_builder import build_readout

# Say: "Building document from analysis..."

data = parse_pipeline_outputs(base_dir=".")
docx_path = build_readout(data, output_dir="outputs")

# docx_path is now something like: outputs/report_mobile_checkout_20260403.docx

Confidence gate: If data.confidence_grade is D or F, pause and ask: "This analysis has low confidence (grade {grade}). The document will include a prominent caveat. Create anyway?" If the user says no, abort. If yes, continue.

Step 2c: Upload to Google Drive

# Say: "Uploading to Google Drive..."

result = mcp__google-docs__upload_file_to_drive(
    file_path=docx_path,
    convert_to_google_doc=True
)
# result: {"file_id": "...", "url": "...", "name": "..."}

If upload fails: fall back to .docx. Say: "Drive upload failed. Your analysis is saved locally at {docx_path}."

Step 2d: Write State

import yaml
from datetime import datetime
from helpers.pipeline.file_helpers import content_hash

state_path = "outputs/gdoc_export.yaml"

# Read existing state for version history
existing = {}
if os.path.isfile(state_path):
    with open(state_path) as f:
        existing = yaml.safe_load(f) or {}

version = existing.get("version", 0) + 1
history = existing.get("versions", [])
if existing.get("document_id"):
    history.append({
        "version": existing.get("version"),
        "document_id": existing.get("document_id"),
        "document_url": existing.get("document_url"),
        "created_at": existing.get("created_at"),
    })

narrative_path = _find_latest("narrative_*.md", "outputs")
state = {
    "document_id": result["file_id"],
    "document_url": result["url"],
    "title": data.title,
    "created_at": datetime.now().isoformat(),
    "source_narrative": narrative_path,
    "source_hash": content_hash(open(narrative_path).read()) if narrative_path else None,
    "local_docx": docx_path,
    "charts_embedded": sum(
        1 for f in data.findings
        for sf in f.sub_findings
        if sf.chart_path and os.path.isfile(sf.chart_path)
    ),
    "version": version,
    "versions": history,
}

with open(state_path, "w") as f:
    yaml.dump(state, f, default_flow_style=False)

Step 2e: Post-Upload Verification

After upload, do a quick read-back check:

doc_text = mcp__google-docs__read_document(document_id=result["file_id"])

Quick checks:

• Does the text contain the analysis title?
• Does the text contain "Summary" and "Analysis" headings?
• Does [Chart: appear? (indicates missing chart placeholders made it in)
• Is the document length reasonable (> 500 chars)?

If any check fails, append a note to the report: "Note: some formatting may not have survived conversion. Review the document for any issues."