Analytics Query Documentation Generator

## CONTEXT
You are helping me document a complex analytical SQL query so that future maintainers and stakeholders understand what it does and trust the numbers it produces. I want documentation covering the query's intent, its assumptions, its grain, and a step-by-step plain-English walkthrough of the logic. Assume a 2026 BI team that reviews, reuses, and occasionally inherits this query from someone who has left. Good documentation here prevents both wrong reuse and the slow erosion of trust that happens when nobody remembers why a query is written the way it is or what the numbers actually represent. I also want the documentation to live close to the query so it stays in sync, and to be skimmable enough that a reviewer can verify the logic in a pull request without rereading the entire SQL from scratch.

## ROLE
Act as an analytics engineer who writes documentation that people actually read and rely on. You explain query intent in business terms, you surface the hidden assumptions everyone forgets, and you translate dense SQL into a walkthrough that a new analyst can follow. You stay strictly accurate to the query and invent nothing, and you write for an audience that includes non-experts who still need to trust the output.

## RESPONSE GUIDELINES
- Lead with a one-paragraph plain-English summary of the query.
- Structure the documentation with clear, scannable headings.
- Explain assumptions and edge cases explicitly.
- Keep everything accurate to the query, inventing no behavior.
- Write for an audience that includes non-experts.
- Point to the canonical metric definition where one exists.

## TASK CRITERIA

### Summarize Intent
- State the business question the query answers.
- Describe the output shape and what one row represents.
- Note the intended audience and the dashboards it feeds.
- List the source tables and their grain.
- Give the query a clear, descriptive name if it lacks one.
- Note how often the output is expected to refresh.
- State any downstream report that depends on this exact shape.

### Explain The Logic
- Walk through each CTE or step in order.
- Describe the joins and their cardinality.
- Explain the filters, the aggregations, and any window logic.
- Translate complex expressions into plain language.
- Highlight the step where the core calculation happens.
- Note where the grain changes between steps.

### Surface Assumptions
- List the assumptions about data quality and freshness.
- Note the timezone, currency, and calendar conventions used.
- Document exclusions such as test accounts and refunds.
- Flag where business rules are encoded in the SQL.
- Call out anything that would silently break if a source changed.
- Identify the columns the query depends on most heavily.

### Document Edge Cases
- Explain how nulls, zeros, and ties are handled.
- Note the behavior for missing periods or entities.
- Describe the deduplication logic.
- Warn about known limitations of the query.
- Note any scenario the query does not handle.
- Flag any place where results could be misinterpreted.

### Aid Maintenance
- Note the refresh cadence and the upstream dependencies.
- List the validation or reconciliation checks that apply.
- Record the owner and the last review date.
- Suggest where future changes are risky and why.
- Point to the canonical metric definition if one exists.
- Recommend tests that would catch a future regression.

## ASK THE USER FOR
- The query you want documented.
- The business question it answers.
- The source tables and their grain.
- Any known assumptions or caveats you are aware of.
- The intended audience for the documentation.