QUA-1024: Restructure Aggregation Comparison check docs

[RafaelOsiro]

Overview

Restructure the Aggregation Comparison rule type documentation from a single page into the 5-page hub pattern (Introduction, How It Works, Examples, API, FAQ), aligned with the QUA-1024 playbook used for Unique, AI Managed, Data Diff, Entity Resolution, Expected Values, and After Date Time.

Key Changes

• New hub at docs/data-quality-checks/aggregation-comparison/ with introduction.md, how-it-works.md, examples.md, api.md, and faq.md. H1 icons follow the Standard Icons convention (book-open-variant, file-cog, no icon for Examples, api, help-circle-outline).
• Introduction: formal definition, calculated field scope (no field picker), six rule-specific properties (target Aggregation, Comparison enum, reference Datastore/Container/Aggregation/Filter Clause), Shape-only anomaly types, and the Next Steps card grid.
• How It Works: evaluation flow for two-aggregate comparison, NULL and non-finite aggregate behavior, the two independent filter clauses (filter and ref_filter), an explicit "Coverage is not used" section, anomaly message format with both filter suffixes, Shape-only behavior (no Source Records highlighting), relationship with Volumetric / Data Diff / Metric, and performance considerations.
• Examples: three production scenarios (order totals vs line-item totals, cross-system row-count reconciliation, net sales must not exceed gross sales) with check configuration, payload, sample aggregates with anomalous-cell highlights, anomaly messages, mermaid flowchart, and equivalent SQL.
• API: endpoint matrix, permission breakdown (Active vs Draft for POST/PUT, Author for DELETE, Reporter for GET), payload example with properties.expression/comparison/ref_datastore_id/ref_container_id/ref_expression/ref_filter, field notes table, and PUT editable/immutable lists (3 immutables: rule, container_id, template_id). Explicit note that coverage and anomaly_message_field are ignored for this rule.
• FAQ: 15 questions across Behavior (operators, cross-datastore, same-container invariants, NULL aggregates, numeric requirement), Anomaly Reporting (message format, Shape-only, Custom Anomaly Description, null/NaN rendering), and Configuration (coverage, comparison editing, row-count match, Check Variables, Metric/Data Diff comparison).
• extra.css: adds the .anomalous-cell class to highlight individual table cells in Examples sample aggregates.
• mkdocs.yml: nested nav under "Aggregation Comparison" plus redirects from checks/aggregation-comparison-check.md and data-quality-checks/aggregation-comparison-check.md to the new introduction.
• Cross-references: overview-of-a-check.md and rule-types-overview.md repointed to the new hub path.
• Removed: legacy docs/data-quality-checks/aggregation-comparison-check.md.

Pages to Test

• http://localhost:8000/data-quality-checks/aggregation-comparison/introduction/ — H1 brick book-open-variant, Specific Properties table shows six properties with Comparison long-form labels, Next Steps cards (How It Works has file-cog, Examples has no icon, API has api, FAQ has help-circle-outline)
• http://localhost:8000/data-quality-checks/aggregation-comparison/how-it-works/ — Evaluation Flow with 4 steps, Coverage section states "does not use a coverage threshold", filter suffixes documented for both filter and ref_filter, Source Records Behavior states it does not apply
• http://localhost:8000/data-quality-checks/aggregation-comparison/examples/ — H1 with no icon, three tabs render, anomalous-cell highlights on sample aggregates, Scenario 2 Shape Anomaly ends with both [filter: load_date = current_date()] [reference filter: updated_at >= current_date()]
• http://localhost:8000/data-quality-checks/aggregation-comparison/api/ — Permission block lists POST/PUT for Active, POST/PUT for Draft, DELETE, GET; fields row marked "No"; explicit note that coverage and anomaly_message_field are ignored; Immutable list has rule, container_id, template_id
• http://localhost:8000/data-quality-checks/aggregation-comparison/faq/ — 15 questions grouped under Behavior / Anomaly Reporting / Configuration; emit Record Anomalies answered "No"; Custom Anomaly Description answered "No"; coverage lowering answered "No"; both Metric and Data Diff comparisons present
• http://localhost:8000/data-quality-checks/overview-of-a-check/ — Aggregation Comparison row links to the new hub introduction
• http://localhost:8000/data-quality-checks/rule-types-overview/ — same
• http://localhost:8000/checks/aggregation-comparison-check/ — legacy URL redirects to the new introduction
• http://localhost:8000/data-quality-checks/aggregation-comparison-check/ — legacy URL redirects to the new introduction

[greptile-apps]

Greptile Summary

This PR restructures the Aggregation Comparison check documentation from a single legacy page into a five-page hub (introduction, how-it-works, examples, api, faq), following the same QUA-1024 playbook already applied to Unique, AI Managed, Data Diff, Entity Resolution, Expected Values, and After Date Time.

• New hub pages cover formal definition, four-step evaluation flow, NULL/non-finite aggregate handling, two independent filter clauses (filter / ref_filter), Shape-only anomaly behavior, API payload with editable/immutable matrix, and 15 FAQ entries across Behavior / Anomaly Reporting / Configuration.
• extra.css adds .anomalous-cell using color-mix(in srgb, var(--q-orange) 12%, transparent) so both border and background track the --q-orange CSS variable together.
• mkdocs.yml nests the nav under a five-page hub and adds two redirects pointing to the new introduction; overview-of-a-check.md and rule-types-overview.md are re-pointed to the hub path.

Confidence Score: 5/5

Pure documentation restructuring with no executable code changes; all cross-references resolve to existing files and both redirects are correctly wired in mkdocs.yml.

Every changed file is documentation or stylesheet. The five new hub pages are internally consistent, all relative links point to verified files, the two legacy-URL redirects are correctly added, and the CSS addition uses the CSS variable throughout rather than hardcoding values. No logic, data, or runtime behavior is affected.

No files require special attention.

Important Files Changed

Filename	Overview
docs/data-quality-checks/aggregation-comparison/introduction.md	New hub landing page with formal definition, field scope, six specific properties, anomaly types, and Next Steps card grid — well-structured and consistent with the established hub pattern.
docs/data-quality-checks/aggregation-comparison/how-it-works.md	Four-step evaluation flow, NULL/non-finite aggregate handling, two independent filter clauses, anomaly message format with filter suffixes, Shape-only behavior, and relationship-with-other-rule-types table all documented accurately.
docs/data-quality-checks/aggregation-comparison/examples.md	Three production scenarios with check configuration tables, JSON payloads, sample aggregate tables with anomalous-cell highlights, Shape Anomaly messages, Mermaid flowcharts, and equivalent SQL — all internally consistent.
docs/data-quality-checks/aggregation-comparison/api.md	Endpoint matrix, permission breakdown (Active vs Draft), full payload example, field notes table, explicit note that coverage and anomaly_message_field are ignored, and editable/immutable PUT matrix are all present and accurate.
docs/data-quality-checks/aggregation-comparison/faq.md	15 questions across Behavior, Anomaly Reporting, and Configuration sections, with accurate answers; links to metric-check.md and data-diff-check.md resolve correctly.
docs/stylesheets/extra.css	Adds .anomalous-cell class using color-mix(in srgb, var(--q-orange) 12%, transparent) for the background — both border and background now track the CSS variable correctly.
mkdocs.yml	Nav entry expanded from a single file to a five-page nested hub; two redirects added/updated to point the legacy URLs to the new introduction — no orphaned entries or missing redirects.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["Legacy single-page doc\naggregation-comparison-check.md\n(deleted)"] -->|replaced by| B["Hub: aggregation-comparison/"]
    B --> C["introduction.md\nDefinition · Field Scope · Properties · Next Steps"]
    B --> D["how-it-works.md\nEvaluation Flow · NULL Handling · Filters · Anomaly Format"]
    B --> E["examples.md\n3 production scenarios with payloads + SQL"]
    B --> F["api.md\nEndpoints · Permissions · Field Notes · PUT matrix"]
    B --> G["faq.md\n15 questions: Behavior / Anomaly Reporting / Configuration"]
    H["mkdocs.yml"] -->|nav nested under hub| B
    H -->|redirect: checks/aggregation-comparison-check.md| C
    H -->|redirect: data-quality-checks/aggregation-comparison-check.md| C
    I["overview-of-a-check.md"] -->|link updated| C
    J["rule-types-overview.md"] -->|link updated| C
    K["extra.css"] -->|adds .anomalous-cell| E

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A["Legacy single-page doc\naggregation-comparison-check.md\n(deleted)"] -->|replaced by| B["Hub: aggregation-comparison/"]
    B --> C["introduction.md\nDefinition · Field Scope · Properties · Next Steps"]
    B --> D["how-it-works.md\nEvaluation Flow · NULL Handling · Filters · Anomaly Format"]
    B --> E["examples.md\n3 production scenarios with payloads + SQL"]
    B --> F["api.md\nEndpoints · Permissions · Field Notes · PUT matrix"]
    B --> G["faq.md\n15 questions: Behavior / Anomaly Reporting / Configuration"]
    H["mkdocs.yml"] -->|nav nested under hub| B
    H -->|redirect: checks/aggregation-comparison-check.md| C
    H -->|redirect: data-quality-checks/aggregation-comparison-check.md| C
    I["overview-of-a-check.md"] -->|link updated| C
    J["rule-types-overview.md"] -->|link updated| C
    K["extra.css"] -->|adds .anomalous-cell| E

Loading

_{Reviews (2): Last reviewed commit: "docs(aggregation-comparison): apply Grep..." | Re-trigger Greptile}

[RafaelOsiro]

@greptileai review