write-report

name

write-report

description

Write or revise the prose summaries for The AI & Work Evidence Observatory dashboard: the intro, the overall synthesis, and the five subtopic sections (productivity, inequality, micro vs macro, entry-level, substitute vs complement). Use whenever the user asks to draft, rewrite, improve, or re-ground the dashboard's written summaries, or to tighten their voice. Grounds the writing in the project's literature review and house style, writes dashboard/data/summaries.json, and rebuilds the pages.

Write the dashboard report

The dashboard's charts are deterministic. Only the prose is written: the intro, an overall synthesis, and one summary per subtopic. Write that prose grounded in the literature review and the extracted evidence, in the house style, then update dashboard/data/summaries.json and rebuild.

Lean on the literature review, not on your own background knowledge. The review is the curated human reading of these papers; it outranks anything you think you know about a study.

Write the sections bottom-up, by aggregating per-paper readings. Each paper already carries a one-sentence finding per subtopic (shown in the digest), a one-line takeaway, and qual notes. Build each section by synthesising those individual readings and the lit-review rows for the papers in scope. Do not write top-down from general knowledge and then look for support.

Papers phrase the same construct differently ("output diversity", "intellectual diversity", "idea variety"; "+30%", "+0.3 SD"). Group like results by meaning, not by exact metric wording, and keep incommensurable units in separate sentences. Rely on each finding's finding_type and text, not on its metric string.

Read these first

1. House style — writing_style_guide.md (repo root). Read it in full and follow it. The quick reference at the bottom of this file is only a reminder, not a substitute.
2. Literature review (primary grounding). Prefer it over your own knowledge, especially for the intro and the overall synthesis.
   • lit_review/Literature Review_ILO - teams & organizations.csv — one row per paper: Title, Summary of Findings, Summary of Method, Limitations, Tasks, Sample, Type of study. This is the curated reading. For each subtopic, pull the rows for the papers in scope and write from their findings and limitations.
   • lit_review/lit_review_paper.pdf — the synthesis write-up. Read it for framing and the throughline. (Local only; it is gitignored. If absent, rely on the CSV.)
3. Structured evidence. Run python3 dashboard/build/summarize.py --digests. It prints, per subtopic, the papers and their reported numbers (a deterministic projection of results.json). Use it for magnitudes and to confirm a claim has support in the data.
4. What to write. dashboard/extraction/subtopics.json lists the subtopics, their focus, place (main/appendix), and whether the evidence is solid or thin.

Match papers across sources by author and year (the CSV uses full titles like "… (2025) – Dell'Acqua et al."; the digests use short labels like "Dell'Acqua et al. 2025"). When the CSV and the digest disagree on a number, trust the digest (it comes straight from the extracted data) and describe it in the review's words.

What to produce

Update dashboard/data/summaries.json. Keep this exact shape; the build reads these keys:

{
  "generated_by": "claude-skill:write-report",
  "model": "<the Claude model you are>",
  "intro":   { "short": "...", "long_md": "..." },
  "overall": { "summary_md": "..." },
  "subtopics": {
    "productivity":          { "label": "Productivity & performance", "summary_md": "..." },
    "inequality":            { "label": "Inequality — who benefits?", "summary_md": "..." },
    "micro_macro":           { "label": "Micro vs macro",             "summary_md": "..." },
    "entry_level":           { "label": "Entry-level jobs",           "summary_md": "..." },
    "substitute_complement": { "label": "Substitute vs complement",   "summary_md": "..." }
  }
}

• intro.short — one or two plain sentences a newcomer understands.
• intro.long_md — one paragraph: what the dashboard is, the subtopics, scope (micro/meso, some conceptual), how to read it (deterministic charts, reviewed written summaries, mixed units never pooled), and data provenance (metalens-datasets). Frame it the way the literature review frames the question.
• overall.summary_md — 2-3 short paragraphs, structured around the four focus topics (productivity, inequality, micro vs macro, entry-level). Open with the single most load-bearing finding stated plainly, not a sweeping claim. Take the topics in turn. Close by marking what is well-evidenced (productivity gains; complement-but-reallocate) versus where evidence is still limited (economy-wide causal effects; entry-level). Do not claim there are "no macro studies" (see the micro_macro rule below).
• each subtopics.<id>.summary_md — 2-3 short paragraphs, aggregated from the per-paper readings for that subtopic: the digest lists each paper's one-sentence finding and reported numbers, and the lit-review CSV gives its Summary of Findings and Limitations. Synthesise across them and cite each study you lean on by its exact short. Keep label exactly as in subtopics.json.

Pull label and the id list from subtopics.json rather than hard-coding them, so a new subtopic flows through.

Grounding rules

• Use only the evidence in the digests and the literature review. Do not invent numbers or papers.
• Cite each paper by its EXACT short label (the "Author Year" string shown in the digest), e.g. "Dell'Acqua et al. 2025", never "Dell'Acqua" or "Dell'Acqua and colleagues". The dashboard auto-links these exact labels to the paper's database entry, so a surname-only or reworded citation will NOT link. Put it in parentheses after the claim, e.g. "matched a two-person team (Dell'Acqua et al. 2025)".
• Never pool or blend incommensurable units (%, SD, multipliers). Do not write one range across them: the line "+30-50% in field settings and about +0.3-0.4 SD" reads as a single finding but mixes percent and standard deviations. Put percent effects and SD effects in separate sentences, each labelled with its unit.
• Write effect sizes as plain signed numbers (+0.42, -0.09). Never write "β=" or the word "beta".
• Surface caveats: context-dependence, null and negative results, non-generative-AI studies, counterexamples. The literature review's "Limitations" column is the place to find them.
• micro_macro: the corpus DOES include macro and meso labour-market studies (employment, wages, hiring, e.g. Humlum, Brynjolfsson, Hampole). Never write that there are "no macro studies in the database". What is limited is rigorous economy-wide CAUSAL identification: large micro gains have not yet been shown to aggregate to clean economy-wide effects. Say that, rather than denying the macro evidence exists.
• entry_level: the evidence is thin and indirect (proxies such as junior scientists and casual contributors). Frame it as emerging. Do not generalize to "AI removes the bottom rung".

House style — quick reference (full guide: writing_style_guide.md)

• Lead with the point in the first sentence. One claim per piece. Order by importance.
• Short sentences. Active voice. Present tense. Plain words ("use" not "utilize", "but" not "however").
• No em dashes. No mid-sentence colons. Give every "this" a noun ("this result", not "this").
• No decorative bold. No self-praise. No throat-clearing ("It is worth noting that").
• Strike the AI tells: delve, leverage, robust, landscape, realm, underscore, foster, "not just X but Y", "from X to Y", rhetorical questions, ending on "In conclusion".
• Read each summary aloud. If you stumble, the reader will too.

Workflow

1. Read writing_style_guide.md, the literature review (CSV, then the PDF for framing), and run python3 dashboard/build/summarize.py --digests.
2. Draft the intro, the overall synthesis, and the five subtopic summaries. Ground each claim in the review and the digests. Write in the house style.
3. Write dashboard/data/summaries.json in the shape above. Set generated_by to claude-skill:write-report and model to your model id.
4. Rebuild and verify:

   cd dashboard
   python3 build/build_dashboard.py   # consumes the published dataset + your summaries -> dashboard.json
   python3 scripts/inline_build.py    # -> standalone/index.html (where the summaries render)
   python3 build/build_landing.py     # -> standalone/landing.html
   python3 build/build_papers.py      # -> standalone/papers.html
   

5. Re-read the rendered summaries against the checklist in writing_style_guide.md. Fix anything that stumbles.
6. Show the user the new summaries (and the diff against the old ones). Do not commit unless asked.

Scope notes

• The summaries render on the Analysis page (index.html): the intro, the overall synthesis, and each subtopic section. The landing page's hero text is fixed in build_landing.py and is not part of this skill.
• The Analysis page is meant to read intro -> overall synthesis -> the four focus topics, without repeating the Overview/landing page. The database overview and the papers-over-time chart live on the landing, so do not restate them here. Write the intro and overall to set up the four topics, not to re-describe the dataset.
• This skill supersedes summarize.py --resummarize (the one-shot API path) for interactive, review-grounded writing. summarize.py --digests remains the shared, deterministic evidence source.