@sheetxl/skills 0.0.0-stage → 0.8.0-beta.15
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.
- package/LICENSE.md +21 -0
- package/README.md +84 -2
- package/SKILL.md +398 -0
- package/package.json +31 -3
- package/references/analysis.md +532 -0
- package/references/charts.md +173 -0
- package/references/cli.md +287 -0
- package/references/embedding.md +74 -0
- package/references/financial-models.md +364 -0
- package/references/interactive.md +194 -0
- package/references/reading.md +708 -0
- package/references/scripting.md +198 -0
- package/references/sessions.md +225 -0
- package/references/setup.md +74 -0
- package/references/showcase.md +32 -0
- package/references/udf.md +400 -0
- package/references/vector.md +129 -0
- package/references/writing.md +368 -0
|
@@ -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`.
|