@sheetxl/skills 0.0.0-stage → 0.8.0-beta.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,532 @@
1
+ ---
2
+ name: analysis
3
+ description: "Audit and repair a workbook — find what is wrong and prove you fixed it. The anomalies read — what the engine has already flagged as breaking a pattern, ranked, with its evidence; the shape sweep that finds defects before you look at a single value; the catalogue of which convention lives in which feature partition, where a hardcode is a hole and an outlier is a one-cell region; sibling sheets as a control group; formula errors (#REF!, #VALUE!, #NAME?, #DIV/0!, #N/A, circular references) counted, located and traced to their root; the blast radius before you write; fixing at the root; and verifying by recount and re-partition. Load when the task is auditing, reviewing, checking, explaining or repairing a spreadsheet, or when asked whether a model is correct. Triggers on: analyze, audit, review, check, is this right, find bugs, fix my sheet, broken spreadsheet, formula error, #REF, #VALUE, #NAME, #DIV/0, #N/A, circular reference, hardcode, broken link, inconsistent, sanity check, explain this sheet, what is wrong, root cause, precedents, dependents, blast radius, sign convention, unit mismatch, color convention, anomalies, flagged, what breaks the pattern, verify the fix, best practice violations."
4
+ ---
5
+
6
+ # Analysis — Audit and Repair
7
+
8
+ > Part of the SheetXL skill suite. See the root `SKILL.md` for routing,
9
+ > `reading.md` for the read surface this builds on, and `writing.md` for making
10
+ > the change. Code below is run-context code (`scripting.md`): snippet form — no
11
+ > `await`, nothing to import.
12
+
13
+ **In this file:** Loud — count and locate · Flagged — the anomalies read ·
14
+ Silent — the shape sweep · Re-partition on the convention's dimension · Sibling sheets are a control group
15
+ · Trace to the root · The blast radius · Fix at the root · Verify ·
16
+ Finding nothing · Reading values — the cheapest rung · The order, end to end ·
17
+ Attended workbooks
18
+
19
+ A spreadsheet with no errors is not a spreadsheet with no bugs. `#REF!` and
20
+ `#DIV/0!` are the defects that announce themselves; the expensive ones are
21
+ silent — a hardcoded number where a formula belongs, a total that stopped
22
+ summing, a link that was pasted over as a value. None of them raise an error,
23
+ and none of them are visible in a printout of the numbers.
24
+
25
+ They are all visible as **shape**.
26
+
27
+ | | Symptom | How you find it |
28
+ |---|---|---|
29
+ | **Loud** | the cell displays an error | count and locate — cheap, do it first |
30
+ | **Flagged** | it breaks the pattern around it, and the engine has already said so | read the `Anomalies` section, highest rank first |
31
+ | **Silent** | it computes, and it is wrong, and nothing around it disagrees | partition, and read the small regions |
32
+
33
+ Command success is never the evidence. For loud defects the evidence is a falling
34
+ error count; for flagged and silent ones it is a finding that has gone, or a
35
+ partition that has stopped having outliers. Everything from *"what does this
36
+ touch"* onward is the same for all three.
37
+
38
+ ## Loud — count and locate
39
+
40
+ The workbook report already did the counting: its roster carries an error count
41
+ per sheet, and its `Errors` and `Calc Failures` sections list the regions,
42
+ sheet-qualified, each with the error literal and the formula behind it. `Errors`
43
+ also lists chart series whose reference has gone `#REF!` — counted apart
44
+ (`3 · 1 in charts`), because no cell holds them and no cell scan finds them. That is
45
+ your baseline. In code, when you want the number alone:
46
+
47
+ ```typescript
48
+ const counts = sheet.getStats().getTypedCounts();
49
+ // counts.error ?? 0 — your "before" (an empty sheet is empty statistics)
50
+ ```
51
+
52
+ Two kinds, kept apart on purpose: an **error** is a successfully calculated error
53
+ *value* (`#DIV/0!` from `=1/0`), a **calc failure** is the engine failing to
54
+ evaluate at all — mostly circular references. A book with zero of one and three
55
+ of the other is still badly broken.
56
+
57
+ To locate, either entrance works. `grep` matches display text, so error tokens
58
+ work directly; `getRegions('error')` partitions by error *value*, so a column of
59
+ forty `#N/A`s is one row rather than forty matches:
60
+
61
+ ```bash
62
+ sheetxl grep "#REF!" book.xlsx
63
+ sheetxl grep "#" book.xlsx # broad sweep
64
+ sheetxl -e "wb.getWorksheet('Model').getRegions('error')" book.xlsx # grouped by value
65
+ ```
66
+
67
+ | Error | Usual root cause |
68
+ |---|---|
69
+ | `#REF!` | deleted rows/columns/sheet a reference pointed at |
70
+ | `#NAME?` | misspelled function or an undefined name |
71
+ | `#VALUE!` | text where a number is expected (often an upstream cell) |
72
+ | `#DIV/0!` | empty or zero divisor — often a missing input, not a formula bug |
73
+ | `#N/A` | lookup with no match — check the lookup range and key |
74
+
75
+ Then jump to *Trace to the root*, below. The rest of the finding half is for the
76
+ defects that never show a `#`.
77
+
78
+ ## Flagged — the anomalies read
79
+
80
+ The engine runs the pattern checks before you ask. Every sheet report carries an
81
+ `Anomalies` section directly after `Calc Failures`; the workbook roster counts
82
+ each sheet's (`anomalies B17:N73 64 cells · 18 regions · formula 15 ·
83
+ sumIncludesSubtotal 5 · …`) and `wb` closes with the workbook's top findings; a
84
+ cell report lists the findings at that cell. The list alone, on any range, sheet
85
+ or the workbook, is `getAnomalies()`, highest rank first; `getCounts('anomalies')`
86
+ says whether there is one to read. When the task names the kind of defect, read
87
+ `wb.getAnomalies({ focus, limit: 25 })` first, over the whole workbook, the next
88
+ window with `offset: 25` (the focus table below maps the task's words to a
89
+ `focus`); the ranked sheet lists come after.
90
+
91
+ ```typescript
92
+ wb.getWorksheet('LBO').getAnomalies()
93
+ ```
94
+
95
+ ```text
96
+ ## Anomalies (56 cells · 24 regions)
97
+ C10 1×1 lookup key is not the label · MATCH key "EBITDA" in row "Entry EBITDA" ($B$10) · here =@INDEX('Ex 10 - …'!C:C,MATCH("EBITDA",…,0))
98
+ Q15:V15 1×6 typed value in a run of formulas · the cells above and below are formulas · here $0.0
99
+ J62 1×1 refers to an empty cell · reads I62 · here =I62
100
+ P13 1×1 font format break · {"weight":700} here, {…} above and below · also changes: fill, alignment · here 'Exit TEV
101
+ C28 1×1 link label mismatch · row "LIBOR" ($B$28) links to "Senior Secured Term Loan B" ('Ex 12 - Debt Schedule'!$B$10) · here ='Ex 12 - Debt Schedule'!F10
102
+ …
103
+ ```
104
+
105
+ One line per finding: a run of cells with the same finding reports once, and the
106
+ same finding in several places is one line ending `also at …` with the others. Each
107
+ line is the address, the check, **the evidence** — the run it breaks, the cell it
108
+ reads, the label it disagrees with, with addresses — and `here`, the anchor's own
109
+ content. The constants formulas type are not lines here: they are the `Constants`
110
+ section after it, each constant with how many places in the workbook type it,
111
+ rarest first — a `12` typed in two places where the model types `365` in twenty is
112
+ the line to read. **The list is ranked**: read it top down, and stop where the lines turn
113
+ into the author's style rather than breaks in it. A line is evidence, never a
114
+ verdict; the next call is yours, and it is usually the cell report at that address.
115
+
116
+ Reading the lines above: `Q15:V15` is a typed row inside a formula block — the
117
+ classic overwritten total. `C28` is a row labeled LIBOR linking to a row labeled
118
+ Senior Secured Term Loan B — a link to the wrong row. `P13`, by contrast, carries
119
+ `also changes: fill, alignment`: a bold cell where the fill and alignment change at
120
+ the same edges is a header, and the line says so. That is the one reading rule
121
+ worth holding: **a lone break is the candidate; a break the other layers share is
122
+ structure.** `one cell each side` marks thin evidence, a cell between two that
123
+ happen to agree. For `format is another role's`, the `N of the sheet's M` is the
124
+ strength of the convention it breaks.
125
+
126
+ The checks, as the report names them:
127
+
128
+ | The line says | It means | Then |
129
+ |---|---|---|
130
+ | `inconsistent formula` | this region's formula differs from the run on both sides of it | compare with the neighbor the line names; one of them is wrong |
131
+ | `typed value in a run of formulas` | a constant where the row or column is otherwise formulas | the overwritten formula; the neighbors say what it was |
132
+ | `omits adjacent cells` · `adds a cell outside its block` · `sum includes a subtotal` · `counted twice` | an aggregate's range disagrees with the block beside it, reaches into another block, holds its own subtotal, or names a cell twice | read the block the line names against the range |
133
+ | `aggregates nothing` | AVERAGE/MIN/MAX of one cell, or a SUM of typed numbers | the range it should cover is the block beside it |
134
+ | `refers to an empty cell` | a reference landing on nothing — often a relative copy that lost its `$` | the cell report: the value usually sits at the anchor's row or column |
135
+ | `link label mismatch` | a pure link whose source row label differs from its target's | the right row is the one whose label matches |
136
+ | `lookup key is not the label` · `approximate match` · `lookup arrays misaligned` | a MATCH key unlike the row's label; a lookup without exact match; INDEX and MATCH over different bounds | the lookup's inputs, one by one |
137
+ | `sign differs from sibling links` | a link negated where the other links into the same row are not | the sign convention of the row it reads |
138
+ | `typed number equals an unread input` | a number typed into a formula that equals an input cell nothing reads (`0.21` where Tax rate holds `0.21`) | the reference it replaced: the input the line names |
139
+ | `differs from its twin formulas` | formulas of the same shape that divide by `12` here and `365` there, or add a term the others take away | which side the business meant; the line names a twin |
140
+ | `off the scale of its format` | a typed percent a hundred times its siblings (`30` for 30%) | the unit it was typed in |
141
+ | `constant` (the `Constants` section) | a constant typed into a formula, with its uses of the workbook's | a constant typed once where the model types another everywhere |
142
+ | `<layer> format break` | an authored font, fill, number format or alignment thin against its run | with `also changes`, structure; alone, a cell someone touched |
143
+ | `<part> format is another role's` | a link, same-sheet reference or calculation colored as the sheet colors another role | the color convention, per sheet: the majority is the rule |
144
+ | `number stored as text` · `unlocked formula` · `reads outside the workbook` | Excel's own checks: text that parses as a number; a formula a user can type over; a reference to another workbook or a deleted one | as Excel would |
145
+
146
+ When the task names the kind of defect, pass it as `focus`: the list is then
147
+ ordered by how often findings like each line's have been that kind of defect in
148
+ audited models, every line still there. Measured on a debugging benchmark whose
149
+ tasks name the defect kind, with each model ranked from the others, this puts
150
+ about 60% more planted defects in the first 25 lines than the ranked list alone,
151
+ and more than reading a hand-picked set of checks first. Task names vary in
152
+ spelling (`Embedded Hardcodes`, `Incorrect SIgn Conventions`): go by the keyword.
153
+
154
+ | The task says | `focus` | Lines about it |
155
+ |---|---|---|
156
+ | a hardcode, a typed-over formula | `embeddedHardcode` | `typed number equals an unread input` · `typed value in a run of formulas` · `Constants` · `format is another role's` |
157
+ | double counting | `doubleCounting` | `counted twice` · `sum includes a subtotal` · `adds a cell outside its block` |
158
+ | an average over the wrong cells | `average` | `omits adjacent cells` · `aggregates nothing` · `adds a cell outside its block` |
159
+ | a bad link, the wrong row or sheet | `crossSheetReference` | `link label mismatch` · `refers to an empty cell` |
160
+ | a lookup | `lookup` | `lookup key is not the label` · `approximate match` · `lookup arrays misaligned` |
161
+ | a copied formula that lost its anchor | `referenceAnchoring` | `refers to an empty cell` · `inconsistent formula` |
162
+ | color coding | `colorCoding` | `format is another role's` · `format break` |
163
+ | a sign | `signConvention` | `differs from its twin formulas` (a term) · `sign differs from sibling links`; then `getStats()` per row |
164
+ | a unit (×12, ×1000, days for months) | `unitMismatch` | `differs from its twin formulas` (a literal) · `off the scale of its format` · `Constants` |
165
+ | deleted rows, broken references | `deletedRows` | `reads outside the workbook` and the `Errors` section |
166
+
167
+ The call, a window at a time, across every sheet; several kinds merge into one
168
+ order:
169
+
170
+ ```typescript
171
+ wb.getAnomalies({ focus: 'unitMismatch', limit: 25 })
172
+ wb.getAnomalies({ focus: ['unitMismatch', 'embeddedHardcode'], limit: 25 })
173
+ ```
174
+
175
+ The next window is the same call with `offset: 25`; a window shorter than the
176
+ limit is the last. On one sheet, `sheet.getAnomalies({ … })`; on a block,
177
+ `range.getAnomalies({ … })`. To read particular checks first instead, name them:
178
+ `getAnomalies({ checks: ['hardcodeInRun', 'styleRole'] })`; with `focus` as well,
179
+ the named checks still list first.
180
+
181
+ For a sign or a unit, know first what the line should carry: [financial-models](financial-models.md)
182
+ has the standard lines' signs and units per model type.
183
+
184
+ **What the read sees is a break.** A row that is wrong in every one of its cells
185
+ breaks nothing beside itself: the same wrong formula from first period to last
186
+ is one consistent region, and the rows above and below are other line items. Those
187
+ are the shape sweep's and the sibling diff's, next, and the semantic judgments —
188
+ monthly or daily, deduction or addition, which of two literals the business meant
189
+ — are yours once the candidates are in front of you.
190
+
191
+ ## Silent — the shape sweep
192
+
193
+ **Before drilling into any sheet, compare the workbook's own descriptions of
194
+ itself against each other.** Every feature is a different view of the same
195
+ cells. When two views disagree about the shape of the same block, the
196
+ disagreement is the finding.
197
+
198
+ The workbook report is most of the sweep for free — its roster carries cell,
199
+ formula and error counts per sheet. One call, then read across:
200
+
201
+ | Compare | The signal | What it means |
202
+ |---|---|---|
203
+ | **formula count vs. cell count**, per column or row of a block | a column with one fewer formula than its neighbors | a formula was typed over with a value |
204
+ | **formula count across sibling sheets** | a filled sheet with *fewer* formulas than its blank template | the model lost a link somewhere it originally had one |
205
+ | **region geometry vs. block geometry** | a `formula` partition that splits where the `contentful` block does not | a hole — and the hole is the defect |
206
+ | **feature count vs. feature regions** | many cells, one region — or many cells, many regions | uniformity, or fragmentation that should not be there |
207
+
208
+ The last one is the general form of the rule: **a count is presence, a partition
209
+ is identity.** Twelve cells carrying a formula is a count. Whether those twelve
210
+ are *one* region or *two* is the audit. Each sheet's report states both on every
211
+ section heading — `Formula (401 cells · 2 regions)` — so the ratio is already in
212
+ front of you: 401 cells in 2 regions is a model, 401 in 300 is noise.
213
+
214
+ For a sweep across sheets that the report does not shape the way you need, the
215
+ loop belongs in the run:
216
+
217
+ ```typescript
218
+ for (const sheet of wb.getWorksheets()) {
219
+ const used = sheet.getUsedRange();
220
+ if (!used) continue; // an empty sheet has no shape to compare
221
+ log(sheet.getName(), sheet.getStats().getCount(), used.getCounts(['formula']));
222
+ }
223
+ ```
224
+
225
+ ### Why shape beats values
226
+
227
+ A number cannot tell you it is wrong. `453.5` in a totals row looks exactly like
228
+ a correct total, at any precision a human will check — and if someone typed it
229
+ from the displayed value, it is correct to one decimal and wrong forever after.
230
+
231
+ But the *shape* of a totals row is unambiguous: every cell in it should carry the
232
+ same authored formula. That is a claim the engine can check across the whole row
233
+ in one call, and it does not depend on knowing what the right answer is.
234
+
235
+ **Audit the invariant, not the output.**
236
+
237
+ ## Re-partition on the convention's dimension
238
+
239
+ `getRegions()` with no argument gives `contentful` — geometry, *where the data
240
+ is*. That view is for orientation and it will tell you a broken model looks fine.
241
+
242
+ Every other feature partitions on **payload identity**: cells belong to the same
243
+ region when they agree on the feature itself. Pass the feature the convention
244
+ lives in, and the convention becomes checkable.
245
+
246
+ **This is the catalogue.** One table, and it is the whole method — pick the row
247
+ whose left column is the claim you are testing. The anomalies read has already
248
+ run the first four rows for you (`inconsistent formula`, `typed value in a run of
249
+ formulas`, `omits adjacent cells`, `format is another role's`); re-partition
250
+ yourself when the convention is one it does not name, or when you want the whole
251
+ partition rather than its breaks:
252
+
253
+ | The convention, or the defect | Partition on | What the break looks like |
254
+ |---|---|---|
255
+ | this row/block should all compute the same way | `formula` | a **one-cell region** in a run of hundreds |
256
+ | this block should be formulas, not typed-in numbers | `formula` | a **hole** — a typed number carries no formula, so it splits the region rather than joining it |
257
+ | an aggregate should cover the block it summarizes | `formula` + region bounds | the `SUM`/`AVERAGE` range disagrees with the `contentful` block beside it |
258
+ | inputs blue, formulas black, cross-sheet links green | `formula` × `font` | a formula class paired with the wrong color |
259
+ | these should all be currency / all be thousands | `numberFormat` | `General` cells inside a formatted run; thousands beside units in one row |
260
+ | this heading should be one merged run | `merge` | the run splits where someone unmerged |
261
+ | the sign convention holds down a column | `numberFormat`, or `getStats()` per column | a min/max sign that disagrees with its neighbors |
262
+ | inputs unlocked, formulas locked (a protected form) | `formula` × `unlock` | a formula inside an editable region — a user can type over the model; or an input cell that is not in the `unlock` partition and cannot be filled in |
263
+ | nothing here should be an error | `error` | the partition exists at all — it groups by error value |
264
+
265
+ Two shapes, and both are readable at a glance: **a hole** (the feature is absent
266
+ where it should be) and **a one-cell region** (the feature is present but
267
+ different). Everything in the table is one of the two.
268
+
269
+ ```typescript
270
+ wb.getWorksheet('Profit and Loss (Monthly)').getRegions(['formula'])
271
+ ```
272
+
273
+ ```text
274
+ # Regions — formula (4)
275
+ N14:N25 12×1 =SUM(N2:N13)
276
+ B26:G26 1×6 =SUM(B14:B25)
277
+ I26:N26 1×6 =SUM(I14:I25)
278
+ B27:N27 1×13 =B26-B21
279
+ ```
280
+
281
+ Row 26 is `Total Expenses`. Eleven months carry `=SUM(x14:x25)`; July — `H26` —
282
+ carries a typed number, so it is not in the partition at all and the row comes
283
+ back split in two. The partition did not need to be told what a total is, what
284
+ the right value was, or which month to suspect. **The gap is the bug report.**
285
+
286
+ Cross two features when the *relationship* is the question — `formula` × `font`
287
+ pairs what each cell computes with the color a human sees, so a cross-sheet link
288
+ that is not green is one row of output. `reading.md` shows the rendered shape
289
+ and the rule for how many features to cross.
290
+
291
+ **A small region is a candidate, not a verdict.** A one-cell region means *this
292
+ cell is different*, not *this cell is wrong*. Sometimes the outlier is correct and
293
+ the run around it is the bug — a subtotal row genuinely differs from the rows it
294
+ totals. And if a model consistently does something unusual, that is its
295
+ convention, not a defect: fix what breaks the pattern, do not impose a pattern the
296
+ model never had. Read the formula and decide before you edit.
297
+
298
+ **A protected sheet that hides its formulas cannot be audited this way.** Its
299
+ report says `formulas hidden`, and there a formula reads as a value: it is absent
300
+ from the `formula` partition, so every hidden formula looks like a hole. Say so
301
+ rather than reporting the holes — or have the user pause the protection first
302
+ (`writing.md` §"Protected sheets").
303
+
304
+ **Partition, do not scan.** The moment you find yourself reading cells to compare
305
+ them, stop — that is the failure mode this exists to replace.
306
+
307
+ ## Sibling sheets are a control group
308
+
309
+ Real workbooks ship their own reference implementation, and it is the cheapest
310
+ evidence available. Template pairs (`Monthly` / `Monthly BLANK`), repeated
311
+ quarters, one sheet per region, last year's tab next to this year's — each twin
312
+ is the same structure with different data.
313
+
314
+ Run the identical partition on both and diff the shape:
315
+
316
+ ```text
317
+ 'Profit and Loss (Monthly)' B26:G26 I26:N26 ← split
318
+ 'Profit and Loss (Monthly BLANK)' B26:N26 ← whole
319
+ ```
320
+
321
+ That upgrades *"H26 looks odd"* to *"H26 was overwritten"* — same file, no
322
+ outside knowledge, one extra call. When a workbook has sibling sheets, comparing
323
+ them is not an optional deepening of the audit; it is the audit.
324
+
325
+ ## Trace to the root
326
+
327
+ Errors cascade: one bad input turns a whole dependency chain into `#VALUE!`. Fixing
328
+ downstream symptoms wastes edits and hides the cause. **The cell is the diagnostic
329
+ lens**; the formula object is the second one, and it answers a different question:
330
+
331
+ ```bash
332
+ sheetxl -e "wb.getRange('D7').getCell()" book.xlsx # value, formula text, the graph
333
+ sheetxl -e "wb.getRange('D7').getFormula()" book.xlsx # the expression analyzed
334
+ sheetxl -e "wb.getRange('D7').createFormula('=<formula>')" book.xlsx # a what-if at D7, unwritten
335
+ ```
336
+
337
+ The **cell** report shows the value, the formula text and the resolved precedents —
338
+ follow the chain upstream until you reach a cell whose error is *not* inherited.
339
+ That cell is the root.
340
+
341
+ The **formula** report answers the other half: the value, then the expression, its
342
+ calculation status, its resolved symbols (a defined name that no longer resolves, a
343
+ function that does not exist — the two silent `#NAME?` causes), its indexed
344
+ references and its tokens. Reach for it when the *text* is the suspect and the
345
+ value alone did not say why. What it does not carry is the graph — precedents and
346
+ dependents live on the cell and the range, which is why the cell comes first.
347
+
348
+ ## Before you edit — the blast radius
349
+
350
+ Tracing upstream tells you *what is wrong*. It does not tell you *what else your fix
351
+ moves*, and a correct fix to the wrong cell is still a broken model. So read the
352
+ graph the other way before you write — and the report you already have has probably
353
+ answered it: every cell, range and name report carries `## Precedents` and
354
+ `## Dependents`, so the `getCell()` you ran during the trace was also the blast
355
+ radius call.
356
+
357
+ ```bash
358
+ sheetxl -e "wb.getRange('H26')" book.xlsx # values, formulas, and both trees
359
+ ```
360
+
361
+ For one direction on its own:
362
+
363
+ | | reads | is read by |
364
+ |---|---|---|
365
+ | one hop | `getDirectPrecedents()` | `getDirectDependents()` |
366
+ | whole chain | `getPrecedents()` | `getDependents()` |
367
+
368
+ All four exist on `ICell`, `ICellRange` **and defined names** (`INamedFormula`), are
369
+ promises (await one before chaining on it), and
370
+ each renders as a flat range listing — one sheet named in the heading, every row
371
+ qualified once the set crosses sheets. The graph is indexed by range,
372
+ so a range is one call rather than a fan-out, and a whole column of dependents is
373
+ one entry rather than four hundred.
374
+
375
+ **What comes back is an `ICellRanges` — a collection of areas, not one range.**
376
+ Its `getCount()` is the number of *areas* (`at(i)` indexes them); the cells are
377
+ `getCounts()`, and `entries()` walks them. Nine areas is not nine precedent
378
+ cells.
379
+
380
+ **The report's tree is the shaped view, and its depth is the blast radius.** The
381
+ top level is one hop. Anything nested is where the change keeps travelling — cells
382
+ you would not have thought to check. A flat tree means the radius is exactly what
383
+ you see.
384
+
385
+ ```text
386
+ ## Dependents
387
+
388
+ D2:D4 3×1 =B2*C2
389
+ D6 6308.8 =SUM(D2:D4)
390
+ B6 400 =SUM(B2:B4)
391
+ D6 ↑ shown above
392
+ ```
393
+
394
+ Editing this block moves `B6` and `D2:D4` directly, and `D6` — the sheet total — one
395
+ hop further on. The tree's grammar — the `↑ shown above` / `↺ circular` marks,
396
+ defined names as labeled nodes, the stated depth and node bounds — is `reading.md`
397
+ §"The dependency graph"; the one mark to act on here is `↺ circular`, a genuine
398
+ cycle. A branch cut at the depth bound is answered by `getPrecedents()` /
399
+ `getDependents()`: the whole transitive reach, flat.
400
+
401
+ Read the radius for its *shape*, not its size. A hundred dependents inside the
402
+ column you are already editing is contained. Three that cross to another sheet or
403
+ land on a reported total is a change to something you were not asked to change — say
404
+ so before you make it, or make it deliberately. And dependents on a range are the
405
+ union over its cells, **not** filtered against the range itself: a block holding
406
+ both formulas and their inputs lists both — "what does this block feed" and "what
407
+ does it feed outside itself" are different questions.
408
+
409
+ **Charts are in the radius.** Nothing recalculates a chart, so the graph does not
410
+ hold one — but a chart plots cells, and the `Dependents` heading counts the charts
411
+ that read the range or anything downstream of it (`· 2 charts`), listed by anchor on
412
+ the `charts` line. Inserting or deleting rows under a chart's data moves its series
413
+ references with the cells, exactly as it moves a formula's; deleting the data leaves
414
+ the series at `#REF!`, which the workbook report then lists under `Errors`.
415
+
416
+ **A formula you have not written yet has a radius too.** Anchor it where it would
417
+ land:
418
+
419
+ ```typescript
420
+ wb.getRange('H26').createFormula('=SUM(H14:H25)')
421
+ ```
422
+
423
+ That computes against the live workbook and commits nothing — the report is the
424
+ value with its references and symbols resolved *at that cell* (`wb.evaluate` for
425
+ the bare number), so what the new formula would **read** is answered before
426
+ anything is written. What it would **feed** is not a property of the formula at
427
+ all: a temporary formula is outside the graph, so the dependents of `H26` — what
428
+ reads that location today — are the downstream half, unchanged by your edit. To
429
+ see downstream *values* move, work on a copy: fork the session (or simply omit
430
+ `--save`), apply the change, and read the dependent set back — the full what-if
431
+ loop is `sessions.md` §"Experiments and what-ifs".
432
+
433
+ ## Fix at the root
434
+
435
+ Make the fix as code (see `writing.md`), batch related fixes into one undo unit, and
436
+ prefer one root fix over N symptom fixes. If the root is a **missing input** rather
437
+ than a wrong formula — common with `#DIV/0!` and `#N/A` — say so instead of
438
+ "fixing" the formula to hide it. That is the user's decision, not yours.
439
+
440
+ ## Verify
441
+
442
+ Loud defects verify by **recount**:
443
+
444
+ ```typescript
445
+ const after = sheet.getStats().getTypedCounts().error ?? 0;
446
+ ```
447
+
448
+ Report `resolved = before − after`, and list what remains with why. If `after` is
449
+ not lower than `before`, your fix did not work — do not report success.
450
+
451
+ Silent defects verify by **re-partition**: run the same partition that found the
452
+ outlier and confirm the small region has merged into the run around it. A partition
453
+ that still has the outlier means the fix did not land, whatever the write reported.
454
+
455
+ Flagged defects verify the same way at lower cost: `getRegions('anomalies')` over
456
+ the range you changed. The finding at that address is gone, and no new one has
457
+ appeared at its neighbors — a fix that turns the cell beside it into the odd one
458
+ out has moved the defect, not removed it.
459
+
460
+ ## Finding nothing
461
+
462
+ **A clean result is the one to distrust.** Audit studies consistently put the share
463
+ of real-world spreadsheets containing at least one error above 90%, so on any
464
+ workbook that has been used for actual work, "I found no defects" is a less likely
465
+ explanation than "I partitioned by the wrong dimension."
466
+
467
+ Before you report clean, check the method rather than the file:
468
+
469
+ - Did you partition by the dimension the convention actually lives in? A model whose
470
+ `Formula` partition is uniform can still have every input miscolored — and the
471
+ sheet report's section headings already named which features are even present.
472
+ A feature with no section cannot hold a defect; one with many regions is an
473
+ invitation.
474
+ - Did you check more than one dimension? One clean partition is one answered
475
+ question, not a verdict.
476
+ - Did you read the `Anomalies` section of every sheet the roster counts them on,
477
+ not only the sheet the task pointed at? The roster line is the index.
478
+ - Did you look past the obvious sheet? Errors cluster in supporting schedules and
479
+ the sheets nobody opens.
480
+
481
+ Then **report what you checked, not just what you found.** *"No outliers in
482
+ `Formula`, `NumberFormat` or `Font` across Operating Model and DCF"* is a
483
+ result you can support. *"The model is clean"* is a claim you cannot.
484
+
485
+ ## Reading values — take the cheapest rung
486
+
487
+ Most analysis needs no values at all: the shape sweep, the partition and the
488
+ region profile answer the question before anything is materialized. When you do
489
+ need them, the three rungs an audit actually lands on, cheapest first:
490
+
491
+ 1. **The region profile** (`sheet.getRegions()`) already carries per-column type,
492
+ bounds, `Σ`, `x̄`, distinct counts, and the authored formula of a uniform
493
+ formula column. Most "what is in this block" questions end here.
494
+ 2. **`range.getStats()`** when you are reducing to an answer — aggregates, order
495
+ statistics, in one pass with nothing materialized.
496
+ 3. **Return the range** when you want to see the cells themselves — an
497
+ A1-addressed table with the `'` text prefix intact.
498
+
499
+ `getValues()` on the same range returns a bare `Scalar[][]` — the same characters
500
+ with the addresses stripped off, so a row has to be located by counting. It is the
501
+ exit door, for when the grid is leaving. And a `for` loop over its result
502
+ producing a sum, a count, or a rewritten column is the tell that `getStats()` or
503
+ `getValuesRange()` was the call. The full contract is `reading.md`.
504
+
505
+ ## The order, end to end
506
+
507
+ 1. **`wb`** — a summary per sheet (content, formula, anomaly and style counts,
508
+ twins) and the error sections. Read the counts against each other — and each
509
+ sheet against its twin — before reading anything else.
510
+ 2. **The anomalies read** — when the task names the defect kind,
511
+ `wb.getAnomalies({ focus, limit: 25 })` over the workbook, a window at a time;
512
+ then each sheet the roster counts them on, its `Anomalies` section top down.
513
+ Every line is a lead with its evidence attached.
514
+ 3. **The shape sweep** — formulas vs. values vs. regions, across columns and
515
+ across sibling sheets. Anything asymmetric is a lead.
516
+ 4. **`getRegions(feature)`** on the dimension the convention lives in. Holes and
517
+ one-cell regions are the findings.
518
+ 5. **The sibling diff** — same partition, twin sheet.
519
+ 6. **`getCell()`** on the suspects only. This is where a lead becomes a diagnosis:
520
+ the missing formula, the dependents that inherit the error.
521
+ 7. **`getFormula()`** to quantify — its value, and the symbols and references
522
+ behind it.
523
+ 8. **The blast radius**, then the fix at the root, then the proof.
524
+
525
+ Steps 1–5 are shape and cost almost nothing. By the time you materialize a single
526
+ value you should already know which cell you are materializing and why.
527
+
528
+ ## Attended workbooks
529
+
530
+ If the workbook is open in an attended session, do all of the above through the session
531
+ (`run`), and `highlight` the cells as you walk the user through what you found — see
532
+ `interactive.md`.