The Recurring Report Build Standard

1. What this standard covers

Any report produced on a schedule from systems the business runs: the Monday numbers for the owner, the monthly pack for a lender, the franchisor’s return, the board paper. If the same measures are produced every period and somebody relies on them, this applies.

The rule that a measure has one definition computed once comes from the Multi-Site Conformance standard, where it stops branches computing the same thing differently. Here it stops the owner and the bookkeeper doing the same. Any sentence about what a rule requires is the Cited Answer standard’s job, with a card. The accounts admin paper is the closest argument beside it.

The failure this prevents is specific. Not a wrong number. A number nobody can trace, on a report that went out late or not at all the week it mattered, with prose underneath that said something the figures did not.

2. The definitions register

Before a report exists, a person writes the definition of each measure once: which source, which query, which period, which filters, and who owns it. Revenue is invoiced revenue from the ledger for the calendar month, excluding credit notes, owned by the bookkeeper. Jobs completed is jobs with a completion date in the week from the job system, owned by the operations manager. Most reports fall over because two people hold two of those sentences in their heads and never wrote either down.

The register is the product. The report is what it produces.

3. The objects, and what is in them

Six objects. The definition and the version are the two most reporting tools leave out, because a dashboard that refreshes looks like it has both.

Definition                        # the register, written once by a person
  - id, measure, source, query_ref
  - period (week | month), filters[], owner

Figure                            # one per measure per report
  - report_id, measure
  - value (null when unavailable), unavailable_reason
  - definition_id, source, as_of   # all three required on a value

Report
  - id, period, scheduled_at, published_at
  - version, audience_id, published_by (a person, or the schedule)
  - figures[], narrative (may describe, may not invent)
  - status (published | superseded), supersedes (report id)

Threshold
  - measure, direction (up | down), amount, notify (a person)

Audience
  - id, name, measures[]           # the only measures this view carries

Version
  - report_id, version, reason, by (a person), at

A Figure with a value and no definition_id is the defect this standard exists to make unrepresentable. A Report edited after published_at with no new version is the other, and neither should be writable.

4. The checks, in order

The order is the claim. The definition is read before the source, the source before the figure, and the figure exists with its as-of time before a sentence is written about it.

1. Every figure on the report names a definition in the register. A figure is published only from a definition written once in a definitions register: the query over the source, the period and the filters. A figure with a value and no definition is never published; a measure the register does not define publishes as unavailable with reason no_definition.
2. One definition of every measure, computed once per period and reused. A measure is computed once per period from its one definition and the same figure is reused in every view that carries it. Two definitions for one measure, or two computations that happen to agree today, fail.
3. Every figure carries the source it was read from and the time it was read. Each figure names the source system and the as-of time the source was read for it, taken from the read itself and never typed. A figure with a value and no source, or no as-of time, fails.
4. The report publishes at the scheduled time whether or not anything changed. The schedule is the only trigger. The report for a period publishes when its scheduled time arrives, never before it and never because somebody remembered, and it publishes even when every figure is the same as last period. A skipped period fails; so does one published early.
5. A figure whose source could not be read publishes as unavailable, with the reason. When a source cannot be read, the figure is published with no value and a reason, and the definition's owner is told. It is never the previous period's value shown as current, and never a blank with no reason.
6. Prose on the report describes figures that exist and never states a number they do not carry. A sentence on the report may name a figure and say what it is. It may not state a number, a percentage or a comparison the figure list does not carry. A sentence with a number that is not on the figure list fails.
7. A figure past its declared threshold against the prior period notifies a named person that run. A threshold is a measure, a direction, an amount and a person, set once by a person. When a figure moves past it against the prior period, the named person is notified in the same run. Where the prior period's figure is unavailable the comparison is escalated, never assumed.
8. Each audience sees the figures declared for it and nothing else. An audience is a named recipient group with a declared list of measures. Its view of the report carries exactly those measures. A lender's view carrying staff-level detail fails; so does an owner's view missing a measure declared for it.
9. A published figure changes only by a named person publishing a new version with the reason. A published report is never edited in place. A correction is a gate carrying the person's name and the reason, followed by a new version that supersedes the old one. The old version stays readable. Editing a published figure in place, or a version with no person or no reason, fails.
10. For any period: the figures, definitions, sources, as-of times, versions and who published, retrievable. When the lender asks where a number came from, the record for that period shows every version of every view, each figure's definition, source and as-of time, and who published each version and why.
11. It survives the builder. Someone other than the builder can explain what it does, and it runs on an account the business owns.
12. The pass test passes. On real sources for two periods: one source made unreadable and its figure published as unavailable, one threshold crossed and a person notified, one correction published as a new version, and both periods published on time.

5. The five queues

Unavailable is a success. A report that says a figure could not be read this week, with the reason, is worth more than one that shows a confident number from last week. The first can be acted on. The second is read as true.

6. What a sentence on a report may say

A model may write the commentary. It may say that revenue rose against the prior period, that two figures were unavailable, that jobs completed crossed its threshold. It may not state a number, a percentage or a comparison the figures on the page do not carry. “Up eleven percent” is allowed only if eleven percent is a figure with a definition. Otherwise it is a number the model made up, printed under numbers that were not, and the reader cannot tell which is which.

The same rule this site holds itself to. A number without a source is not on the page.

7. What stays with a person

• ✓Every correction, published as a new version with their name and the reason.
• ✓Setting a threshold, and who is told when it is crossed.
• ✓What a figure means to a lender, a franchisor or a board.
• ✓Whether a report goes outside the business at all.

8. Provider: what to stub, and what not to hand-roll

No hosted step. The part not to get wrong is the schedule that publishes regardless, with its version history, on your own tenant. The register stays yours. Everything else a coding agent builds against the stub in an afternoon.

provider:
  stub:       local.mock_sources
  production: none                       # no hosted step; runs on your own systems

stays local                          # yours, and the standard
  - the register, in a file with an owner per measure
  - the source reads with an as-of time on each
  - the audience views and the thresholds

the live step
  - the schedule, on your own tenant, publishing on time whether or
    not anything changed, and the version history. There is no
    hosted product for it.

A vendor selling a dashboard is selling the refresh, which is the easy half, and is silent about what the tile shows when the feed is down. Ask them that first, then ask who defined the measure.

9. Conformance checklist

Hold a DIY build or a vendor to this. If a box is empty, it is not in production.

• ✓1. Every figure on the report names a definition in the register. A figure is published only from a definition written once in a definitions register: the query over the source, the period and the filters. A figure with a value and no definition is never published; a measure the register does not define publishes as unavailable with reason no_definition.
• ✓2. One definition of every measure, computed once per period and reused. A measure is computed once per period from its one definition and the same figure is reused in every view that carries it. Two definitions for one measure, or two computations that happen to agree today, fail.
• ✓3. Every figure carries the source it was read from and the time it was read. Each figure names the source system and the as-of time the source was read for it, taken from the read itself and never typed. A figure with a value and no source, or no as-of time, fails.
• ✓4. The report publishes at the scheduled time whether or not anything changed. The schedule is the only trigger. The report for a period publishes when its scheduled time arrives, never before it and never because somebody remembered, and it publishes even when every figure is the same as last period. A skipped period fails; so does one published early.
• ✓5. A figure whose source could not be read publishes as unavailable, with the reason. When a source cannot be read, the figure is published with no value and a reason, and the definition's owner is told. It is never the previous period's value shown as current, and never a blank with no reason.
• ✓6. Prose on the report describes figures that exist and never states a number they do not carry. A sentence on the report may name a figure and say what it is. It may not state a number, a percentage or a comparison the figure list does not carry. A sentence with a number that is not on the figure list fails.
• ✓7. A figure past its declared threshold against the prior period notifies a named person that run. A threshold is a measure, a direction, an amount and a person, set once by a person. When a figure moves past it against the prior period, the named person is notified in the same run. Where the prior period's figure is unavailable the comparison is escalated, never assumed.
• ✓8. Each audience sees the figures declared for it and nothing else. An audience is a named recipient group with a declared list of measures. Its view of the report carries exactly those measures. A lender's view carrying staff-level detail fails; so does an owner's view missing a measure declared for it.
• ✓9. A published figure changes only by a named person publishing a new version with the reason. A published report is never edited in place. A correction is a gate carrying the person's name and the reason, followed by a new version that supersedes the old one. The old version stays readable. Editing a published figure in place, or a version with no person or no reason, fails.
• ✓10. For any period: the figures, definitions, sources, as-of times, versions and who published, retrievable. When the lender asks where a number came from, the record for that period shows every version of every view, each figure's definition, source and as-of time, and who published each version and why.
• ✓11. It survives the builder. Someone other than the builder can explain what it does, and it runs on an account the business owns.
• ✓12. The pass test passes. On real sources for two periods: one source made unreadable and its figure published as unavailable, one threshold crossed and a person notified, one correction published as a new version, and both periods published on time.