QUA-1024: Restructure Data Diff check docs

[RafaelOsiro]

Overview

Splits the Data Diff check documentation from a single page into a hub structure with Introduction, How It Works, Examples, API, and FAQ pages.

Key Changes

• Introduction: hub page with Definition, Field Scope, General/Anomaly Properties, and Next Steps cards
• How It Works: full semantics, Row Identifiers, Comparators, the three diff statuses, diff_change_types, and Comparison Source Records rendering
• Examples: three production scenarios (backup validation, system-to-system transfer, scoped post-migration mirror with diff_change_types)
• API: endpoints, PUT editable/immutable matrix, payload example, field notes
• FAQ: 13 questions across Behavior, Anomaly Reporting, and Configuration sections
• Link updates: is-replica-of-check.md, overview-of-a-check.md, rule-types-overview.md, profile.md repointed to the new path
• extra.css: added .anomalous-cell class mirroring the source-records highlight in the app
• mkdocs.yml: nav restructure + redirect mapping from old single-page URL

Pages to Test

• http://localhost:8000/data-quality-checks/data-diff/introduction/ — H1 "Data Diff Check", "Recommended Check" admonition mentions diff_change_types differentiator, 4 Next Steps cards
• http://localhost:8000/data-quality-checks/data-diff/how-it-works/ — H1 has info-outline icon in brick, 5-step evaluation flow, "Restricting Anomalies by Status" section with table and 3 use cases
• http://localhost:8000/data-quality-checks/data-diff/examples/ — three tabs (Backup Validation, System-to-System Transfer, Scoped Post-Migration Mirror); Scenario 3 uses diff_change_types: ["removed", "changed"]
• http://localhost:8000/data-quality-checks/data-diff/api/ — H1 has api icon in brick, "What PUT can change" admonition with Editable/Immutable lists, payload uses ["removed", "changed"]
• http://localhost:8000/data-quality-checks/data-diff/faq/ — H1 has help-circle icon, 13 Q&As, Q7 (diff_change_types) cross-links to how-it-works, Q13 (PUT editability) consistent with API page
• http://localhost:8000/data-quality-checks/is-replica-of-check/ — Deprecation notice link points to new /data-diff/introduction/ path
• http://localhost:8000/checks/data-diff-check/ — legacy redirect lands on /data-quality-checks/data-diff/introduction/
• http://localhost:8000/data-quality-checks/data-diff-check/ — legacy redirect lands on /data-quality-checks/data-diff/introduction/

[greptile-apps]

Greptile Summary

Splits the existing data-diff-check.md single-page doc into a five-page hub structure (Introduction, How It Works, Examples, API, FAQ) and updates all inbound links from is-replica-of-check.md, overview-of-a-check.md, rule-types-overview.md, and profile.md to point at the new paths, with two legacy-URL redirects added in mkdocs.yml.

• The new pages are well-structured and internally consistent; extra.css adds the .anomalous-cell helper class using existing CSS variables, and the nav/redirect plumbing looks correct.
• The how-to-create.md page is intentionally held out of the nav (pending screenshots) and the prior {:target="_blank"} inline-link thread is addressed in this commit.
• Two minor documentation gaps remain: the FAQ's definition of N in the anomaly message doesn't note that diff_change_types suppression affects the count, and the api.md Field Notes table omits the coverage field that how-to-create.md documents and the old page included in its payload example.

Confidence Score: 5/5

Documentation-only restructure; no runtime code is changed, redirects are in place, and all inbound links are updated correctly.

All changes are Markdown, CSS, and nav configuration. The hub structure is coherent, cross-links are consistent, and the two legacy redirect entries cover both known old URL patterns. The two open items are documentation clarifications, neither of which would misdirect a reader into a wrong API call.

No files require special attention; api.md and faq.md have the minor gaps noted in the comments above.

Important Files Changed

Filename	Overview
docs/data-quality-checks/data-diff/introduction.md	New hub page for Data Diff Check with definition, field scope, general/anomaly properties, and Next Steps cards; cross-links to sub-pages are correct.
docs/data-quality-checks/data-diff/how-it-works.md	New detailed reference page covering the five-step evaluation flow, three diff statuses, diff_change_types, Row Identifiers, Comparators, and Shape Anomaly format; accurate but N-count definition lacks a diff_change_types qualifier.
docs/data-quality-checks/data-diff/examples.md	New examples page with three production scenarios; tabbed layout, sample data tables, flowcharts, and SQL equivalents are well-structured.
docs/data-quality-checks/data-diff/api.md	New API reference page with endpoints table, PUT editable/immutable matrix, payload example, and field notes; missing the coverage field that was present in the old single-page doc.
docs/data-quality-checks/data-diff/faq.md	New FAQ page with 13 Q&As; Q10's definition of N in the anomaly message is inconsistent with the Scoped Post-Migration Mirror example in examples.md where suppressed statuses would inflate N.
docs/data-quality-checks/data-diff/how-to-create.md	New UI walkthrough page; intentionally excluded from nav pending screenshots, consistent with the TODO comment and mkdocs.yml.
mkdocs.yml	Nav restructured to hub layout; two redirects added covering both legacy URL patterns pointing to data-diff/introduction.md.
docs/stylesheets/extra.css	Added .anomalous-cell class using existing CSS variables (--q-orange, --q-brick) to mirror the app's source-records highlight.
docs/data-quality-checks/data-diff-check.md	Old single-page doc deleted; replaced by the new hub structure under data-diff/.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["POST /api/quality-checks\n(rule: dataDiff)"] --> B["Apply filter clause\nto target container"]
    B --> C["Read reference container\nin full"]
    C --> D{"Row Identifiers\nconfigured?"}
    D -->|Yes| E["Match rows by\nidentifier tuple"]
    D -->|No| F["Symmetrical set\ndifference"]
    E --> G["Compare fields on\neach matched pair\n(with Comparators)"]
    F --> G
    G --> H["Assign diff status:\nadded / removed / changed"]
    H --> I{"Status in\ndiff_change_types?"}
    I -->|Yes| J["Row contributes\nto anomaly count N"]
    I -->|No| K["Row computed\nbut suppressed"]
    J --> L["Emit single Shape Anomaly\nwith Comparison Source Records"]
    K --> L

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["POST /api/quality-checks\n(rule: dataDiff)"] --> B["Apply filter clause\nto target container"]
    B --> C["Read reference container\nin full"]
    C --> D{"Row Identifiers\nconfigured?"}
    D -->|Yes| E["Match rows by\nidentifier tuple"]
    D -->|No| F["Symmetrical set\ndifference"]
    E --> G["Compare fields on\neach matched pair\n(with Comparators)"]
    F --> G
    G --> H["Assign diff status:\nadded / removed / changed"]
    H --> I{"Status in\ndiff_change_types?"}
    I -->|Yes| J["Row contributes\nto anomaly count N"]
    I -->|No| K["Row computed\nbut suppressed"]
    J --> L["Emit single Shape Anomaly\nwith Comparison Source Records"]
    K --> L

Loading

_{Reviews (2): Last reviewed commit: "docs(data-diff): open how-it-works cross..." | Re-trigger Greptile}

[ets]

Approving — greptile-apps scored this 4/5.

---

Generated by Claude Code

[RafaelOsiro]

Addressed in edfb9173:

• introduction.md — added {:target="_blank"} to the in-text cross-link to how-it-works.md#restricting-anomalies-by-status, matching every other cross-page link on the page.
• how-to-create.md — keeping the TODO/excluded-from-nav state as-is for this PR (the page will be finished as part of the rule-type runbook later).

Both threads resolved.

@greptileai

[greptile-apps]

Want your agent to iterate on Greptile's feedback? Try greploops.