kyure-a/nix-config/doc-coauthoring

Document coauthoring

Produce a document that its intended readers can understand and use without the conversation that created it. Adapt the collaboration to the user's material and requested level of involvement.

Establish the document's purpose

Use the supplied draft, template, sources, and conversation to identify the audience, the decision or action the document should support, and any required format. Read relevant linked or local material with the tools available in the current environment.

Ask only about missing information that would materially change the document. Bundle related gaps into a small set of questions, and draft independent portions while answers are pending. If reasonable assumptions suffice, state them and proceed. Do not require a process-selection conversation before doing the work.

Keep a distinction between sourced facts, the user's decisions, and unresolved assumptions. An unknown fact is a gap to resolve or label, not a reason to invent evidence.

Draft and refine

Use an existing template or structure when the user supplies one. Otherwise choose a structure that serves the document's purpose; a short document may need no outline or separate sections.

For a new document with sufficient context, create a complete first draft. For a complex decision with unresolved alternatives, develop the central argument first and expose the tradeoffs that actually require the user's judgment. Brainstorm options only when it helps make that decision.

In revisions, preserve settled content and apply feedback to the relevant passages. The user may edit directly or give feedback in conversation. Read direct edits before revising them, and carry clear preferences into the rest of the document.

Use the user's requested document destination and the appropriate available editing tools. Share a reviewable draft or artifact when it is useful; do not require approval for every section or routine edit already covered by the request.

Check the reader's experience

Read the document as someone who has not seen the conversation. Check whether it provides the context, evidence, definitions, decision, and next action its audience needs. Resolve contradictions and remove repetition that obscures the argument.

For a substantial document with unfamiliar readers or consequential decisions, a fresh-reader review can reveal missing context. If independent review is available and useful, give the reviewer only the document and realistic reader questions, then incorporate concrete findings. A small edit normally needs only a focused reread.

Stop when the requested document is complete and remaining uncertainties are clearly identified. Deliver the document with a brief account of material changes and any unresolved decisions. Further questions or another review should serve a specific remaining need.