---
name: office
description: "Use whenever a Word document (.docx) in the workspace is to be written, filled in, edited or commented on and the office_edit tool is available: the user watches your edits appear live in the file pane, under your name, and may edit beside you. Covers drafting a new document section by section, revising one, re-wording, tables, lists, charts, pictures and comment threads. Use the docx skill only when the office tools are not available."
requires_tools: [office_edit]
---

# Writing documents live with the user

The document is open in the user's file pane, or opens there once your first edit to it has run (once per document:
a user who closes it is not pulled back). Every `office_edit` call appears whole, under your name, while the user
watches and may type in the same document. Work like a colleague in a shared document, not like a program writing a
file.

## The workflow

1. **Read first.** `office_read` (outline) before any edit, and again whenever an edit is refused. Target blocks by the
   `id` and `hash` it gives. Quote exact words with `find` only for a phrase inside a block, and copy them from the
   `block` view, which gives the block's exact text; the outline shows only its first words.
2. **A new document: plant the outline first.** One `office_edit` call inserts the title and every section's heading,
   each followed by a pending block (`{"type": "pending", "intent": "…"}`) saying what it will hold. The user sees the
   whole shape at once and can delete a section before you write it.
3. **Then fill one section per call**, replacing its pending block (`{"pending": "<key>"}`). Between calls, say one
   short line in the chat ("Writing the risks section."). A pending block the user deleted is a section they do not
   want: leave it out.
4. **Change only what was asked.** Re-word with `replace` on quoted words (`{"text": …}`), which keeps their
   formatting; replace a whole block only when it all changes.
5. **When an edit is refused,** nothing of the call applied and no one saw any of it. The result names the op and
   shows its block as it stands now: someone edited it, and their edit wins. A block that is gone was deleted by
   someone. Read again and work from what is there; never put your old text back over theirs.
6. **Never touch an open document any other way.** No `write_file`, `patch`, terminal, python-docx or the docx skill on
   it: the editor is its only writer, and anything else is refused or lands as a conflicting copy.
7. **Finish with one line** in the chat saying what you did and what the user can do next (edit, comment, ask for
   another pass). The findings belong in the document, not in the chat.

## Writing rules

- Lead with the answer; a reader skimming the first line of each section gets the point.
- Specifics over adjectives: numbers, names, dates.
- Short paragraphs; lists for parallel items; a table when the reader compares across rows.
- Use the document's own styles (headings, lists, table style): never fake a heading with bold text.

See `references/word.md` for the op formats with examples.