Write a well-structured document or report

This skill turns a request like "write this up" into a document a busy reader can act on after reading the first half page. The standard: the answer comes first, every heading says something, every number has a source, and the reader knows exactly what you need from them and by when.

When to use

• "Write up what we found and send it to me."
• "Put together a proposal / brief / one-pager for X."
• "Draft a report on last month's numbers."
• "We need a policy / process doc / how-to for Y."
• "Write a memo so I can decide between A and B."

What you need

• The reader: who they are, what they already know, what they will do with it. If several readers, write for the one who decides.
• The job of the document: decide, approve, inform, instruct or persuade. One main job per document.
• The material: notes, data, earlier docs, research. Ask for or find it (search_files, session_search, memory) before drafting.
• Constraints: length, deadline, house template or style, format wanted (Word, PDF, Google Doc, plain text in chat).
• If you cannot say who reads it and what they should do afterwards, ask one clarify question before writing.

Method

1. Write the purpose sentence first. "After reading this, [reader] will [decide / do / know] [X]." Keep it at the top of your draft until you finish. Anything that does not serve it goes to an appendix or is cut.

2. Pick the skeleton for the document type. Use references/document-skeletons.md (report, proposal, decision memo, brief, one-pager, how-to or SOP, policy, post-mortem). Do not invent a structure when a standard one fits; readers navigate by familiar shapes.

3. Find the governing thought. Write the single sentence the whole document argues, for example "We should move packaging to Northline in January because it saves 14% with no quality loss." Then group your support into 2 to 5 reasons that do not overlap and together cover the case (this is the pyramid approach: answer, then grouped support, then detail).

4. Open with the answer. The first paragraph or summary box gives, in this order:

   • Situation: the context the reader agrees with (one sentence).
   • Complication: what changed or what is wrong (one sentence).
   • Answer: your conclusion or recommendation (one or two sentences).
   • Ask: the decision or action you need, with a date. For documents longer than 3 pages, put this in an executive summary of no more than half a page (and never more than a tenth of the document). Write it last, place it first.

5. Outline with statement headings. Headings should carry the message: "Churn rose 3 points because onboarding slipped", not "Churn". Read the headings alone in order: they should tell the story. Use at most three heading levels. Number sections in documents over 5 pages so people can refer to "section 3.2".

6. Draft section by section. Rules that hold almost everywhere:

   • One idea per paragraph, opening with the sentence that states it. Three to five sentences.
   • Aim for sentences averaging 15 to 20 words; split anything over about 30.
   • Active voice and named actors: "Finance approved the budget", not "The budget was approved".
   • Use a list for three or more parallel items, a numbered list for steps in order, a table for comparing three or more things across two or more attributes.
   • Numbers carry units, period and source: "£41,200 revenue in September 2026 (shop export)". Round to what matters (two significant figures in prose; exact figures in tables).
   • Mark what you know from what you assume: "Estimate:", "Assumption:", "Not yet confirmed:".
   • Define a term or acronym the first time it appears, or avoid it.

7. Make recommendations specific. Each one says what, who, by when, cost, and why. "Approve £3,000 for a West promotion by 20 Oct; Ada runs it; expected gain £4,500 to £5,500 a quarter." When there are real options, show them side by side with trade-offs and say which you recommend and why the others lose.

8. Edit in four separate passes.

   • Structure: read only the title, summary and headings. Does the argument hold without the body?
   • Clarity: cut filler and long words (references/plain-english-edits.md). Target a 10 to 20% word cut on a first draft.
   • Facts: check every number, name, date and quote against its source. Recalculate totals and percentages.
   • Reader: reread as the reader. What would they ask first? Make sure the answer is on page one.

9. Add the furniture. Title, date, author, version, page numbers. Table of contents for documents over about 10 pages. Sources section or footnotes. Appendix for methods and raw tables.

10. Produce the format asked for (Word, PDF, Google Doc via a connected app, or Markdown in chat) and save it in your work space: ~/Desktop/<your name> - Work space/<job-folder>/. Name it YYYY-MM-DD_topic_type_v01.ext.

Output

• The document, in the requested format, saved in the job folder in your work space.
• A short message to the owner:

  [Title] is ready: [full path].
  Bottom line: [the governing thought in one sentence].
  I need: [decision or input] by [date].
  Open points: [anything unverified or assumed, or "none"].
  

• If the owner asked for text only, give the document in chat with the same structure and no preamble.

Checks before you finish

• The purpose sentence is met, and the first half page carries the answer and the ask.
• Headings read alone tell the story; no heading is a bare topic label.
• Every number has a unit, period and source; totals and percentages recalculated.
• No unexplained acronyms; no paragraph covers two ideas.
• Assumptions and unverified points are labelled as such.
• Dates are absolute ("Fri 9 Oct 2026"), and the weekday matches the date (check with terminal: date -d 2026-10-09 +%A).
• File saved with a clear name in the job folder, and you told the owner where.

Pitfalls

• Chronological storytelling ("First we looked at... then..."). Readers want the conclusion; put the journey in an appendix if at all.
• Topic headings that force the reader to dig for the point. Write the point in the heading.
• Burying the ask in the last paragraph. The ask goes in the opening and is repeated at the end.
• Hedging everything. State a view and its confidence: "Likely (70%) because...". One clear caveat beats ten soft ones.
• Invented precision or invented facts. Never fill a gap with a plausible number. Write "not known yet" and say how you would find out.
• Formatting instead of structure. Bold, colours and boxes do not fix a weak argument. Fix the outline first.
• Writing for yourself. Jargon and internal shorthand that the reader does not share. Check against the reader you named in step 1.
• Legal, HR, medical or financial documents (policies, contracts, disciplinary letters, advice): draft them, but flag clearly that a qualified person must review before they are used or sent.

See also: make-word-document, make-pdf-document, build-slide-deck (same storyline, slide form), status-updates-and-handoffs (short recurring updates).