stakeholder-writing

Stakeholder Writing

Write documents that busy professionals with no context on our work can understand, trust, and act on, and that the user can share without rewriting: reports, proposals, decision memos, cost estimates, status updates, emails, and PR or issue text. This skill owns the reader, the content, the structure, the look, and the final check. Delivery stays with its owners: draft-doc for Google Docs (native .md for living docs, .gdoc for styled deliverables), draft-mail for Gmail, github-pull-request and github-issues for GitHub, documentation-site for Zensical sites, gws for Workspace APIs, fmind-visuals for decks, diagrams-as-code for diagrams, and repository-docs for README and AGENTS.md files.

These are guidelines, not a form. Each one exists to help a busy reader; when one does not help this reader or this document, adapt or drop it, and tell the user what you changed and why. Three never bend: invent no facts, disclose no secrets or private data, and never let a figure mislead.

Workflow

1. Frame the reader and the ask: note who reads, what they already know, the questions they ask first (reader lenses), and the one decision or action you want from them, by when. Choose the document type, the destination, and the reader's language, then start from the matching outline and reshape it to the request. Ask the user when an unknown reader or goal would change the content; otherwise state your assumptions.
2. Gather verified facts and their links: use primary sources and current data, and record each figure's source, date, and scope. Link claims inline to the pages that support them, internal or external, and choose each link for this reader's access and need to know (links). Turn each unknown into a labeled assumption with a plausible range, and show how the conclusion moves across it.
3. Lead with the message: write the one sentence the reader should remember, then an executive summary of about 120 words with the conclusion, why it matters to them, the decision and its deadline, and one or two supporting figures. Follow it with a short Key terms block when the reader meets unfamiliar terms, units, or metrics.
4. Structure by importance: name the subject in the title and give sections short names; open each section with a bold sentence that states its conclusion and close a long one with a short take-home box (headings). Keep the body as short as the decision allows, about one page for a simple one, and move methods, calculations, evidence, and raw data to annexes that the text points to.
5. Write plainly and show it: follow the style guide: plain words, short active sentences, a concrete example per abstract point, and bold that tells the argument to a skimmer. Use a chart or diagram wherever it explains faster than text, with a caption that states its conclusion (visuals).
6. Make the decision easy and honest: number the options and compare them on the same criteria and conditions (benefit, cost, risk, effort, time to value), include doing nothing, recommend one, and say why. State assumptions, limits, residual risks, and what would change the recommendation, and end with next steps that each have an owner and a date.
7. Make it beautiful, natively: a document that looks designed earns attention and trust, so give the look as much care as the words. Use the destination's own features rather than imitating them (platform features), start from the HTML or Markdown report template, and style with ~/.agents/DESIGN.md (Fmind Theme) or customer branding if available, asking for its guide when you lack it.
8. Run the reader check: review the draft against the checklist, fix what fails, and render it where it will be read, such as HTML at desktop and phone widths with playwright. Tell the user what you could not verify and which guidelines you set aside.