dsh-office-kit 0.4.1 → 0.4.3

package/assets/skills/excel-live-control/references/office-automation.md

@@ -1,13 +1,10 @@
 # The COM object model behind a live edit
 
-What this skill talks to is not a file. It is an out-of-process COM server that happens
-to own a window: every property read and every write is a remote call across process
-boundaries, and every object you hold is a proxy that re-reads state when you ask it.
-That explains most of the rules below.
+The target is an out-of-process COM server that owns a window. Each property read or write
+is a remote call; each object is a proxy that re-reads state. That explains most rules here.
 
 `container_tools/live_excel.py` wraps the common cases. Read this when the CLI has no verb
-for what the task needs, when a call fails in a way the JSON does not explain, or when you
-are extending the tool.
+for the task, a failure is unexplained, or you extend the tool.
 
 ## Reaching the running instance
 
@@ -15,36 +12,33 @@ are extending the tool.
 $app = [Runtime.InteropServices.Marshal]::GetActiveObject('Excel.Application')
 ```
 
-- This is the only supported way to find a *running* instance. `New-Object -ComObject
-  Excel.Application` creates a new, invisible one — never do that for user work.
-- It exists in Windows PowerShell 5.1 (`powershell.exe`). PowerShell 7 (`pwsh`) removed
-  the method, which is why the tool shells out to `powershell.exe` and not `pwsh`.
-- With nothing running it raises `0x800401E3 (MK_E_UNAVAILABLE)`. That is the signal to
-  ask the user to open the workbook, not to launch anything.
-- WPS Spreadsheets registers both `Ket.Application` and `Excel.Application`, so a
-  successful attach to `Excel.Application` does not prove Microsoft Excel is running.
-  `Application.Name` and `Application.Version` are worse than useless here — WPS reports
-  `Microsoft Excel` / `12.0`. Infer the product from `Application.Path`.
-- The running-object table is per user session and survives the process that created the
-  instance. A hidden instance launched for a self-test stays attachable from later calls;
-  it stays invisible until something shows it, and it leaks until `Application.Quit()`.
+- The only supported way to find a running instance. `New-Object -ComObject
+  Excel.Application` creates a new invisible one; never use it for user work.
+- Only in Windows PowerShell 5.1 (`powershell.exe`); PowerShell 7 (`pwsh`) removed it,
+  which is why the tool shells out to `powershell.exe`.
+- Nothing running raises `0x800401E3 (MK_E_UNAVAILABLE)`. Ask the user to open the
+  workbook; launch nothing.
+- WPS registers `Ket.Application` and `Excel.Application`, so attaching does not prove
+  Microsoft Excel. `Application.Name`/`Version` are useless here (WPS reports `Microsoft
+  Excel` / `12.0`). Infer the product from `Application.Path`.
+- The running-object table is per user session and outlives the creating process. A hidden
+  self-test instance stays attachable, invisible until shown, and leaks until
+  `Application.Quit()`.
 
 ## Addressing
 
 `Application` → `Workbooks` → `Workbook` → `Sheets` → `Worksheet` → `Range`.
 
 - Collections are **1-based**: `$book.Sheets.Item(1)`. `Item(0)` throws.
-- `$sheet.Cells` is the whole sheet; `$sheet.UsedRange` is the rectangle that has content
-  or formatting. `UsedRange` is not trimmed by deleting a value in its last cell; treat
-  it as a hint for what to read, never as the boundary of an edit.
-- A1 strings: `A1`, `B4:D9`, `$B$14`, `Sheet1!A1:C9`, `'Build Detail'!E14` (quote sheet
-  names containing spaces). `Range.Address($row_absolute, $column_absolute)` prints one
-  back, e.g. `$r.Address(0,0)` gives `A1:C3`. Prefer reporting the absolute form the user
-  can paste into the Name Box.
-- Sheet names are case-insensitive in .NET-side matching but must match for COM:
-  `$book.Sheets.Item('Build')` throws on `build`. Use `Worksheet.Name` for the exact
-  spelling.
-- Multi-area ranges (`A1:A5,C1:C5`) exist; the tool refuses them for writes because a
+- `$sheet.Cells` is the whole sheet; `$sheet.UsedRange` is the rectangle holding content or
+  formatting. Clearing the last cell does not shrink it: a read hint, never an edit
+  boundary.
+- A1 strings: `A1`, `B4:D9`, `$B$14`, `Sheet1!A1:C9`, `'Build Detail'!E14` (quote names
+  with spaces). `$r.Address(0,0)` gives `A1:C3`; report the absolute form the user can
+  paste into the Name Box.
+- Sheet-name matching is case-insensitive in .NET but exact for COM:
+  `$book.Sheets.Item('Build')` throws on `build`. Use `Worksheet.Name` for spelling.
+- Multi-area ranges (`A1:A5,C1:C5`) exist; the tool refuses them for writes because one
   rectangular `Value2` assignment cannot fill them.
 
 ## Cells: what you write and what comes back
@@ -52,156 +46,136 @@ $app = [Runtime.InteropServices.Marshal]::GetActiveObject('Excel.Application')
 | Property | Use it for | Reads back |
 | --- | --- | --- |
 | `Range.Value2` | every value: numbers, text, dates (as serials), booleans, arrays | typed scalars / `Object[,]` |
-| `Range.Formula` | formulas in A1 notation; also the way to read them back | `String`, e.g. `=SUM(B2:B9)` |
+| `Range.Formula` | formulas in A1 notation; also how to read them back | `String`, e.g. `=SUM(B2:B9)` |
 | `Range.FormulaR1C1` | fills where you think in offsets | `String` |
-| `Range.Text` | the *displayed* string (after number format) | per-cell only |
-
-- **`Value2` is type-preserving and locale-blind.** Assign a `Double` and the cell is a
-  number; assign a `String` and it is text — except that the application may *parse* a
-  string that looks like a date, a currency amount, or `=1+1`. Writing `"2026-01-31"`
-  through `Value2` produced the serial `46053` in a date-formatted cell. If the user meant
-  the literal text, store the serial (or the number) and set a number format, or prefix
-  the apostrophe; do not rely on the parse.
-- **`$null` empties a cell.** That is the supported way to clear one value inside a block
-  you are writing.
-- A multi-cell read returns a 2-D `Object[,]` with **1-based** indices. A single cell
+| `Range.Text` | the displayed string, after number format | per-cell only |
+
+- **`Value2` preserves type and ignores locale.** A `Double` stays a number, a `String`
+  stays text — unless the app parses it as a date, currency, or `=1+1`. `"2026-01-31"`
+  written through `Value2` produced serial `46053` in a date-formatted cell. For literal
+  text, store the serial/number and set a number format, or prefix the apostrophe. Never
+  rely on the parse.
+- **`$null` empties a cell**, the supported way to clear one value inside a written block.
+- A multi-cell read returns a 2-D `Object[,]` with **1-based** indices; a single cell
   returns a scalar, so code that always indexes `[1,1]` fails on one-cell ranges.
-- **Errors come back as integers.** A live value of `#DIV/0!` is the Int32 SCODE
-  `-2146826281`; `#VALUE!` is `-2146826273`, `#REF!` `-2146826265`, `#NAME?`
-  `-2146826259`, `#NUM!` `-2146826252`, `#N/A` `-2146826246`. In WPS,
-  `WorksheetFunction.IsError` returns `False` for them and `SpecialCells(16)` throws, so
-  the practical test is "is this value an Int32?" — then read `Range.Text`,
-  `Range.Formula` and `Range.Address(0,0)` for that cell alone.
-- `Range.Text` is a per-cell property. On a multi-cell range WPS returns `DBNull`, so the
-  tool reads it cell by cell (that is why `--display` is capped).
-- **Assigning one formula to a range fills it with relative adjustment.** Setting
-  `A1:A3` to `=B1` gives `=B1`, `=B2`, `=B3`. This is the cheap way to fill a column; it
-  is also the way to accidentally create a formula you did not intend when the target is
-  more than one cell.
-- Dates are serials (`days since 1899-12-30`, the 1900 date system). `DateSerial(y,m,d)`
-  gives the number; a `NumberFormat` gives the look.
-- Formulas are text. There is no calculation on write; the value updates when the
-  application recalculates, which is why `recalc` exists.
+- **Errors are integers.** `#DIV/0!` is Int32 SCODE `-2146826281`; `#VALUE!` `-2146826273`,
+  `#REF!` `-2146826265`, `#NAME?` `-2146826259`, `#NUM!` `-2146826252`, `#N/A`
+  `-2146826246`. WPS returns `False` from `WorksheetFunction.IsError` and throws on
+  `SpecialCells(16)`, so test "is this an Int32?", then read `Range.Text`,
+  `Range.Formula`, `Range.Address(0,0)` for that cell alone.
+- `Range.Text` is per-cell; on a multi-cell range WPS returns `DBNull`, so the tool reads
+  cell by cell (hence the `--display` cap).
+- **One formula assigned to a range fills with relative adjustment**: `A1:A3` = `=B1`
+  gives `=B1`, `=B2`, `=B3`. Cheap for a column, and how unintended formulas appear on
+  multi-cell targets.
+- Dates are serials (`days since 1899-12-30`, 1900 system). `DateSerial(y,m,d)` gives the
+  number; `NumberFormat` gives the look.
+- Formulas are text. Nothing calculates on write; values update on recalc, which is why
+  `recalc` exists.
 
 ## Number formats
 
-`Range.NumberFormat` takes format *codes*, not locales: `#,##0`, `#,##0.00`, `0.0%`,
-`"$"#,##0.00`, `mmm-yy`, `d-mmm`, `@`. Use invariant ASCII codes — the dot is always the
-decimal point inside the code, whatever the machine's `Application.DecimalSeparator`
-says. WPS returns empty strings for `DecimalSeparator`/`ThousandsSeparator`, so do not
-read locale from the app and do not build codes from locale data.
-
-- Format is display only. The stored value keeps full precision; never round data to make
-  it read right.
-- One format per column. Mixing `#,##0` and `#,##0.00` down a single column is the most
-  common visual defect in a live sheet.
-- Percentages carry precision: one decimal for analytical tables, zero for dashboards,
-  two when the differences are small. The code encodes that: `0.0%`, `0%`, `0.00%`.
-- `###` in the window means the column is too narrow for the formatted value, not that
-  the value is wrong. Widen with `ColumnWidth` (points-ish, default about 8.43) or
-  `EntireColumn.AutoFit()`, and check the result with `--display`.
+`Range.NumberFormat` takes codes, not locales: `#,##0`, `#,##0.00`, `0.0%`, `"$"#,##0.00`,
+`mmm-yy`, `d-mmm`, `@`. Use invariant ASCII; the dot is always the decimal point inside a
+code, whatever `Application.DecimalSeparator` says. WPS returns empty
+`DecimalSeparator`/`ThousandsSeparator`: never read locale from the app or build codes from
+locale data.
+
+- Format is display only; values keep full precision. Never round data to make it read
+  right.
+- One format per column; mixing `#,##0` and `#,##0.00` down a column is the commonest
+  visual defect.
+- Precision belongs in the code: `0.0%` for analytical tables, `0%` for dashboards,
+  `0.00%` when differences are small.
+- `###` means too narrow, not wrong. Widen with `ColumnWidth` (default ~8.43) or
+  `EntireColumn.AutoFit()`, then check with `--display`.
 
 ## Colour is BGR
 
-`Interior.Color` and `Font.Color` are OLE colour longs written `0xBBGGRR`, while every
-spec in this repo is `#RRGGBB`. Convert explicitly:
+`Interior.Color` and `Font.Color` are OLE longs `0xBBGGRR`; specs are `#RRGGBB`:
 
 ```
 ole = red + green * 256 + blue * 65536        # #RRGGBB -> BGR long
 ```
 
-`#C00000` becomes `192`; a pure blue fill becomes `16711680`. Setting `ColorIndex = -4142`
-removes a fill (`Interior.Color` then reads back `16777215`). Theme colours and tints are
-not addressable this way: if the workbook's palette matters, use the workbook's own
-existing colours rather than inventing one.
+`#C00000` becomes `192`; pure blue fill is `16711680`. `ColorIndex = -4142` removes a fill
+(`Interior.Color` then reads `16777215`). Theme colours and tints are not addressable;
+reuse existing workbook colours.
 
 ## Font, borders, alignment, layout
 
 - `Range.Font`: `Name`, `Size`, `Bold`, `Italic`, `Color`, `Underline`, `Strikethrough`.
-  One family across the sheet; the repo default is Helvetica Neue → Helvetica → Arial →
-  Aptos, whichever the workbook already uses.
-- `Range.Borders.Item(index)`: 7 left, 8 top, 9 bottom, 10 right; `LineStyle` (1 continuous),
-  `Weight` (2 thin), `Color`. `BorderAround(1, 2)` draws a thin outline in one call.
-- `HorizontalAlignment` / `VerticalAlignment` take `xlHAlign*` constants (`-4131` left,
-  `-4108` center, `-4152` right) and `xlVAlign*` (`-4160` top, `-4108` center, `-4104`
-  bottom). The tool maps the readable names for you.
-- `Range.Merge()`, `Range.UnMerge()`, `Range.WrapText`, `Range.IndentLevel`,
-  `EntireColumn.ColumnWidth`, `Tab.Color`, `Rows.Hidden`.
-- `FreezePanes` lives on `Window`, not on the sheet, and did not stick on a hidden
-  instance in WPS. The tool deliberately has no freeze-pane verb; if the user needs panes
-  frozen, tell them to do it, or do it visibly in a shown window.
-- Whole-sheet `AutoFit` and `Select`/`Activate` are traps: they change the user's view,
-  can take seconds on a large sheet, and `ScreenUpdating` does not hide the flicker from a
-  user who is looking at the window.
+  One family per sheet: Helvetica Neue → Helvetica → Arial → Aptos, whichever the workbook
+  uses.
+- `Range.Borders.Item(index)`: 7 left, 8 top, 9 bottom, 10 right; `LineStyle` (1
+  continuous), `Weight` (2 thin), `Color`. `BorderAround(1, 2)` draws a thin outline in one
+  call.
+- `HorizontalAlignment` takes `xlHAlign*` (`-4131` left, `-4108` center, `-4152` right);
+  `VerticalAlignment` takes `xlVAlign*` (`-4160` top, `-4108` center, `-4104` bottom). The
+  tool maps readable names.
+- Also: `Merge()`, `UnMerge()`, `WrapText`, `IndentLevel`, `EntireColumn.ColumnWidth`,
+  `Tab.Color`, `Rows.Hidden`.
+- `FreezePanes` lives on `Window` and did not stick on a hidden WPS instance. No freeze
+  verb: tell the user, or do it visibly.
+- Whole-sheet `AutoFit` and `Select`/`Activate` change the user's view, can take seconds,
+  and `ScreenUpdating` does not hide the flicker.
 
 ## Objects beside the cells
 
-- **Tables**: `$sheet.ListObjects.Add(1, $range, [Type]::Missing, $has_headers)` creates
-  a `ListObject`. PowerShell cannot reproduce VBA's empty argument positions — pass
-  `[Type]::Missing` for the `Destination` slot. Created tables get localized default
-  names (`表1`), so name them. With `has_headers = 0` the application *generates a header
-  row above the data*, which shifts the values down one row and makes the table one row
-  taller than the range you named. Extend an existing table with `ListObject.Resize`
-  rather than adding a second one over the same cells.
+- **Tables**: `$sheet.ListObjects.Add(1, $range, [Type]::Missing, $has_headers)`.
+  PowerShell cannot reproduce VBA's empty argument positions, so pass `[Type]::Missing` for
+  `Destination`. Tables get localized default names (`表1`); name them. `has_headers = 0`
+  makes the app generate a header row above the data, shifting values down and making the
+  table one row taller than the range. Extend with `ListObject.Resize`, never a second
+  table.
 - **Charts**: `$sheet.ChartObjects().Add(left, top, width, height)` → `.Chart` →
-  `.SetSourceData($range)` + `.ChartType`. `HasTitle`/`ChartTitle.Text` set the title.
-  `ChartType` numbers: column 51, stacked column 52, bar 57, stacked bar 58, line 4, line
-  with markers 65, area 1, stacked area 76, pie 5, doughnut -4120, scatter -4169,
-  scatter with lines 74. A chart over an empty range renders blank — check the source
-  cells before blaming the chart.
-- **Shapes**: `$sheet.Shapes.AddShape(...)`, `AddTextbox`, `AddPicture`. They float over
-  cells and are not part of the used range; anchor them to a cell (`TopLeftCell`) so they
-  move with the data.
-- **Pivots**: `PivotTables`, `PivotFields`. Read and report them; never rebuild one
-  through COM unless the user asked for a new pivot — the field layout is not recoverable
-  from a failed attempt.
-- **Names**: `$workbook.Names`, `Range.Name`. Names break when you delete the cells they
-  point at (`#REF!` in the name), so a rename or a row delete is a contract change.
-- **Conditional formats**: `Range.FormatConditions`. Appending a condition to a range
-  that already has one edits the *existing* set; a "fix" here can silently change rules
-  the user depends on. Read first, and keep the range bounded.
-- **Validation**: `Range.Validation` — same rule. Read the existing rule before writing a
-  new one.
+  `.SetSourceData($range)` + `.ChartType`; `HasTitle`/`ChartTitle.Text` set the title.
+  Types: column 51, stacked column 52, bar 57, stacked bar 58, line 4, line with markers
+  65, area 1, stacked area 76, pie 5, doughnut -4120, scatter -4169, scatter with lines 74.
+  A chart over an empty range renders blank; check the source cells.
+- **Shapes**: `Shapes.AddShape(...)`, `AddTextbox`, `AddPicture`. They float over cells, sit
+  outside the used range, and need `TopLeftCell` anchoring to move with data.
+- **Pivots**: `PivotTables`, `PivotFields`. Read and report; never rebuild through COM
+  unless asked — a failed attempt loses the layout.
+- **Names**: `$workbook.Names`, `Range.Name`. Deleting their cells breaks names (`#REF!`),
+  so a rename or row delete is a contract change.
+- **Conditional formats**: `Range.FormatConditions`. Appending to a range with an existing
+  condition edits that set; read first, keep the range bounded.
+- **Validation**: `Range.Validation`; read the existing rule before writing.
 
 ## Calculation and freshness
 
-- `Application.Calculation`: `-4105` automatic, `-4135` manual. A workbook left in manual
-  mode shows stale numbers after your edit; `recalc` runs `CalculateFull` across every
-  open workbook and reports the mode it found.
-- `CalculateFull` recalculates dependencies, not just the active sheet. `CalculateFullRebuild`
-  rebuilds the dependency tree — use it only when a value looks impossible, because it is
-  slow on a large model.
-- Iterative calculation (`Application.Iteration`) is off by default. Circular references
-  that "worked" for the user are a sign it was on; do not turn it on to make an edit
-  succeed.
+- `Application.Calculation`: `-4105` automatic, `-4135` manual. Manual mode shows stale
+  numbers after an edit; `recalc` runs `CalculateFull` on every open workbook and reports
+  the mode.
+- `CalculateFull` recalculates dependencies, not just the active sheet.
+  `CalculateFullRebuild` rebuilds the tree; use it only when a value looks impossible — it
+  is slow on large models.
+- Iteration (`Application.Iteration`) is off by default. Circular references that "worked"
+  mean it was on; do not enable it to make an edit succeed.
 
 ## Latency, failures, retries
 
-- Every property access is an RPC. A trivial call (`info`, three reads) took about 1.2–1.5 s
-  on this host; a call that formats 100 cells one at a time can take tens of seconds.
-  **Batch**: one `write_range` for a block, one `style_range` for a range, one `set_formula`
-  for a column. Do not loop calls per cell.
-- The default timeout in the tool is 180 s. Raising it is legitimate for a big paste;
-  lowering it below a second will fail on a busy application.
-- Failures you will meet:
-  - `0x800401E3` — nothing is running. Remediate by asking the user to open the workbook.
-  - `0x8001010A` (RPC_E_SERVERCALL_RETRYLATER) — the application is busy (a modal dialog,
-    a recalculation, a user dragging a window). Read again, and if it persists tell the
-    user there is a dialog blocking the app.
-  - "Object required" / a stale proxy — usually after the user closed the workbook you
-    were holding. Re-attach by name; never reuse the old object.
-  - A method that exists in Excel raising "does not contain a method named …" in WPS — the
-    WPS object model is a subset. Fall back to a simpler route (formatting via
-    `Value2`/`NumberFormat` instead of a specialised helper).
-- **Nothing is transactional.** A call that fails halfway leaves the cells it already
-  wrote. The retry protocol is: `read_range` the block, compare with intent, write only
-  what is missing or wrong. Replaying the same batch is how a live document gets
-  duplicated rows.
+- Every property access is an RPC. `info` plus three reads took 1.2–1.5 s here; formatting
+  100 cells one at a time can take tens of seconds. **Batch**: one `write_range` per block,
+  one `style_range` per range, one `set_formula` per column. Never loop per cell.
+- Default timeout is 180 s. Raising it is fine for a big paste; below 1 s fails on a busy
+  app.
+- Failures you meet:
+  - `0x800401E3` — nothing running. Ask the user to open the workbook.
+  - `0x8001010A` (RPC_E_SERVERCALL_RETRYLATER) — app busy (dialog, recalculation, dragged
+    window). Read again; if it persists, tell the user a dialog is blocking it.
+  - "Object required" / stale proxy — usually the workbook was closed. Re-attach by name;
+    never reuse the old object.
+  - An Excel method raising "does not contain a method named …" in WPS: the WPS model is a
+    subset. Fall back to a simpler route (formatting via `Value2`/`NumberFormat`).
+- **Nothing is transactional.** A half-failing call leaves written cells. Retry:
+  `read_range` the block, compare with intent, write only what is missing or wrong.
+  Replaying a batch duplicates rows.
 
 ## The one rule that outranks the rest
 
-A live edit mutates a document the user is looking at and may have unsaved changes in.
-**Read and diff before writing.** `read_range` the target with `--formulas`; note whether
-`info` says the workbook is `saved: false`; then make the smallest write that satisfies the
-request. If the diff shows values you did not expect, stop and ask — the user's unsaved
-work is more important than finishing the task.
+A live edit mutates a document the user is looking at, possibly with unsaved changes.
+**Read and diff before writing.** `read_range` the target with `--formulas`; note
+`saved: false` from `info`; then make the smallest write that satisfies the request. If the
+diff shows unexpected values, stop and ask — unsaved user work outranks finishing the task.

package/assets/skills/excel-live-control/references/read_only_qna.md

@@ -1,59 +1,54 @@
 # Answering questions about a workbook the user has open
 
-Read-only work: no writes, no saves, no restyling. The deliverable is an answer with cell
-references the user can check, not a changed document.
+Read-only: no writes, no saves, no restyling. Deliver an answer with cell references the
+user can check, not a changed document.
 
 ## Reading
 
-- `info` first: which workbook, which sheets, which used ranges, tables, charts, pivots.
-  That tells you where to look and whether the thing the user is asking about even exists.
-- `read_range --formulas` for the cells that matter. You almost always need both: the
-  value tells you *what*, the formula tells you *why*. A number with no formula behind it
-  is an input the user typed; a formula with no precedent is a number you cannot trust.
-- `read_range --display` when the question is about how something *reads* (`###`, a
-  truncated label, a date that shows as a serial). Displayed text follows the number
-  format; the value does not.
-- Read the workbook's own labels — row and column headers, period names, "Actual" vs
-  "Forecast" markers, units — before interpreting a cell. `D14` is only meaningful when
-  you know it is "Q3 advertising spend, USD".
-- The window may be ahead of the disk file. If `info` shows `saved: false`, the numbers
-  you read are the user's unsaved state; say so if the answer would differ from the file.
+- `info` first: which workbook, sheets, used ranges, tables, charts, pivots — and whether
+  the thing asked about exists.
+- `read_range --formulas` for the cells that matter. The value says *what*; the formula
+  says *why*. A number with no formula is a typed input; a formula with no precedent is
+  untrustworthy.
+- `read_range --display` when the question is how something *reads* (`###`, a truncated
+  label, a date shown as a serial): displayed text follows the number format, values do
+  not.
+- Read the workbook's labels — headers, periods, "Actual" vs "Forecast", units — before
+  interpreting a cell. `D14` means nothing without "Q3 advertising spend, USD".
+- The window may be ahead of the file. `info` showing `saved: false` means you are reading
+  the user's unsaved state; say so when the answer would differ.
 
 ## Answering
 
-1. **Locate the output by its labels**, not by guesswork: find the row/column that names
-   the metric and the period the user asked about, then read the intersection.
-2. **Trace the precedent chain** back from the output to labelled assumptions or raw
-   inputs. `read_range --formulas` on each step; stop at cells whose value is typed rather
-   than computed. Reporting an intermediate total as the cause is the classic error.
-3. **Reconcile before asserting.** If a total does not equal the sum of its parts, that is
-   the finding — report the gap and the cells, do not average it away.
-4. **Compute from the underlying values.** A cell showing `1.2` may hold `1.2345`; the
-   answer to "what is the margin" uses the stored value, and if the requested precision
-   needs the rounded number, say that you are using the displayed value.
-5. **Rank drivers** by absolute contribution when the question is "why did it move".
-   Report the top two or three with their cells and amounts, not a list of everything.
-6. **Cite cells** in the reply: `` `Summary!D14` shows 1,234 units because `Build!F7:F12`
-   sums to that ``. A claim without an address is not verifiable.
-7. If two sheets disagree, say which one you believe and why (more recent period, source
-   data rather than a copy, a formula chain rather than a paste), and do not "fix" either
-   without being asked.
+1. **Locate the output by its labels**, not by guessing: find the metric's row/column and
+   the period, then read the intersection.
+2. **Trace the precedent chain** back to labelled assumptions or raw inputs. Use
+   `read_range --formulas` at each step; stop at typed cells. Reporting an intermediate
+   total as the cause is the classic error.
+3. **Reconcile before asserting.** If a total is not the sum of its parts, that is the
+   finding: report the gap and the cells; do not average it away.
+4. **Compute from underlying values.** A cell showing `1.2` may hold `1.2345`; use the
+   stored value, and say so if the requested precision forces the displayed one.
+5. **Rank drivers** by absolute contribution for "why did it move": the top two or three,
+   with cells and amounts, not everything.
+6. **Cite cells**: `` `Summary!D14` shows 1,234 units because `Build!F7:F12` sums to that ``.
+   A claim without an address is unverifiable.
+7. Sheets disagree: say which you believe and why (more recent period, source over copy,
+   formula chain over paste) and do not "fix" either unasked.
 
 ## Sensitive reviews
 
-Clinical records, payroll and individual compensation, customer-level data: answer at the
-level the user asked for and no lower. Inspect structure, formats, dependency chains and
-formulas as evidence, and do not echo restricted values into the chat unless the user
-needs that exact figure to act. If the question cannot be answered without exposing
-personal data, say what you can answer instead.
+Clinical records, payroll/compensation, customer-level data: answer at the level asked and
+no lower. Inspect structure, formats, dependency chains and formulas as evidence; do not
+echo restricted values unless the user needs that figure to act. If the question cannot be
+answered without exposing personal data, say what you can answer instead.
 
 ## Limits
 
-- Do not equate the live window with the saved file, and do not present a read-only
-  question as if you had verified the disk copy.
-- If a formula depends on external links, volatile functions (`NOW()`, `RAND()`) or a
-  pivot cache that has not been refreshed, say the number is provisional.
-- If the workbook is protect-structured or the sheet is protected, reads still work;
-  report the protection rather than working around it.
-- `#REF!`, `#DIV/0!` and friends in the cells are part of the answer, not noise: name the
-  cell, the formula and what it broke.
+- Do not equate the live window with the saved file, or present a read-only answer as
+  verified against disk.
+- External links, volatile functions (`NOW()`, `RAND()`) or an unrefreshed pivot cache make
+  the number provisional; say so.
+- Protected sheets: reads work; report the protection, do not work around it.
+- `#REF!`, `#DIV/0!` and friends are part of the answer: name the cell, the formula and what
+  it broke.