--- name: white_paper_writing description: "Write white papers that frame a problem, present cited evidence and data, and set out a solution approach without a sales pitch in the body. Use when drafting, outlining, reviewing, or revising a white paper, or when planning its design, gating, and distribution." metadata: { "includeInPrompt": true } --- # White Paper Writing ## Purpose This skill produces white papers: long documents that define a problem, present evidence, and set out a solution approach a reader can evaluate on the merits. Scope: long-form-research-writing covers research essays, long features, and reports; technical-proposal-writing covers proposals written to win a specific engagement; copywriting covers conversion pages. This skill owns the white paper format specifically: problem framing, evidence and data presentation, solution approach without a sales pitch in the body, design and gating basics, and distribution. A white paper earns trust in two ways. The evidence holds up when a reader checks the sources. The body stays free of sales language, so the approach section reads as analysis rather than a pitch. ## Workflow 1. Define the audience and the goal. Write down who the paper is for, using role and context rather than a broad label. Examples: support leads at firms with a manual review queue, or platform engineers choosing a data store. Write down what the reader should be able to do or decide after reading. One goal per paper. If two audiences need two different decisions, write two papers or cut one audience. 2. Frame the problem. State the problem in one paragraph before any solution appears. Cover what happens now, who it affects, how often it happens, and what it costs in time, money, or risk. Use measured facts where they exist. Label estimates as estimates and name the basis. A problem framed only as the absence of a product is a pitch, not a paper. 3. Build the outline before drafting. Use this order: title, executive summary, problem, evidence, approach, implementation considerations, limitations, sources. Write the executive summary last, after the body is stable. Each section gets one job, listed in the template skeleton below. 4. Gather evidence under strict rules. - Cite primary sources first: original data, official documents, standards, filings, and direct measurements. Use secondary summaries only when the primary source is not available, and say so. - Label vendor data as vendor data wherever it appears, in the text, in chart notes, and in the sources list. Vendor data can support a point. It cannot carry a point on its own. - Show the method for every chart and table: what was measured, over what period, with what sample or source, and what was excluded. - Allow no uncited statistics. Every number that makes a claim needs a citation on the same line or in the figure note. If a number has no source, cut it or replace it with a sourced range. - Record full source details as you go: author or issuing body, title, date, and link or identifier. Rebuilding a sources list at the end wastes time and drops entries. 5. Plan charts and tables. - Give each chart one message. State that message in the caption. - Use a table when the reader needs exact values. Use a chart when the reader needs a pattern, a comparison, or a change over time. - Label axes, units, and time periods on the chart itself. A reader who sees the chart alone should still read it correctly. - Put the source and method note directly under each figure, not only in the sources list. - Keep chart types plain: bars for comparisons, lines for change over time, and tables for ranked or grouped values. Skip decorative chart types that need a legend to decode. 6. Draft the body under the writing rules. - Keep sales language out of the body. No product claims, no pricing, no superlatives about a company or a product, and no calls to action until the closing page. - Put the call to action only at the end, on its own page or in a short closing block: what to read next, who to contact, or where to get the full data set. - Write the approach as a method a reader could apply with any tooling. Name a specific product only where the method truly depends on it, and say why. - State limitations in the paper itself: where the evidence is thin, which settings the data does not cover, and what would change the conclusion. - Use plain sentences and short paragraphs. Define each technical term at first use. - Length guidance, as ranges for planning rather than rules: a short paper runs 1,500 to 3,000 words, a standard paper runs 3,000 to 6,000 words, and a deep technical paper runs 6,000 to 10,000 words. Cut to fit the evidence. A paper with 3,000 words of evidence should stay near 3,000 words. 7. Apply the design basics. - Cover: title, subtitle that states the problem, date, and version. One visual at most, and only if it informs. - Table of contents: include one for papers over about 3,000 words, with page numbers or links that match the final file. - Headings: one style, consistent numbering or no numbering, and heading text that states the section job. - Figure captions: number each figure, state its message in one line, and follow it with the source and method note. - Body layout: margins wide enough for notes, a readable body font size, and page numbers on every page after the cover. - Export a final PDF for distribution and keep the source file with the same version label. 8. Decide on gating. - What gating is: gating means a reader gives contact details, usually name and email through a form, before downloading the paper. Ungated means the file or page is open to any reader. - Tradeoffs: gating gives a follow-up path and a count of named readers. Gating also cuts reach, blocks casual sharing of the file, and can lower trust when the form asks for more than the paper is worth. Ungated papers spread further and get cited more easily, and they return no reader contact details. - Decide from the goal set in step 1. Gate only when a defined follow-up exists and someone owns it. Keep the form short. Offer an ungated summary or abstract either way, so a reader can judge the paper before trading details. - Do not assert conversion numbers for gating without a source. If a claim about gating results has no cited source behind it, soften it to a plain tradeoff statement, for example: gating can reduce download volume and can raise follow-up value per reader. 9. Run the distribution checklist. - Final PDF checked against the design basics in step 7, version and date on the cover. - Web version or landing page live, with title, summary, and the download or read link working. - Ungated summary or abstract posted where the audience already reads. - Announcement sent to the existing list or channel, if one exists, with one line on the problem and one line on the evidence. - Social or community posts written from the evidence, each linking to the landing page rather than to a loose file copy. - Internal handoff note sent: who the paper is for, where it lives, and what follow-up the gating form feeds. - Source files, data, and chart files archived under the same version label as the PDF. 10. Run the checker below on the Markdown draft before design work starts. Fix every FAIL line. Read each WARN line and either add the citation or cut the claim. ### Paper template skeleton Copy this skeleton and fill every section. Write "none" or "unknown" where a section has nothing yet, rather than deleting the section. ```markdown # [Title that states the problem or the finding] ## Executive Summary [Problem in two lines. Main evidence in two lines. Approach in two lines.] ## Problem [What happens now, who it affects, how often, and what it costs.] ## Evidence [Findings, each with a citation. Vendor data labeled as vendor data. Method notes for every figure.] ## Approach [The solution approach as a method. No product pitch.] ## Implementation Considerations [Steps, costs, staffing, risks, and dependencies for putting the approach in place.] ## Limitations [Thin evidence, uncovered settings, and what would change the conclusion.] ## Sources [Full source details: author or issuing body, title, date, link or identifier.] ## Next Steps [Call to action only here: what to read next, who to contact, where to get the data.] ``` ### Draft checker Save the code below as paper_check.py, then run it against a draft saved as a Markdown file: ```bash python3 paper_check.py paper.md ``` The checker looks for the required sections, flags numeric claims with no citation nearby as a heuristic, and reports word count. It checks structure and citation placement only. It cannot judge whether a source is sound. ```python #!/usr/bin/env python3 """Check a white paper draft in Markdown for required sections, uncited numeric claims, and word count. Usage: python3 paper_check.py paper.md Exit code 0 when all required sections are present, 1 otherwise. Standard library only. """ import re import sys REQUIRED = [ ("Executive summary", r"executive summary"), ("Problem", r"^#{1,4}\s+problem\b"), ("Evidence", r"^#{1,4}\s+evidence\b"), ("Approach", r"^#{1,4}\s+(solution\s+)?approach\b"), ("Implementation considerations", r"implementation considerations"), ("Limitations", r"^#{1,4}\s+limitations\b"), ("Sources", r"^#{1,4}\s+(sources|references)\b"), ] NUMERIC_CLAIM = re.compile( r"(\d+(?:\.\d+)?\s?%|\$\s?\d|\b\d+(?:\.\d+)?\s?(?:percent|times|x)\b|\b\d{2,}\b)" ) CITATION_HINT = re.compile( r"(\[[^\]]+\]|\(https?://|source:|sources:|see figure|see table|method:)" ) def main(): if len(sys.argv) != 2: print("usage: python3 paper_check.py paper.md") return 2 with open(sys.argv[1], "r", encoding="utf-8") as handle: text = handle.read() lines = text.splitlines() lowered = text.lower() failures = 0 for label, pattern in REQUIRED: found = re.search(pattern, lowered, re.MULTILINE) status = "PASS" if found else "FAIL" if not found: failures += 1 print(f"{status}: section present: {label}") title_found = bool(re.search(r"^#\s+\S", text, re.MULTILINE)) if title_found: print("PASS: title present: top level heading") else: failures += 1 print("FAIL: title present: top level heading") flagged = 0 for index, line in enumerate(lines, start=1): if not NUMERIC_CLAIM.search(line): continue if CITATION_HINT.search(line.lower()): continue window = " ".join(lines[index - 1:index + 1]).lower() if CITATION_HINT.search(window): continue flagged += 1 print(f"WARN: line {index}: numeric claim with no citation nearby: {line.strip()[:90]}") if flagged == 0: print("PASS: no uncited numeric claims flagged by heuristic") else: print(f"INFO: uncited numeric claims flagged: {flagged}") words = len(text.split()) print(f"INFO: word count: {words}") if failures: print(f"RESULT: {failures} required check(s) failed") return 1 print("RESULT: all required checks passed") return 0 if __name__ == "__main__": sys.exit(main()) ``` Worked example. Save this fixture as sample_paper.md: ```markdown # Reducing Manual Review Time in Support Queues ## Executive Summary This paper frames a support review problem and sets out an approach based on cited evidence. ## Problem Teams spend time on repeated manual checks. ## Evidence A cited study reports a 25% share for one task type [1]. An uncited figure says volume rose 40% last year. ## Approach Group similar items, show the source data, and route edge cases for review. ## Implementation Considerations Start with one queue, log decisions, and review errors weekly. ## Limitations The evidence covers one queue type and may not transfer to other queues. ## Sources [1] Example internal log, method: counted tickets by type for one month. ``` Verified run on that fixture: all 7 section checks print PASS, the title check prints PASS, one WARN line flags line 11 for the uncited 40% claim, the checker reports 1 uncited numeric claim flagged and a word count of 116, prints RESULT: all required checks passed, and exits with code 0. On a bare draft with a title and one line of text and no sections, the 7 section checks print FAIL, the word count is 7, and the checker exits with code 1. The WARN heuristic can miss uncited claims and can flag cited ones written in an unusual form, so read the evidence section by hand as well. ## Output Contract A finished run of this skill delivers: - The white paper draft in Markdown or an agreed document format, following the template skeleton, with every section present. - A sources list with full details for every cited claim, and vendor data labeled as vendor data throughout. - Figure files or figure specs for each chart and table, each with a caption, a source note, and a method note. - A checker report: the PASS, FAIL, and WARN lines from paper_check.py, plus a note on how each FAIL was fixed and how each WARN was resolved. - A gating decision in one short paragraph: gated or ungated, the reason tied to the goal, and the fields the form asks for if gated. - A distribution record: where the paper was posted, the date, the version posted, and where the source files are archived. ## Operating Rules 1. One audience and one goal per paper. Name both before drafting starts. 2. Frame the problem before any approach appears. A paper that opens with a solution reads as a pitch. 3. Cite primary sources first. Label vendor data as vendor data in the text, in figure notes, and in the sources list. 4. Allow no uncited statistics. Every claim number needs a citation on the same line or in the figure note under it. 5. Show the method behind every chart and table: what was measured, the period, the sample or source, and what was excluded. 6. Keep sales language out of the body. The call to action appears once, at the end. 7. State limitations inside the paper. Name thin evidence and uncovered settings directly. 8. Treat length ranges as planning aids. Let the evidence set the final length. 9. Do not state gating results as numbers without a cited source. Soften unsourced gating claims to plain tradeoff statements. 10. Keep the paper self-contained. A reader should get the problem, the evidence, and the approach from the paper alone. 11. Version and date every release. Archive source files and data under the same version label as the published file. 12. Write in plain, direct sentences. Cut any sentence that adds length without adding evidence or clarity.