dsh-office-kit 0.4.1 → 0.4.3

package/assets/skills/excel-live-control/domain_guidance/healthcare.md

@@ -1,58 +1,52 @@
 # Healthcare
 
-Two kinds of workbook live in a health organisation, and they carry different rules:
+Health organisations run two workbook kinds:
 
-- **Clinical and patient records**: appointments, encounters, observations, results.
-  The source of truth is a clinical system; a workbook holds an extract.
-- **Administrative and financial work**: budgets, staffing, throughput, cost per case.
-  Money follows `financial_models.md` even when the organisation is a hospital.
+- **Clinical and patient records** — appointments, encounters, observations, results. The
+  clinical system is the source of truth; a workbook holds an extract.
+- **Administrative and financial work** — budgets, staffing, throughput, cost per case. Money
+  follows `financial_models.md`, hospitals included.
 
-Most healthcare spreadsheet tasks are the second kind built on top of the first. Keep the
-extract and the analysis visibly separate.
+Most tasks are the second kind built on the first. Keep extract and analysis visibly apart.
 
 ## Handling the raw extract
 
-- Put raw data on its own sheet or block, untouched, one table. Everything you compute
-  lives *beside* it or in a separate prepared block — never by overwriting a measurement.
-- Descriptive names help the next reader: `Appointments_RawData` beats `Sheet2`;
-  `Clinic KPI Dashboard` beats `Sheet5`.
-- Keep the source's definitions with the data: the period it covers, the extract date, the
-  source system, the denominator used. Length of stay, readmission rate and utilisation
-  are meaningless without them, and definitions differ between systems.
-- Preserve identifiers exactly as supplied (MRN formats vary), and keep dates as dates with
-  one format down the column.
-- Units belong in the header (`Weight (kg)`, `Temperature (°C)`, `HbA1c (%)`, `Heart rate
-  (bpm)`), not in the cells as text. A column of `"72 bpm"` strings cannot be averaged.
+- Keep raw data untouched on its own sheet or block, as one table; compute beside it or in a
+  separate prepared block. Never overwrite a measurement.
+- Name descriptively: `Appointments_RawData` beats `Sheet2`; `Clinic KPI Dashboard` beats
+  `Sheet5`.
+- Keep the source's definitions with the data: period covered, extract date, source system,
+  denominator. Length of stay, readmission rate and utilisation are meaningless without them,
+  and systems define them differently.
+- Preserve identifiers exactly (MRN formats vary); dates as dates, one format down the column.
+- Units in the header (`Weight (kg)`, `Temperature (°C)`, `HbA1c (%)`, `Heart rate (bpm)`),
+  never cell text — `"72 bpm"` strings cannot be averaged.
 
 ## Building on it
 
-- Highlight the fields staff must complete (amber fill) and keep unused placeholders out.
-- If a threshold drives a flag, use one named cell for it (`BMI_threshold`) and reference
-  it, so the cut-off is visible and changeable. A number buried in a formula is an
-  invisible policy.
-- Flags come only from a stated source or protocol threshold, and keep the severity the
-  source gives (normal / elevated / high), with a legend on the sheet. Do not invent
-  clinical ranges, do not round a borderline value into a category.
-- A codebook (code → meaning, units, abbreviations) next to the data when the extract uses
-  codes, or a legend when it uses abbreviations.
-- Keep a `Corrected value` column or an audit log for corrections. Never edit the original
-  measurement in place; the original and the correction are both evidence.
+- Highlight fields staff must complete (amber fill); no unused placeholders.
+- For a threshold-driven flag, name one cell (`BMI_threshold`) and reference it, so the
+  cut-off is visible and changeable.
+- Flags only from a stated source or protocol threshold, with its severity (normal / elevated
+  / high) and a sheet legend. Never invent clinical ranges; never round a borderline value
+  into a category.
+- Codebook (code → meaning, units, abbreviations) beside coded data; legend for
+  abbreviations.
+- `Corrected value` column or audit log; never edit the original measurement in place —
+  original and correction are both evidence.
 
 ## Consequences of getting it wrong
 
-Clinical arithmetic and clinical judgement are different things. Compute what the source
-supports; verify a critical calculation (dosing, risk score, threshold classification)
-against the authoritative definition when one is available, and if it is not available say
-so instead of asserting the number is right. Do not give clinical advice, and do not
-present a screening flag as a diagnosis.
+Clinical arithmetic is not clinical judgement. Compute what the source supports; check a
+critical calculation (dosing, risk score, threshold classification) against the authoritative
+definition, and say when none exists rather than asserting the number. No clinical advice; a
+screening flag is not a diagnosis.
 
 ## Doing it live
 
-- The user may have the extract open with their own formatting. Read before writing:
-  `info` for the sheets and used ranges, `read_range --formulas --display` for the block
-  you are extending.
-- Add derived columns to the right of the raw block with a clear header, or to a separate
-  prepared area; never insert a column into the middle of an extract that other formulas
-  or a pivot already reference.
-- After writing, verify with `read_range --formulas` and check the `errors` array — a
-  healthcare sheet with a `#DIV/0!` in a rate column is a report that will be misread.
+- The extract may be open with the user's formatting. Read first: `info` for sheets and used
+  ranges; `read_range --formulas --display` for the block you will extend.
+- Add derived columns right of the raw block with a clear header, or in a separate prepared
+  area; never insert a column into an extract that formulas or a pivot reference.
+- After writing, verify with `read_range --formulas` and check `errors` — a `#DIV/0!` in a
+  rate column becomes a misread report.

package/assets/skills/excel-live-control/domain_guidance/marketing_advertising.md

@@ -1,53 +1,52 @@
 # Marketing and advertising
 
-Campaign, funnel, lead, CRM and ad-performance data. The failures here are almost always
-grain, denominator or freshness — not arithmetic.
+Campaign, funnel, lead, CRM and ad-performance data. Failures here are grain, denominator or
+freshness — rarely arithmetic.
 
 ## Know what the export is
 
-- **Extract freshness vs analysis time.** An export pulled Tuesday and analysed Friday is
-  Tuesday's data. Record the extract date and the as-of date once, in the input area, and
-  do not compare a Friday figure with a Tuesday one as if the difference were performance.
-- **Channel setup.** A campaign may be split across an ad platform, a CRM and a billing
-  system. Name which one each figure comes from before combining them.
-- **Grain.** Daily rows are not campaign rows. Impressions are not sessions; clicks are not
+- **Freshness**: an export pulled Tuesday and analysed Friday is Tuesday's data. Record the
+  extract date and as-of date in the input area; do not read a Friday-vs-Tuesday difference as
+  performance.
+- **Channel setup**: a campaign may span an ad platform, a CRM and a billing system. Name the
+  source of each figure before combining them.
+- **Grain**: daily rows are not campaign rows. Impressions are not sessions; clicks are not
   leads; leads are not qualified leads; a pipeline total is not revenue.
-- **Denominators.** CTR uses impressions, CVR uses sessions or clicks depending on the
-  platform's definition, CPA uses conversions attributed that period. Carry the platform's
-  definition into the label; two vendors' "conversion rate" differ.
+- **Denominators**: CTR uses impressions; CVR uses sessions or clicks per the platform's
+  definition; CPA uses conversions attributed that period. Put the platform's definition in
+  the label — vendors' "conversion rate" differ.
 
 ## Layout
 
 - Name tabs by content and period: `Leads_Q1_2025`, `Pipeline Analysis`, `ROI Dashboard`.
-- Keep the raw import intact on its own sheet; clean in derived columns or a prepared
-  area, and record what you excluded or mapped (non-target region, test account,
-  renamed source) so the exclusion is visible.
+- Keep the raw import intact on its own sheet; clean in derived columns or a prepared area,
+  and record exclusions and mappings (non-target region, test account, renamed source).
 - One typed time-series date column with one format. Add an ISO helper column only when a
-  downstream import needs it, and label it as such.
+  downstream import needs it, labelled as such.
 - Targets and traffic lights only when the source supplies a target and a direction. No
-  invented targets, no green/amber/red on numbers nobody set a goal for.
-- Every dashboard figure traces back to a cell in the prepared data. If a number cannot be
-  traced, it does not go on the dashboard.
+  invented targets, no green/amber/red on goals nobody set.
+- Every dashboard figure traces back to a cell in the prepared data; otherwise it does not go
+  on the dashboard.
 
 ## Metrics
 
-- Define abbreviations where they are used (CPC, CPM, CPA, ROAS, MQL) — a legend on the
-  analysis sheet, not a glossary tab nobody opens.
-- Keep the comparison basis visible: week over week, month over month, or the same period
-  last year. Mixing bases across one chart is the most common misleading dashboard.
-- Attribution: say which model (last click, first click, linear, platform-reported) and
-  keep it consistent within a table. Platform-reported and analytics-reported conversions
-  never reconcile exactly; report both rather than forcing a match.
-- Charts only when they make a trend, a comparison or a funnel clearer than a table. A
-  chart of six categories is a table with extra steps.
+- Define abbreviations where used (CPC, CPM, CPA, ROAS, MQL) — a legend on the analysis sheet,
+  not a glossary tab nobody opens.
+- Keep the comparison basis visible: week over week, month over month, or same period last
+  year. Mixing bases in one chart is the most common misleading dashboard.
+- Attribution: state the model (last click, first click, linear, platform-reported) and keep
+  it consistent within a table. Platform- and analytics-reported conversions never reconcile
+  exactly; report both.
+- Charts only when they make a trend, comparison or funnel clearer than a table. Six
+  categories is a table with extra steps.
 
 ## Doing it live
 
-- Read first: `info` (which sheets, which used ranges, whether the user is mid-edit) then
+- Read first: `info` (sheets, used ranges, whether the user is mid-edit), then
   `read_range --formulas` across the block you will extend.
-- Append new periods as rows below the existing table and extend the table/conditional
-  formatting/chart source with it. Do not create a second table beside the first.
-- When a figure must be flagged for refresh (stale extract, missing platform), use the
-  amber input fill and a note in the cell beside it, not a colour nobody explained.
-- Verify with `read_range --formulas`: this is where a misaligned denominator shows up as a
-  rate that is off by a factor of ten.
+- Append new periods as rows below the table and extend the table, conditional formatting and
+  chart source with them. No second table beside the first.
+- For a refresh flag (stale extract, missing platform), use amber input fill plus a note in
+  the cell beside it, not an unexplained colour.
+- Verify with `read_range --formulas`; a misaligned denominator surfaces as a rate off by a
+  factor of ten.

package/assets/skills/excel-live-control/domain_guidance/scientific_research.md

@@ -1,53 +1,51 @@
 # Scientific research data
 
-The spreadsheet is often the only record of an experiment. Treat the observations as
-irreplaceable: a cleaned value that overwrote a raw measurement is data loss, and a live
-edit is one keystroke away from it.
+The spreadsheet is often the only record of an experiment. Treat observations as
+irreplaceable: a cleaned value that overwrote a raw measurement is data loss, and a live edit
+is one keystroke away.
 
 ## Keep the raw table raw
 
-- One flat table: one row per observation, one variable per column, one unit per column.
-  No merged cells, no multi-row headers, no calculation rows mixed into the data block.
-- Do not overwrite a measurement. Transformations live in separate columns (clearly headed
-  `log10(x)`, `normalised`) or in a separate processed block/sheet.
-- Record the cleaning: which rows were excluded and why, which values were imputed, which
-  units were converted. A protocol note on the sheet or a short note beside the block.
-- Missing observations stay visibly missing (blank or `n.a.` as the table's convention
-  dictates) — never silently zero-filled. Randomised and simulated values are labelled as
-  such; they are not observations.
+- One flat table: one row per observation, one variable per column, one unit per column. No
+  merged cells, no multi-row headers, no calculation rows inside the data block.
+- Never overwrite a measurement. Transformations go in separate columns (headed `log10(x)`,
+  `normalised`) or a separate processed block or sheet.
+- Record the cleaning: rows excluded and why, values imputed, units converted — in a protocol
+  note on or beside the sheet.
+- Missing observations stay visibly missing (blank or `n.a.`, per the table's convention);
+  never zero-fill silently. Label randomised and simulated values as such — they are not
+  observations.
 
 ## Presentation tables are a different object
 
-When the sheet is a report of the data rather than the data itself:
+When the sheet reports the data rather than holding it:
 
-- One type of data per column, units in the header (`Concentration (mg/L)`), never inside
-  the cell.
+- One type of data per column; units in the header (`Concentration (mg/L)`), never in the cell.
 - Never encode meaning only in colour or bold — add a labelled value column (`Flag:
-  excluded`, `Status: control`). A reader with a monochrome printout must still get the
-  full information.
-- Notes belong in a notes column, not in cell comments that a co-author will never see.
-- No merged cells in a table you expect anyone to sort or filter.
+  excluded`, `Status: control`). A monochrome printout must still carry the meaning.
+- Notes belong in a notes column, not in cell comments a co-author will never see.
+- No merged cells in a table anyone will sort or filter.
 
 ## Analysis
 
-- Prefer a transparent formula to a clever one. Someone has to defend this number in a
-  review six months from now.
-- Show the calculation steps: the intermediate columns are the evidence. Hiding them in a
-  single formula makes the result unfalsifiable.
-- A circular reference or iterative calculation is off-limits unless the user asks for it
-  and documents it. A simulation's random seed and method are part of the result.
-- Distinguish measurement, derived value, flag and assumption — by label, not by font
-  colour alone.
-- If the design of the analysis changes (an exclusion added, a normalisation changed), say
-  so in the reply. A quiet change to a denominator rewrites the conclusion.
+- A transparent formula beats a clever one; someone must defend the number in review six
+  months from now.
+- Show the steps: intermediate columns are the evidence; one formula makes the result
+  unfalsifiable.
+- Circular references and iterative calculation are off-limits unless the user asks and
+  documents it. A simulation's random seed and method are part of the result.
+- Distinguish measurement, derived value, flag and assumption by label, not by font colour
+  alone.
+- If the design changes (exclusion added, normalisation changed), say so in the reply. A
+  quiet denominator change rewrites the conclusion.
 
 ## Doing it live
 
 - Before touching anything: `info`, then `read_range --formulas --display` on the block.
-  Raw data and report blocks are usually on different sheets; confirm which is which.
-- Append observations as rows at the bottom of the table, extend any table object to cover
-  them, and keep the header row exactly as it is.
-- Verify with `read_range --formulas`; the `errors` array catches the `#DIV/0!` and
-  `#VALUE!` that appear when a text value lands in a numeric column.
-- Never delete rows from the middle of a data table; a delete shifts every downstream
-  formula and every chart range with it.
+  Raw data and report blocks usually sit on different sheets; confirm which is which.
+- Append observations as bottom rows, extend any table object to cover them, leave the header
+  row untouched.
+- Verify with `read_range --formulas`; the `errors` array catches the `#DIV/0!` and `#VALUE!`
+  that appear when text lands in a numeric column.
+- Never delete rows from the middle of a data table; a delete shifts every downstream formula
+  and chart range.