docs(analytics): retire the dataset inventory, keep the argument

[os-steve]

Closes #1422

Description

The maintainer ruled a fourth path on this card, rejecting all three options it offered (pin / stop enumerating / codegen). Verbatim: 「content/docs 为什么要有 cubes 清单表，文档应该是介绍业务概念」 — the thing being pinned should not exist.

So: the cubes/dataset inventory leaves content/docs, in all three locales; the pages around it become a business-concept introduction; the reports.mdx argument that leaned on the inventory is rewritten so it stands without it; and no guard is built.

Type of Change

• Documentation update

Related Issues

Ruling: decision batch #20 item 5, recorded on the card. Drift history that motivated it: #610, #965, #977, #1228 (all closed, all history rather than blockers). Boundary precedent kept on the other side of the line: #1329 / #1326.

Changes Made

1. The inventory is gone (ruling clause 1). The nine-row Dataset | Reads | Dimensions | Measures table is removed from content/docs/analytics/cubes.mdx and both translations. analytics/reports.mdx repeated the same roster in prose in three places; those go too.

2. The pages are rewritten as business-concept introductions (clause 2). cubes.mdx now says what the semantic layer is, which business questions it answers today, and where it stops — stated as questions and limits, not as declared names. A new section, Where the semantic layer lives, points readers at src/datasets/ as the single source of truth and says in one sentence why the table is not here, so the next person who wants to add it back has the reasoning rather than a blank space. The admin tip at the foot of the page was flipped to match: document the business question, not the inventory.

3. The argument was rewritten before the list was removed (clause 3). This is the part the card warned about. reports.mdx line 66 transcribed case_metrics's six dimensions and eight measures and then used that roster to argue five unshipped reports cannot be built. Each of those five arguments already rested on one specific fact; they now say so directly and no longer depend on the completeness of a list. Same treatment in the sales, lead and contract sections.

4. No guard, no test change (clause 4). With the inventory gone there is no drift left to pin. test/** is untouched — no file in it was edited, and none needed to be.

5. Scope held (clause 6). The view/report/dashboard rosters are not touched. A user can see those in the product; a machine semantic layer they cannot. That is the boundary AGENTS.md already codifies.

Enumeration verdicts, one by one

The failure mode on this card is deleting the wrong lists and turning an analysis into empty prose. The test used on each: does the enumeration promise completeness over a source-declared set (a transcription — it drifts the day the source grows), or does it name specific facts each doing argumentative work (a business argument — falsified only if that one fact changes)? A second check on top, taken from AGENTS.md rule 5: can a reader see this in the product UI?

Site	Verdict	Reason
cubes nine-row dataset table	removed	The transcription itself. Complete-set roster; invisible in the UI (this app ships no cube screen, as the page itself says).
cubes "Reachable today" vocabulary map (17 names)	removed	The same roster re-spelled as bullets — an exhaustive map of one dataset's declared names. Replaced by the business questions it answers, plus a pointer to src/datasets/opportunity.dataset.ts for the names.
cubes service section's six dimensions + eight measures + the eight-bullet measure list	removed	Complete-set transcription of case_metrics.
cubes "Not reachable, and why" (sales)	kept, compressed	Each bullet is a specific negative fact — no elapsed-days column, no measure over Expected Revenue, no line-item reach, no region on the deal. Argument, not roster.
cubes service limits (agent, account, product, CSAT, grain)	kept	Same: each names one absent thing and what follows from it. The no-first-response-measure paragraph in particular is load-bearing for reports.mdx.
cubes marketing "name by name" list	kept	These are campaign fields on a record a user opens, contrasted against the missing aggregation layer. That contrast is the section's whole insight, and the fields are UI-visible — the documentable side of the boundary.
cubes retired cube names (Sales, Pipeline, Service, Marketing)	kept	Phantom re-pointing: names readers arrive with that resolve to nothing. The opposite of an inventory.
cubes Copilot tool names	kept	A platform surface, not the cubes/dataset inventory. Ruling clause 6 forbids extending the ruling; left alone deliberately.
cubes date-dimension list (trend charts)	rewritten	Was an exhaustive list of declared date dimensions. The business point (no snapshot dimension exists, so time-series only runs along a date a dataset already carries) stands without it.
reports shipped-report tables (4 + 1 + 3 + 2)	kept	User-visible navigation facts — the report library is a screen. Same class as the view rosters clause 6 protects.
reports Pipeline by Stage / Stale Opportunities / Top Performing Reps	kept	Phantom re-pointing and one-fact arguments.
reports Forecast vs Actual (5 forecast measures)	trimmed	The list was decoration; the argument needs "quota lives here, one row per owner per period, so pin the period". Pin-the-period advice kept — it is actionable and it is what bites.
reports Win/Loss Analysis (6 measures)	trimmed	Buildability needs the two reason dimensions and the fact that the win/lose side is declared, not six names.
reports Lead Source ROI (4 dimensions)	trimmed	The argument is "one measure, never crosses to opportunities". Source is named because it does work; the other three did not.
reports case_metrics 6+8 roster (line 66)	removed	The transcription that this card is about.
reports five case-report bullets	kept, all five	Each already rested on its own fact — no owner dimension, no join to crm_account, no measure over customer_rating, nothing recording a reopen, Origin is a dimension. They now carry the argument alone.
reports SLA first-response paragraph	kept	Names two measures to draw a distinction a service manager acts on (violation rate vs compliance rate). Instruction, not inventory.
reports "nine objects" contract list	trimmed	The argument needs only "no dataset reads crm_contract".
reports product_metrics parenthetical	trimmed	Complete transcription of a 1-dimension, 2-measure dataset; the argument is "it never crosses to contracts or line items".
reports "Working with reports" controls table	kept	UI controls a user sees.
Tips sections naming Win Rate / Won Deals / Forecast Metrics	kept	Advice that names 2-3 specific things to be actionable. Naming a fact to do work is not enumerating a set for completeness.

One consequential edit outside the two named pages

content/docs/analytics/index.mdx (and both translations) promised that the cubes page "lists the gaps one by one" and describes "what each dataset can and cannot answer". After this change those promises are overstated, so two phrases were adjusted. Nothing else on that page moved; every string its pin test asserts is intact.

Testing

• pnpm verify green end-to-end (EXIT=0): validate, typecheck, lint, lint:i18n-gate (0 i18n/missing-* issues), hygiene (source hygiene clean), hygiene:tokens (source token ratchet clean), build (Artifact: dist/objectstack.json), test.
• Test Files 161 passed (161) / Tests 3402 passed | 1 skipped (3403) — the whole suite, on the committed tree.
• The three wording pins the ruling preserves are green unchanged: docs-analytics-vocabulary, docs-dashboard-tiles, docs-conversion-rate-spelling. So is heading-label and its helper. No assertion was touched, and none needed to be.
• Changeset added (.changeset/analytics-docs-drop-the-dataset-inventory.md, patch).
• New tests added — deliberately not: ruling clause 4 forbids a guard here, and the docs-drift tests are frozen under epic Epic: bring this repo's test farm back under the 2026-08-31 ruling — platform-first, os lint --strict first, then retire the local re-implementations by family #1579 step 6.

Two near-misses worth naming, both checked rather than assumed:

• docs-conversion-rate-spelling requires the conversion-rate metric to survive by name on analytics/cubes and analytics/reports in both Chinese scripts — a negative-only sweep would have passed on deletion, and that pin is what stops it. The phrase is preserved in all four files.
• heading-label and its helper only read the analytics/dashboards* pages, so the two heading changes here (The nine datasets to Where the semantic layer lives, and Service — case_metrics to Service) cannot reach it. Recorded because the dispatch flagged that test as at risk; measured, it is not. No inbound anchor links to either heading exist anywhere under content/.

Additional Notes

Locale parity: all three cubes faces are the same length and carry the same section structure; blockquote-callout counts are equal (0 in each), which is what docs-locale-callouts compares.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
hotcrm	Ignored		Sep 6, 2026 10:12am UTC