Reports: gather with scripts, write once, convert by script

Why this playbook exists

A report costs tokens three ways: reading sources in full, drafting the same text several times, and regenerating it per output format. Cut all three: extract facts with scripts into a compact facts file, write the Markdown once, and convert with the bundled scripts.

Workflow

1. Facts first. Put every number, list, and finding into facts.md or facts.json produced by scripts (see the data-analysis skill). Read PDFs by page range (the Read tool's pages argument) or extract text with a script into a file you grep; never load a whole document into the conversation. Reuse the previous report of the same series in Reports/ for structure and terminology instead of re-deriving it.

2. Outline. Use this skeleton unless the series already has its own:

   # Title (date, version)
   ## Executive summary          five lines at most
   ## Scope and method
   ## Findings                   a table: id, area, severity, evidence, recommendation
   ## Recommendations            prioritized
   ## Appendix                   raw tables, test log summaries

3. Write the Markdown once to Reports/<Title> <YYYY-MM-DD>.md. Arabic reports: Modern Standard Arabic, the technical term in English in parentheses on first use, one numeral system throughout (match the series), short sentences, tables instead of prose for comparisons.
4. Convert by script, never by rewriting:
   • HTML: python <skill>/scripts/md_to_html.py report.md report.html --rtl (drop --rtl for English).
   • DOCX: python <skill>/scripts/md_to_docx.py report.md report.docx --rtl.
   • PDF from the HTML with headless Chrome: "C:/Program Files/Google/Chrome/Application/chrome.exe" --headless=new --disable-gpu --no-pdf-header-footer --print-to-pdf="report.pdf" "file:///C:/path/report.html" The scripts need markdown and python-docx (pip install markdown python-docx).
5. Deliver the file paths plus a five-line summary in chat. Never paste the report body into chat.

Style

• Every finding cites its evidence: a file, screen, DocType, test id, or page number.
• No filler: no restating the brief, no generic advice, no repeated headings.
• Keep versions: a new date-stamped file per revision; add one line to the series index or the project CHANGELOG when one exists.
• Word or PowerPoint requested by name with features the scripts do not cover (tracked changes, templates, slides): use the docx or pptx skill from the same Markdown.