office · diff
git:20261013.aca032c to git:20261013.5b99011
12 added, 7 removed. Audit A to A.
---
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.
+ `id` and `hash` it gives. Quote words with `find` only for a phrase inside a block, copied from the `block` view,
+ which gives the block's exact text (the outline shows only its first words). `find` searches the whole document and
+ `nth` counts its exact matches from the top, from 1: quote enough words to be unique (the `search` view ignores
+ case, so its count can differ).
+ 2. **A new document: plant the outline first.** A path that does not exist yet: `office_edit` creates it blank; there
+ is nothing to read 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.
+ why. When its block changed since you read it, the result shows the block as it stands now: someone edited it, and
+ their edit wins. A block that is gone was deleted. Read again and work from what is there; never put your old text
+ back over theirs. Ops in one call run in order, each on what the earlier ops left: a block an earlier op replaced
+ or deleted is gone for the later ones, and one it re-worded has a new hash.
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.