Report New

Report Packaging (Visual Deliverable)

Turns a process-mining ledger (where time goes, repeated processes, automation, savings, all basis-labelled) into the deliverable an exec says "YES" to: a clean, visual, defensible HTML + PDF. The ledger is the input; this skill renders and persuades. Runs independently of any analysis skill: if input is missing, it asks.

Two hard requirements:

1. Beautiful, concise, grounded. Beat a top consulting deck on design, clarity and brevity (assets/components.html). Less prose, more structure. Recommendations are hyper-specific to this customer: their actual tools, the concrete mechanism, the human remainder. Never invent a number, app, tool or step not in the ledger.
2. PDF == HTML. Exact reproduction: clean page breaks, nothing clipped or split. By design (fixed-size pages + one inlined stylesheet) + a verify step.

Never fabricate. Always nudge. Any missing key input (a ledger, a bound field, a role/department label, client name, logo, cost rate) → STOP and ask in one batched question. Never invent identity, numbers, roles, tools, or steps to fill a gap or smooth a layout. This overrides speed and overrides every default below.

HTML first. PDF only after the user approves (mandatory stop). The user ALWAYS reviews the HTML deck before any PDF exists. Render report.html, show it, then STOP and wait for explicit approval ("yes" / "approved" / "ship it"). Never generate the HTML and the PDF in the same turn; never jump to a PDF or a *-final.* file unprompted. The ONLY PDF allowed before approval is the throwaway /tmp overflow probe in stage 5 (internal QA, never presented as the deliverable). If you have not received approval in this conversation, end your turn after the review step (stage 6). This overrides speed.

---

1. Inputs (1 or many users)

Source: one or more process-analysis*.md files in the working dir. Each file embeds the full ledger as a single fenced ```json code block (the last fenced json block in the file, so a json snippet quoted earlier in the narrative can't be grabbed by mistake); extract that block to get the ledger object, and use the narrative text above it for wording. Each ledger is one observed person (the analysis is single-user by construction). Any producer of the same shape works. Never print a ledger's source filename or any per-person file label anywhere in the deck or appendix (a filename like process-analysis-jane.md is itself an identifier); refer to ledgers by role only.

• Detect the cohort: glob process-analysis*.md (and any paths the user gives), then extract each file's embedded json block. 1 file → single-user report. 2+ → consolidated report (§7 stage 2).
• Each ledger MUST carry meta.user_role (and ideally department) for grouping. If a ledger lacks a role label, ask which role/department it belongs to; never guess.

Expected ledger shape (top-level keys + the leaves the report binds; omit any element whose field is absent, per §2):

• meta: user_role, department, location, window, active_days, measurement_scope, cost_basis (rate, derivation, basis); optional report_title, client.
• exec_rollup: total_repetitive_hours_per_week, automatable_pct, capacity_unlocked_pct, hours_saved_per_year, dollars_saved_per_year_net, fte_capacity_unlocked_this_person, overall_confidence{grade,why}, shown_caveat. Headline figures = {low,base,high,basis}.
• baseline: total_active_hours, active_days, app_time_share[]{app,pct,hours}, deep_work_share.
• processes[]: name, category, role_department, tier, frequency{occurrences_clean,occurrences_possible,period}, time_per_instance_min, common_path{description,approx_coverage_pct}, steps[]{action,app,input,output, time_min,pain,automatable,basis}, automation{verdict,future_state,route, effort_tier,work_nature,mechanism,feasibility,tool,automatable_fraction_low, automatable_fraction_high,human_remainder,automation_cost}, scores{impact_hours,automatability,effort,priority_rank}, confidence{grade}, savings{annual_hours_saved,gross_annual_dollars_saved,net_annual_dollars_saved,payback_months,dominant_uncertainty}.
• systems_landscape[], reasoning_log[](+counts), assumptions[], what_would_sharpen[], narrative_summary, review{reproducibility_note}.

assets/components.html shows the exact field→page binding on sample data.

Intake gate. Ask ONCE in a single batched AskUserQuestion for everything missing. Cosmetic fields take a default on skip; data-affecting gaps are never invented (per the rule above): label them missing/estimated or omit:

• Ledger(s) path/data, and which users form the cohort (if absent or a different shape: ask for the file(s) or the fields above).
• Role/department for any ledger missing it (grouping key, never guessed).
• Cost rate if absent from a ledger (else mark estimated, show derivation).
• Report title (default "<role/team> Automation Map"); client/company name; confidentiality line (default "COMMERCIAL IN CONFIDENCE").
• Client logo (file path or URL). See §4 — always nudge if not given.
• Branding (MemoryLane default / neutral) and orientation (landscape default / portrait).
• Report language + locale (default English; ask if the ledger's meta.location/market suggests Philippines, Malaysia, Czech Republic, Slovakia, Germany, Austria, or Switzerland) and currency if not carried in cost_basis (see §2's locale table for the separator convention + symbol per market).

---

2. Honesty contract (non-negotiable)

The ledger labels every exec number seen / reasoned / estimated with a shown_caveat and a reasoning log. Surface them, or this becomes slop:

• Every headline number carries its basis as a chip (seen green · reasoned blue · estimated amber) or the inline .basis micro-label. No bare numbers.
• shown_caveat near the headlines (cover note + exec summary).
• Scope line in every footer stating the observed population: "Based on 1 observed person (n=1)" or "Based on N observed people across M roles". Cohort totals (summed across the observed people) are real for those people; extrapolation beyond the observed headcount is estimated/unverified.
• Reproduce the reasoning-log verdict count in the appendix header.
• Ranges (low–base–high), never false precision.
• Reconcile across pages. Every per-process figure rolls up to its function subtotal and to the exec headline; a number shown on more than one page matches everywhere. Change one figure → re-derive the rollup. Never hand-edit a headline or a summary cell in the HTML without re-deriving it from the ledger. The chain a reader can reproduce from the inputs printed on any page: per-run time x frequency x automatable% = hours freed; hours freed x the role's loaded rate = annual savings; per-process savings sum to the function subtotal; function subtotals sum to the combined total; the headline restates the combined total. Worked example (shipped): Product (slide deck ~A$3,500 + sprint ~A$500) = A$4k; Marketing (~A$6,200 + ~A$2,800 + ~A$2,000) = A$11k; Measured (2 users) = A$15k; capacity 1h + 3h = 4h/week (5%); 2 + 3 = 5 processes.
• One rounding grain. Round money to a clean grain with "~" (nearest $100/$1k by confidence) and use the SAME grain on every page; no to-the-dollar figures from a thin sample.
• Measured first, extrapolation labelled. Lead with the measured figure ("Measured (N users)"); show any company-wide/extrapolated number as a separate, clearly labelled illustrative/directional row (lower-range, net of licence and rollout costs). Never headline the extrapolated number as fact.
• Commercials stay out of the body. No price, retainer, or minimum-term in the report; at most a neutral "bundled monthly fee". Pricing lives in the quote.
• Render only what the ledger contains. Missing field → omit the element. Anti-slop is the product.

Number + money formatting (house style, from shipped reports; currency follows the ledger, A$ shown as the example).

Locale first, before applying the house style below. The comma-thousands / period-decimal pattern in the examples below (~A$6,200) is the English-market convention (Philippines, Malaysia, Australia, New Zealand business English). It is NOT universal:

• Philippines: ₱ (PHP), English convention (comma thousands, period decimal).
• Malaysia: RM (MYR), English convention.
• Australia: A$ (AUD), English convention.
• New Zealand: NZ$ (NZD), English convention.
• Czech Republic: Kč (CZK), reversed convention: period/space thousands, comma decimal (e.g. ~15.500 Kč or ~15 500,00 Kč, not 15,500.00).
• Slovakia: € (EUR), same reversed convention as Czech (~4 200,00 €).
• Germany / Austria: € (EUR), reversed convention (~4.200,00 €).
• Switzerland: CHF, reversed convention but apostrophe thousands-separator is also common (CHF 4'200.00); confirm with the client which they use. Detect the target locale from the ledger's meta.location/cost_basis.currency and the client's market, then apply THAT locale's separator convention consistently across every page; never default to the English pattern for a non-English-convention market. Rounding grain, ~ usage, and the "New capacity unlocked" wording rules below apply the same regardless of locale, only the separator and symbol change.

Report language. The house style and copy below is written in English. If the client requests the deck in a local language (Filipino/Tagalog, Bahasa Malaysia, Czech, Slovak, German), translate the narrative, page titles, KPI labels, and chip display text into that language, but never translate the underlying ledger enum values (basis: seen|reasoned|estimated, verdict: kill|leave_as_is|redesign|automate, etc.); those stay in English so the JSON keeps parsing/reconciling correctly, only their rendered label changes. Ask which language the deck should ship in during intake (§1) if the client's market suggests it is not English; default to English if unstated.

• Capacity + time reads 1h/week (2%) (no space inside 1h, one space before the parenthesis). Shipped: 1h/week (2%), 3h/week (8%), 4h/week (5%), ~1 FTE (5%).
• Per-process figures and the in-scope table carry ~ and full digits with a comma (~A$6,200, ~A$3,500, ~A$500, total ~A$15,000); exec KPI tiles and the measured/total rows are the rounded grain with NO ~ (A$4k, A$11k, A$15k, A$100k+); the headline reads save A$100k (no ~, no +). ~ is used ONLY on per-process dollars, the in-scope total, and the illustrative figures (~A$100k+, ~1 FTE, ~15% of a workday), never on exec/measured rows or the headline.
• Freed capacity is always phrased "New capacity unlocked" (KPI tile label AND the per-function table column header, identical wording).
• Each per-process tile shows three cells: [avg time per run, frequency ("17 clean (+30 possible)" when the ledger carries both counts, never collapsed to one number)] / [Automatable %] / [Est. annual savings]. The metric cell is the Automatable %, never hours/yr (a percentage is easier to picture).

Data-confidence banner (read the thinness, say it). Compute a tier from the ledger's coverage (total active hours, active days, #people, window) and show it as a one-line .databanner near the headlines (cover + exec); fold it into the scope line too. Tiers and voice:

• rich (≈20+ active days, or n≥3 in a role): "Strong sample, numbers are well-grounded."
• ok (a couple of weeks, decent hours): "Solid first read (N days, n people)."
• light (few days / one person): "Directional first read, not a verdict; ranges wide on purpose."
• thin (e.g. ~7h over 8 days, n=1): say it plainly and stay useful, e.g. "~7h over 8 days, 1 person. Little data, but here's the read: <top finding>. Reasonable extrapolation: <X>. Act on the top one; get more data before the rest." Friendly, confident, actionable, never a disclaimer dump. Thin data also: widen the ranges, push figures to estimated, and lead with the single most reasonable extrapolation + the one action, not a hedge.

Voice, no essays. Short, plain, compelling. Fragments and bullets over paragraphs; label, number, basis, done. The only running prose is the ledger's narrative_summary (<100 words) and the conclusion. State data thinness in ONE line (the banner), never a wall of caveats. Friendly and direct: "little data, here's the read, here's the reasonable extrapolation, here's the one move."

---

3. Design system & assets

In assets/ beside this file:

• report.css — full design system + print rules. Inline it into a <style> tag. The whole report is one self-contained HTML file: CSS inlined, charts as inline SVG/CSS, images as data URIs, no external links, no CDN, no JS. This is what makes the PDF portable and faithful.
• components.html — rendered reference gallery of every section archetype on sample data. Clone these blocks, bind real values, match the look.
• render-pdf.mjs + make-pdf.sh — the PDF pipeline (§7–8).

Brand tokens live in the CSS (do not re-pick): --accent warm amber, --panel deep ink-navy (cover + bands), Inter sans / Geist mono, near-white body.

App/tool logos. Every app named in a process renders its real logo from a maintained icon map (data-URI'd, never linked); for a tool with no logo file, inline a small SVG glyph. Never show a generic globe placeholder in the final deck, and flag any missing icon at verify rather than substituting one.

Tables. Span the full page width with balanced colgroups. Right-align numeric and money columns to the column edge; center small metric columns; never leave left-hugging gaps in wide columns.

---

4. Client logo & company name

The report carries the client's identity, like a consulting deliverable.

• Get it: from the intake answer. If no logo was given, nudge once ("Send the logo file or a link and I'll place it on the cover + every page; otherwise I'll use the company name as a text wordmark.") Proceed either way.
• Embed, never link (PDF portability): a URL → download via curl -L -o /tmp/logo.<ext> "<url>"; then encode to a data URI (base64 -i /tmp/logo.png → data:image/png;base64,…). SVG can be inlined or data-URI'd. Use <img src="data:…"> so it survives into the PDF.
• Cover (page 1): the .cover__client lockup ("Prepared for" + logo), logo max-height:44px, aspect preserved.
• Every page footer: <img class="foot-logo"> (height:14px) + the company name in the footer text. The CSS caps both dimensions; keep aspect ratio for wide and square logos alike.
• Contrast: the cover logo sits on a white plate (CSS) so dark logos read on the dark cover; add .plain if the logo is already light. The footer is light, so a light/white logo there needs a dark plate, add one.
• No logo: show the company name as the wordmark (cover + footer); still nudge.

Per-app icons (time-by-application appendix), and the acquisition gotchas we hit shipping:

• Inline every icon as a data URI: PNG → data:image/png;base64,…, brand SVG → data:image/svg+xml;base64,…. Size each at width:20px;height:20px;border-radius:4px;object-fit:contain.
• A site's favicon.ico is sometimes actually a PNG (one client's was a 231×231 PNG named .ico). Detect with file, convert/rename with sips before use.
• Never use a sprite sheet as a single logo (a 456×76 multi-logo strip is not one icon); fetch the individual brand SVG instead.
• cdn.simpleicons.org can return 0 bytes; fall back to jsdelivr (cdn.jsdelivr.net/npm/simple-icons@<v>/icons/<name>.svg).
• Monochrome brand SVGs need the brand hex injected as fill before inlining (e.g. Slack #4A154B, OpenAI/ChatGPT #10A37F).
• The long-tail "Other" row uses a neutral inline 3-dot glyph (#9B9690), never a brand logo.

---

5. Page model — why breaks stay clean

The report is a stack of .page elements; each is exactly one A4-landscape sheet (fixed size in report.css). Print maps one .page → one PDF page via break-after: page. Pages are composed to fit, not reflowed, so breaks are deterministic and nothing splits mid-element.

• Compose each page to fit; if a section overflows (long step table, many processes), split across more .page blocks.
• The CSS already sets break-inside: avoid on cards/tables/rows and print-color-adjust: exact (backgrounds/chips/gradients print).
• The verify step (§7) flags any overflowing page; fix before approval.
• Portrait: switch @page + --page-w/--page-h (noted in the CSS).

---