@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,364 @@
1
+ # Financial models: how the standard ones are built
2
+
3
+ When you build, complete or audit a financial model, its type has conventions a reviewer expects —
4
+ the lines, their order, their signs and units, where a balance starts and ends. Identify the model
5
+ type from its sheets and labels, read its section below, then follow the workbook's own layout: the
6
+ page says what each line computes, the workbook says where it goes and how it is written. Where the
7
+ two disagree, the workbook's existing rows win.
8
+
9
+ When auditing, a line that breaks its type's convention is a candidate, not a verdict: if the
10
+ model breaks it the same way everywhere, that is the model's own convention; a line that breaks it
11
+ where its siblings keep it is the finding.
12
+
13
+ | model | read | recognize it by |
14
+ | --- | --- | --- |
15
+ | Bond / debt accounting | [debt accounting](#debt-accounting-bonds-under-the-effective-interest-method) | amortization schedule, effective interest, discount/premium/zero-coupon/OID, carrying value, deferred tax on a bond |
16
+ | Debt schedule, cash sweep, LBO | [debt schedules](#debt-schedules-cash-sweeps-and-lbos) | tranches with beginning and ending balances, revolver, term loans, mandatory and voluntary repayment, cash available for debt repayment |
17
+ | Acquisitions | [acquisitions](#acquisitions-consolidation-equity-method-purchase-price-and-accretion) | consolidation worksheet, NCI, goodwill, equity method, investment in affiliate, purchase price allocation, EPS accretion or dilution, synergies vs premium |
18
+ | Real estate | [real estate](#real-estate-rent-roll-revenue-build-noi-and-valuation) | rent roll, units and SF, vacancy and loss-to-lease, EGI, NOI, cap rate, direct cap, reversion |
19
+ | Corporate: three statements, ratios, valuation | [corporate models](#corporate-models-three-statements-ratios-and-valuation) | income statement, balance sheet, cash flow, ratio analysis, DCF, WACC, cost of equity, comps, EV/EBITDA, sensitivity table, FY columns |
20
+
21
+ Conventions that hold across model types:
22
+
23
+ - A balance rolls forward: beginning = prior ending; ending = beginning + flows. Check the last
24
+ period against what it must be (a repaid loan ends at 0; a balance sheet balances).
25
+ - Deductions are negative lines that subtotals add, or positive lines that subtotals subtract —
26
+ whichever the model already does, never both.
27
+ - A new cell takes the sign of the same kind of line nearby: fees shown as negatives elsewhere on the
28
+ sheet mean a new fee line is negative too. With nothing to match: operating expenses and taxes are
29
+ positive; vacancy, loss-to-lease and concessions are negative; repayments are negative. Reading a
30
+ line from another schedule can need a minus, so compare how the two places store it.
31
+ - In a template, a 0 typed across a block that should be calculated is a placeholder for the cell to
32
+ fill, not a value to keep: a total or roll-forward of zeros above real inputs is still to be built.
33
+ - A note on the sheet that deductions are negative binds vacancy and other loss lines, dividends and
34
+ interest, even where a formula elsewhere would be simpler with a positive. Tax and operating
35
+ expense rows often stay positive under the same note; a line whose neighbors show its sign follows
36
+ them.
37
+ - Write a 0 where the convention gives 0 (a deferred tax under a book-equals-tax treatment); leave a
38
+ cell empty only where the line does not apply.
39
+
40
+ ## Debt accounting: bonds under the effective-interest method
41
+
42
+ How a bond (or any debt carried at amortized cost) schedule is conventionally built: discount,
43
+ premium, zero-coupon and original-issue-discount (OID) bonds, with the book–tax split and early
44
+ extinguishment. Read it before filling one; the model's own labels and signs still win where they
45
+ say otherwise.
46
+
47
+ ### The schedule
48
+
49
+ | line | formula | note |
50
+ | --- | --- | --- |
51
+ | Effective (implied) rate | `=IRR(cash flows)` of the issuer's flows: proceeds in, coupons and principal out | when the model lists the flows; otherwise the market rate it states |
52
+ | Beginning balance | first period: the issue price (proceeds); then the prior period's ending | |
53
+ | Interest expense | rate × beginning balance | |
54
+ | Cash coupon | face × coupon rate (0 for a zero-coupon bond) | |
55
+ | Amortization | interest expense − cash coupon | positive for a discount (the balance accretes up to face), negative for a premium |
56
+ | Principal repaid | face (or the extinguishment price) in the period it is paid, else 0 | |
57
+ | Change | amortization | in the last period, see below |
58
+ | Ending balance | beginning + change | |
59
+
60
+ The last period has two layouts, and a model's notes or existing rows decide between them. With
61
+ nothing to go on, a discount or zero-coupon bond usually ends at face: its last change is the
62
+ amortization and the repayment sits on its own line. A premium bond usually ends at 0: its last
63
+ change takes out the whole balance (`=-beginning`).
64
+
65
+ Worked example (invented): proceeds 9,600, face 10,000, 3-year, coupon 2%, so the rate is the IRR
66
+ of +9,600, −200, −200, −10,200: 3.426%. Year 1: interest 328.9, coupon 200, amortization 128.9,
67
+ ending 9,728.9. Year 3: beginning 9,862.2, interest 337.8, amortization 137.8, ending 10,000, and
68
+ the 10,000 repayment on its own line.
69
+
70
+ ### Early extinguishment
71
+
72
+ In the period the bond is retired early: gain or loss = carrying value at retirement − price paid
73
+ (a loss when the price is higher). The principal-repaid line carries the price paid (or the face,
74
+ with the premium in the gain/loss line, as the model lays it out), and the ending balance is 0.
75
+
76
+ ### Income statement and taxes
77
+
78
+ - Interest expense on the income statement is the effective interest, not the coupon. A label like
79
+ "Interest expense (amortization)" is the amortization part alone; "(coupon)" is the cash part.
80
+ - The tax side follows the treatment the task states. Typical statements:
81
+ - Tax carries the bond at face (or at issue price) and amortization is not deductible each year:
82
+ the yearly book–tax difference is the amortization; deferred tax = difference × tax rate, and
83
+ it reverses when the bond is repaid.
84
+ - Tax follows book: no difference, so deferred tax and the deferred-tax balance are 0 in every
85
+ period — write the 0s, do not invent a difference.
86
+ - Deferred tax = −amortization × tax rate, and its direction picks the balance it builds:
87
+ - A discount (issued below face, OID, zero-coupon) has positive amortization, so deferred tax is
88
+ negative and builds a deferred tax **asset**: change in DTA = −deferred tax.
89
+ - A premium (issued above face) has negative amortization, so deferred tax is positive and builds
90
+ a deferred tax **liability**: change in DTL = deferred tax.
91
+ - Where the model carries both balances, the other one stays 0 in every period.
92
+ - Cash taxes = book (GAAP) tax expense − deferred tax expense. The deferred-tax balance rolls
93
+ forward: beginning = prior ending; ending = beginning + the period's change.
94
+
95
+ ### Cash flow and balance sheet links
96
+
97
+ - Financing cash flows: proceeds in the issue period (positive), principal repaid in the repayment
98
+ period (negative). Coupons are operating or financing as the model classifies interest.
99
+ - A "change in cash" line inside a tax balance-sheet block is the principal only: it holds the
100
+ repayment in the repayment period and stays empty in the others. Coupons do not belong on it.
101
+ - Retained earnings roll forward by net income; the liability on the balance sheet is the schedule's
102
+ ending balance.
103
+
104
+ ## Debt schedules, cash sweeps and LBOs
105
+
106
+ How corporate debt is conventionally scheduled: a block per tranche, paid down from the cash the
107
+ model has available. Read it before filling one; the model's own labels and signs still win where
108
+ they say otherwise.
109
+
110
+ ### A tranche
111
+
112
+ | line | formula | note |
113
+ | --- | --- | --- |
114
+ | Beginning balance | the prior period's ending | first period: the opening amount |
115
+ | Mandatory repayment | −original amount × scheduled % | stops at the balance |
116
+ | Voluntary repayment (sweep) | −MIN(cash available to this tranche, balance after mandatory) | never below 0 cash: `-MAX(0, MIN(...))` |
117
+ | Ending balance | beginning + repayments | |
118
+ | Interest | rate × beginning balance, unless the task or a label says average | average: rate × (beginning + ending) / 2 |
119
+
120
+ Repayments are negative and the ending balance adds them. A schedule whose ending row already
121
+ subtracts a positive "repayment amount" is the other convention: follow it.
122
+
123
+ ### The waterfall
124
+
125
+ - Cash available = opening cash + cash flow − minimum cash, as the model's lines give it.
126
+ - The senior tranche takes first. Each junior tranche gets what is left: cash available + the
127
+ (negative) repayments above it.
128
+ - Totals add the tranches. A coverage ratio with no interest to divide by is `IFERROR(..., "n/a")`
129
+ when the model shows it that way.
130
+
131
+ ### The sign of interest
132
+
133
+ Match interest lines the model already shows. With none to match, use the convention for the model:
134
+
135
+ | model | interest |
136
+ | --- | --- |
137
+ | Cash sweep or debt waterfall | positive: rate × balance, and cash available subtracts it |
138
+ | LBO or a debt schedule that feeds the statements or free cash flow | negative: `=-balance*rate`; interest income stays positive |
139
+ | Consolidation or normalization income statement | positive, as an expense the subtotal subtracts |
140
+ | An adjustment in an accretion or dilution bridge | negative: it reduces earnings |
141
+
142
+ Where capex or working capital are typed negative on the sheet, the schedule's interest is negative
143
+ too and the cash flow line links it as is: `=interest`, not `=-interest`. Only where a tranche block
144
+ already shows interest as a positive amount is the line that reads it `=-interest`.
145
+
146
+ ### A revolver with interest on its average balance
147
+
148
+ Interest on the average balance makes the revolver depend on itself. Solve it instead of adding a
149
+ circular reference. With no sweep of other cash, and interest stored negative:
150
+
151
+ ending = (beginning × (1 + rate / 2) − cash flow before revolver interest) / (1 − rate / 2)
152
+
153
+ Worked example (invented): beginning 1,000, rate 6%, cash flow before revolver interest 200. Ending =
154
+ (1,000 × 1.03 − 200) / 0.97 = 855.67. Interest = −(1,000 + 855.67) / 2 × 6% = −55.67. Check: 1,000 −
155
+ 200 + 55.67 = 855.67.
156
+
157
+ ## Acquisitions: consolidation, equity method, purchase price and accretion
158
+
159
+ How a deal is conventionally carried through the numbers. Read it before filling one; the model's
160
+ own labels, signs and notes still win where they say otherwise.
161
+
162
+ ### Consolidation worksheet
163
+
164
+ Columns run acquirer, target, adjustments, consolidated, and the consolidated column adds across.
165
+
166
+ | line | adjustment |
167
+ | --- | --- |
168
+ | Cash | −the cash consideration |
169
+ | Target's equity | eliminated: −target equity |
170
+ | NCI at fair value | consideration ÷ ownership % − consideration |
171
+ | Goodwill | implied total value (consideration ÷ ownership %) − fair value of net assets |
172
+ | Step-ups | fair value − book value of the asset |
173
+
174
+ The income statement adds the two companies line by line. Tax is rate × pretax income and is stored
175
+ positive; the NCI share is target net income × (1 − ownership %), also positive, and net income to
176
+ common subtracts it, even under a label starting "Less:". The NCI share belongs in the adjustments
177
+ column and the consolidated column; net income to common in the consolidated column only. Leave both
178
+ empty in the acquirer's and target's columns. Later balance sheets roll from the
179
+ acquisition date: cash + the change in cash; NCI + NCI's income − its dividends; equity + net income
180
+ to common − common dividends; other lines hold. Dividends are negative in cash flow from financing.
181
+
182
+ ### Equity method
183
+
184
+ - Book value acquired = ownership % × target book value. Excess = price − book value acquired,
185
+ split into identified intangibles and goodwill.
186
+ - Equity income = ownership % × affiliate net income − amortization of the intangibles (intangibles ÷
187
+ life). It is one line on the investor's income statement.
188
+ - Investment in affiliate = cost + equity income − dividends received. The investor pays the purchase
189
+ price in cash and adds it to the investment on the acquisition date. Where the balance sheet has
190
+ its own intangibles and goodwill lines, the price splits across them on that date: investment =
191
+ book value acquired, intangibles and goodwill = their allocated amounts.
192
+ - After the acquisition date, cash = prior cash + the period's net income and non-cash items as the
193
+ supporting schedules give them, and intangibles and goodwill hold.
194
+ - Cash taxes on operations = operating profit × rate. Deferred tax on equity income = equity income ×
195
+ (1 − dividends-received deduction) × rate. Total tax expense adds them.
196
+ - An adjustments column on the balance sheet is after − before, line by line.
197
+
198
+ ### Purchase price allocation
199
+
200
+ - Deferred tax liability on the step-ups = −(asset step-ups) × tax rate: a **negative** line in the
201
+ bridge, because it reduces net assets.
202
+ - Fair value of net assets = book value + step-ups + that negative liability.
203
+ - Goodwill = purchase price − fair value of net assets.
204
+ - Depreciation of a step-up = −step-up ÷ useful life, negative, and the asset's ending = beginning +
205
+ that line.
206
+ - The liability's own schedule opens at the positive amount (`=-bridge line`) and falls each period by
207
+ tax rate × the period's depreciation and amortization.
208
+
209
+ ### Accretion and dilution
210
+
211
+ | line | formula | sign |
212
+ | --- | --- | --- |
213
+ | Synergies, after tax | synergies × (1 − tax rate) | + |
214
+ | Interest on acquisition debt, after tax | −debt × rate × (1 − tax rate) | − |
215
+ | Interest lost on cash used, after tax | −cash × rate × (1 − tax rate) | − |
216
+ | Combined net income | sum of both companies' net income and the lines above | |
217
+ | New shares | stock-funded value ÷ acquirer's share price; stock-funded value is the equity price less debt and cash used | |
218
+ | Pro forma EPS | combined net income ÷ (acquirer's shares + new shares) | |
219
+ | Accretion / (dilution) | pro forma EPS − standalone EPS; % is that ÷ standalone | |
220
+
221
+ A note naming whose tax rate applies decides it; otherwise use the acquirer's. Later years use the same
222
+ new share count.
223
+
224
+ ### Synergies against the premium
225
+
226
+ Value the **after-tax** synergies. Terminal value = final year's after-tax synergy × (1 + growth) ÷
227
+ (discount rate − growth). Net value created = present value of synergies − premium paid, where the
228
+ premium is purchase price − unaffected market cap.
229
+
230
+ ## Real estate: rent roll, revenue build, NOI and valuation
231
+
232
+ How an income-property model is conventionally built — multifamily or commercial — from the rent
233
+ roll to net operating income (NOI) to a direct-capitalization or DCF value. Read it before filling
234
+ one; the model's own labels, units and signs still win where they say otherwise.
235
+
236
+ ### Units: monthly, annual, per unit, per square foot
237
+
238
+ - Rents are quoted **monthly per unit** (or per SF per year for commercial, as the label says).
239
+ Annual revenue = monthly rent × units × 12. A line that drops the 12 is a month, not a year.
240
+ - A per-unit or per-SF column beside annual dollars is a ratio of that line: annual amount ÷ units,
241
+ or ÷ (units × average SF), and ÷ 12 again when the column is monthly ("$/SF/mo", "per unit per
242
+ month"). Read the column header for which; the same divisor applies to every line in the column,
243
+ totals included. In a multifamily or rent-roll model, a column headed only `$/SF` or `/SF` is per
244
+ SF per month: rents there are monthly, so it divides by 12 too.
245
+ - Percent inputs stay percents: a 4.5% vacancy is `0.045` or a reference to the input cell.
246
+
247
+ ### The revenue build
248
+
249
+ | line | formula | sign |
250
+ | --- | --- | --- |
251
+ | Gross potential rent (market rent) | market rent × units × 12 | + |
252
+ | Loss-to-lease | −(market rent − in-place rent) × occupied units × 12, or −GPR × the stated rate | − |
253
+ | Vacancy | −(potential rent) × vacancy rate, or −vacant units × rent × 12 | − |
254
+ | Concessions, credit loss, non-revenue units | −amount or −rate × base | − |
255
+ | Net rental revenue | sum of the lines above | |
256
+ | Other income (parking, fees, reimbursements) | per unit or per space × count × 12 | + |
257
+ | Effective gross income (EGI) | net rental revenue + other income | |
258
+
259
+ Deductions are **negative lines** and the subtotals **add** them (`=SUM(...)` over the block). A
260
+ model that shows a deduction positive and subtracts it is the other convention; follow whichever
261
+ the existing rows use, never mix.
262
+
263
+ ### Operating expenses and NOI
264
+
265
+ - Each expense line: per-unit or per-SF rate × count, a percent of EGI (management fee), or a base
266
+ amount grown each year.
267
+ - Growth: year 1 of a projection is the base-year amount × (1 + growth); each year after is the
268
+ prior year × (1 + growth). The base year itself is the historical or stated figure.
269
+ - NOI = EGI − total operating expenses. Capital items (reserves, tenant improvements, leasing
270
+ commissions, debt service) sit **below** NOI unless the model puts them above.
271
+
272
+ ### Valuation
273
+
274
+ - Direct capitalization: value = stabilized (year-1 or forward) NOI ÷ cap rate. Value per unit =
275
+ value ÷ units; per SF = value ÷ SF.
276
+ - Purchase price from a going-in cap rate: price = NOI ÷ cap rate; total cost adds closing costs
277
+ (price × (1 + cost %)).
278
+ - DCF: cash flow each year = NOI − capital items; terminal (reversion) value = the year after the
279
+ hold's NOI ÷ exit cap rate (or the final year's NOI, as the model states), less selling costs, a
280
+ negative line that net proceeds add;
281
+ value = NPV of the cash flows plus the discounted reversion at the discount rate.
282
+ - Debt metrics: debt yield = NOI ÷ loan; DSCR = NOI ÷ annual debt service; LTV = loan ÷ value.
283
+
284
+ Worked example (invented): 50 units at $1,800/month: GPR = 1,800 × 50 × 12 = 1,080,000. Vacancy 5%:
285
+ −54,000. Other income $75/unit/month: 45,000. EGI = 1,071,000. Expenses 38% of EGI: −406,980. NOI =
286
+ 664,020. At a 5.5% cap rate, value = 12,073,091, or 241,462 per unit; NOI per unit per month =
287
+ 664,020 ÷ 50 ÷ 12 = 1,106.7.
288
+
289
+ ## Corporate models: three statements, ratios and valuation
290
+
291
+ How a company model is conventionally completed — the three statements, the ratio sheet, the cost of
292
+ capital and the valuation bridge. Most of its lines have more than one textbook definition; the
293
+ reviewer expects the one below unless the label or the model's own rows say otherwise.
294
+
295
+ ### Read the model's own definitions first
296
+
297
+ - Before writing a ratio, find where the model already computes its parts: an earlier column of the
298
+ same row, a sibling ratio, the same label on another sheet. Reuse those rows — the debt in Debt /
299
+ Equity is the debt the model uses in Debt / EBITDA and in its EV bridge; the share count in book
300
+ value per share is the one its market cap uses.
301
+ - Complete a row across every period column its block carries, including a date header that extends
302
+ a pattern (`=EOMONTH(prior,12)`) and a stub or pre-operation column the row's siblings fill.
303
+ - A line the task names but the row leaves blank is still yours to fill; a row the task does not
304
+ name is filled only when its block's other rows are.
305
+
306
+ ### Ratios: label → formula
307
+
308
+ | label | formula | note |
309
+ | --- | --- | --- |
310
+ | Debt / Equity, Debt Equity Ratio | (short-term + long-term borrowings) / total equity | "long-term debt to equity" only when the label says long-term |
311
+ | Debt / EBITDA | the same total borrowings / EBITDA | |
312
+ | Payout ratio | dividend per share / diluted EPS | diluted where the model shows both; or total dividends / net profit |
313
+ | Return on average assets | PAT / AVERAGE(opening, closing total assets) | PAT before minority interest: assets carry the minority's share. "Return on total assets" without "average": PAT / closing total assets |
314
+ | Return on (average) equity | PAT / (average) total equity | "attributable" or "after minority" in the label: net profit after minority / (equity − minority interest) |
315
+ | PAT margin | PAT / revenue | |
316
+ | Net (profit) margin | net profit after minority interest / revenue | the model's own line names decide between PAT and net profit |
317
+ | Book value per share | (total equity − minority interest − proposed dividend or preference capital, where the balance sheet lists them) / shares | the shares the model's market cap uses |
318
+ | EBITDA | EBIT + depreciation and amortization | or revenue − operating costs before D&A, as the income statement is laid out |
319
+ | Interest coverage | EBITDA (or EBIT, as labeled) / finance cost | |
320
+ | Receivables, payables, inventory as % of sales or COGS | balance / flow, on the **average** balance where the model's days rows average | a forecast % held at the average of the historical years shown |
321
+ | EV / EBITDA, P / E | enterprise value / EBITDA; price or market cap / earnings | |
322
+ | **Implied** EV / EBITDA, implied P / E | the valuation's own value: (target or average price × shares + debt + minority interest − cash − investments) / EBITDA | not each period's market price; "implied" means from the valuation. The plain multiple beside it uses each period's price; the implied one uses the valuation's single price in every period |
323
+
324
+ ### Cost of equity and WACC
325
+
326
+ - Cost of equity (CAPM) = risk-free rate + beta × equity risk premium.
327
+ - Adjust it as the label says: a **discount** applied to the cost of equity compounds,
328
+ `= CoE × (1 + discount)`; a **premium** (company-specific, size, liquidity) adds, `= CoE + premium`.
329
+ - Post-tax cost of debt = pre-tax cost × (1 − tax rate). WACC = E/(D+E) × Ke + D/(D+E) × Kd × (1 − t).
330
+
331
+ ### Valuation bridge
332
+
333
+ - Equity value = enterprise value − total borrowings + cash and cash equivalents − minority interest.
334
+ Cash includes every cash-like line the balance sheet lists: other bank balances, deposits and
335
+ liquid current investments, not the cash line alone.
336
+ - Value per share = equity value / shares. A sensitivity table of "implied value" against WACC and
337
+ growth tabulates what the valuation summary reports — per share when it reports a price.
338
+ - Terminal value (Gordon growth) = final-year FCF × (1 + g) / (WACC − g), discounted with the final
339
+ year's factor.
340
+
341
+ ### Schedules
342
+
343
+ - Depreciation at a stated rate = rate × (opening balance + capex) unless the model or the task gives
344
+ another base (a half-year convention, a rate on opening only).
345
+ - Closing = opening + additions − depreciation; the next opening is this closing.
346
+
347
+ ### Not meaningful values
348
+
349
+ Where a ratio is undefined or not meaningful — a zero or negative denominator, a near-zero base (a
350
+ loan repaid to a sliver, a growth base of a few units), a negative valuation multiple — write the
351
+ placeholder the model already uses (`NM`, `NA`, `N/A`) as text. Never leave the cell empty or let an
352
+ error show. For multiples: `=IF(IFERROR(x,"NA")<0,"NM",IFERROR(x,"NA"))`.
353
+
354
+ ### Checks
355
+
356
+ A balance check = total assets − (total liabilities + equity), 0 when it balances, unless the model
357
+ already has a check written the other way; then match it. A cash check = closing cash on the cash
358
+ flow − cash on the balance sheet.
359
+
360
+ Worked example (invented): borrowings 120 short + 380 long, equity 1,250, minority 50, PAT 210,
361
+ assets 2,000 opening and 2,200 closing. Debt / Equity = 500 / 1,250 = 0.40. Return on average assets
362
+ = 210 / 2,100 = 10.0%. CoE: 7% + 1.1 × 6% = 13.6%; with a 10% liquidity discount, 13.6% × 1.10 =
363
+ 14.96%, plus a 2% specific premium, 16.96%. EV 3,000, cash 140, other bank balances 60: equity value
364
+ = 3,000 − 500 + 200 − 50 = 2,650.
@@ -0,0 +1,194 @@
1
+ ---
2
+ name: interactive
3
+ description: "SheetXL attended mode: working with a human who has the workbook open right now. Session ownership rules, the highlight tool (mark ranges in their grid — a ranked, individually labelled list of findings they can walk; asks nothing), the prompt tool (one blocking dialog — a question, or a few as steps — shown at the cells each is about), and safe experimentation via forks. Load whenever an attended session exists, or when guiding a user in the live UI. Triggers on: attended session, attended, highlight, mark ranges, show the user, present, presence, prompt user, guide user, draw attention."
4
+ ---
5
+
6
+ # Interactive — Working With a Human
7
+
8
+ > Part of the SheetXL skill suite. See the root `SKILL.md` for routing;
9
+ > `sessions.md` for session mechanics and cell deep links.
10
+
11
+ **In this file:** Attended-mode rules · The two human-loop tools — `highlight`
12
+ and `prompt` · Common patterns
13
+
14
+ An `attended` session means a human has that workbook open in a live UI **right
15
+ now**. This reference covers the rules that keep you and the user in the same
16
+ reality, and the tools for communicating spatially in their UI.
17
+
18
+ ## Attended-mode rules
19
+
20
+ 1. **The attended workbook is the context.** Unqualified references ("B10", "this
21
+ sheet") mean the active attended session — never a file you find on disk.
22
+ 2. **Reach it only through its session** (`run` with that `session_id`).
23
+ Editing the underlying file via CLI or SDK forks state the user's UI cannot
24
+ see.
25
+ 3. **Never open or close attended sessions.** The user's UI owns them. For your own
26
+ isolated work, create a sandbox session.
27
+ 4. **Experiment on a fork, not on the user.** To try something risky against live
28
+ attended state, fork the attended session into a private copy, verify the result
29
+ there, then apply the verified change through the attended session (guarded by
30
+ `original_commit_id`). The full what-if loop is `sessions.md` §"Experiments
31
+ and what-ifs".
32
+ 5. **Narrate spatially.** When you change or discuss cells the user is looking
33
+ at, point — `highlight` a range, and deep-link the addresses you cite in prose
34
+ (`sessions.md`). A highlight beats a cell address in prose.
35
+
36
+ ## The two human-loop tools
37
+
38
+ They split on one question — **am I asking for anything?**
39
+
40
+ | | `highlight` | `prompt` |
41
+ |---|---|---|
42
+ | response | none — informational | blocking — one dialog, answered once |
43
+ | ranges | many, in review order (`working`: one) | one per question (its subject) |
44
+ | lifetime | `finding`/`question`: until the user dismisses them; `working`: until the workbook next changes or you highlight anything else | until answered |
45
+
46
+ Both are UI-only: they never modify workbook data, and they need an **attended**
47
+ session — a sandbox has no grid to render into. Neither will pretend otherwise:
48
+ on a sandbox, `highlight` tells you nothing was marked and `prompt` errors. Take
49
+ either at its word rather than narrating a highlight the user cannot see.
50
+
51
+ Both also **resolve their addresses before rendering anything** — a range that
52
+ does not exist is an error naming the reason, not a silent miss, and what comes
53
+ back is what the grid actually marked (sheet-qualified). If you sent `B2` you
54
+ will see `Sheet1!B2`.
55
+
56
+ (The selection itself belongs to the user — point with `highlight` and deep
57
+ links; never move their cursor.)
58
+
59
+ ### `highlight` — show, ask nothing
60
+
61
+ `highlight` is **declarative within its intent**. A `finding` or `question` call
62
+ **adds** a list the user reviews alongside the earlier ones, and those stay until
63
+ the user dismisses them, one at a time or all together. An empty `ranges` clears
64
+ the intent you pass, and only that one. Nobody has to respond.
65
+
66
+ `working` is different: it is your **cursor** — the one range you are about to
67
+ write. It replaces your previous `working` mark and clears itself as soon as the
68
+ workbook changes (your write landing, or the user's own edit) or you highlight
69
+ anything else. The user never manages it and never sees it in their findings, so
70
+ never use it for something you want them to look at.
71
+
72
+ - `ranges` — `{ range, label? }` entries. **The order is the order the user walks
73
+ them**, so rank a findings list by what matters, not by what your scan hit
74
+ first. Each entry carries its own `label` because that is what the user reads
75
+ on arriving at it — one label across seven findings says the same thing at
76
+ every stop.
77
+ - `intent` — what the marking means: `finding` (look at this — the default),
78
+ `question` (these are the candidates; judge them), `working` (I am about to
79
+ write here — one range).
80
+
81
+ **This is how you hand over a list of results.** An audit that found six
82
+ suspicious cells is one call, ranked, each with its own reason — the user steps
83
+ through it in the grid instead of reading six addresses out of a chat message
84
+ and clicking each one:
85
+
86
+ ```text
87
+ highlight {
88
+ ranges: [
89
+ {range: "P&L!D69", label: "hardcoded — the rest of the row is =-(D44+D54)"},
90
+ {range: "P&L!F12", label: "sign flipped vs. the column"},
91
+ {range: "P&L!B7", label: "General format in a currency column"}
92
+ ],
93
+ intent: "question"
94
+ }
95
+ ```
96
+
97
+ It also narrates a single edit:
98
+
99
+ 1. Before the edit — `highlight` the target with `working`. It shows while your
100
+ write runs and clears itself when the write lands.
101
+ 2. After the edit — `highlight` what changed as a `finding`, and say what you did
102
+ in prose with deep links.
103
+
104
+ A walkthrough — several places, explained in order — is a `finding` list, not a
105
+ series of `working` marks: the user steps through it at their own pace.
106
+
107
+ ### `prompt` — one blocking dialog, at the cells
108
+
109
+ `prompt` puts a question to the user inside the grid and waits for the answer.
110
+ Use it when the work cannot proceed without a decision that is genuinely the
111
+ user's — a missing input, a destructive choice — not for confirmations you can
112
+ express in chat.
113
+
114
+ - **One prompt at a time per session.** While one is waiting on the user,
115
+ another is refused. Wait for the answer, or cancel your task, before asking
116
+ again.
117
+ - **Several related decisions are one prompt.** Pass `questions` (each with its
118
+ own `id`, `message`, `options`, `range`, and a short `header` for its tab)
119
+ instead of `message`. The user moves between them as tabs of one dialog, each
120
+ scrolled to and marked at its own cells, and the answers come back together
121
+ under their ids. If
122
+ they dismiss part-way, you get the answers given so far.
123
+ - **Say what each option does.** An option may carry a `description` — a second,
124
+ quieter line under its label ("Change B20 to use TEXT(B17, \"0.00%\")").
125
+ - **The user can always answer in their own words.** A question with `options`
126
+ also offers "Other" — a multi-line text box; that answer comes back as text
127
+ (`in their own words: "…"`) instead of an option id. Read it — it is usually
128
+ the case your options missed.
129
+
130
+ - `range` — the single range the question is **about**. The question appears at
131
+ those cells, which is what makes it a question about *them* rather than a
132
+ floating dialog. Pass it whenever the question has a subject.
133
+ - Omit `range` only when the question is not about a place ("which quarter should
134
+ I model?"). It is then centred. It never falls back to the user's selection —
135
+ that is theirs, and it is almost never what you are asking about.
136
+
137
+ Asking about cells does **not** need a `highlight` first: the prompt is already
138
+ at them. Reach for both only when the surrounding context matters too — mark the
139
+ whole block with `highlight`, then `prompt` at the one cell in question.
140
+
141
+ ## Common patterns
142
+
143
+ ### Orient the user before making changes
144
+
145
+ ```text
146
+ highlight {ranges: [{range: "Sheet1!B2:D8", label: "Updating these prices"}], intent: "working"}
147
+ → run (the edit, through the attended session)
148
+ → highlight {ranges: [{range: "Sheet1!B2:D8", label: "Updated — 3 cells changed"}], intent: "finding"}
149
+ ```
150
+
151
+ ### Flag errors found during analysis
152
+
153
+ One `highlight` with `question` intent, ranked worst-first, each entry labelled
154
+ with its reason. The grid shows *where* and *why* together; your prose adds what
155
+ you propose to do about it.
156
+
157
+ ### Ask before a destructive change
158
+
159
+ ```text
160
+ prompt {
161
+ range: "Budget!D69",
162
+ message: "D69 is hardcoded where the column computes. Replace it with the formula?",
163
+ options: [{id: "replace", label: "Replace"}, {id: "keep", label: "Keep as-is"}]
164
+ }
165
+ ```
166
+
167
+ The question renders at D69, so there is nothing to cross-reference.
168
+
169
+ ### Several decisions that belong together
170
+
171
+ ```text
172
+ prompt {
173
+ questions: [
174
+ {id: "d69", header: "Hardcode", range: "Budget!D69",
175
+ message: "D69 is hardcoded. Replace it with the formula?",
176
+ options: [{id: "replace", label: "Replace", description: "Use =-(D44+D54) like the rest of the row."},
177
+ {id: "keep", label: "Keep"}]},
178
+ {id: "f12", header: "Sign", range: "Budget!F12",
179
+ message: "F12's sign is flipped vs. the column. Fix it?",
180
+ options: [{id: "fix", label: "Fix"}, {id: "keep", label: "Keep"}]}
181
+ ]
182
+ }
183
+ → User answered:
184
+ - d69: replace
185
+ - f12: keep
186
+ ```
187
+
188
+ One dialog, two tabs, each marking its cells — not two prompts in a row.
189
+
190
+ ### Walk a user through a model
191
+
192
+ Highlight each range in turn as you explain it in chat — inputs, then the
193
+ formulas that consume them, then the output — one `working` highlight per step,
194
+ each replacing the last.