office git:20261014.48e66f7A

Immutable. This exact content never changes and is served at /api/v1/blob/bb922acb9226ada4.

---
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.

## Where the document is

- Name a document by its path relative to the workspace, the folder the file pane shows. The same on a folder of the
  user's computer and in a project: `office_edit` always reaches the real document, never a thread's copy. Never `~`,
  `$HOME` or an absolute path outside that folder.
- Nothing to look up first: `office_edit` makes a missing document, and `office_read` says when there is none. No
  `list_files`, terminal or other tool to find or check the place.
- You cannot see pages. For a length the user asks for, count words: about 450 words of body text fill a page. Never
  render or convert the document to check it: the user is reading it live.

## 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 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
   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, or an earlier op of the same call changed it. A block that is gone was deleted or moved, by someone
   or by an earlier op of the call. 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, moved or deleted is
   gone for the later ones (a moved block gets a new id, found in that op's result `ids`), 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.