# CTE plan generation technique (Agent View Generation)

Adapted from the AV-SQL CTE step. CTEs incrementally capture the information needed
to answer the rewritten question, WITHOUT answering the final question (that is the
next phase).

Rules (from the AV-SQL discipline, hold verbatim):

1. Copy table and column names EXACTLY from the schema context provided
   (`tht schema render --format mschema-text --table ...`). Never invent objects
   that are not present.
2. Always keep the keys (PK and join columns) in the CTEs: they will be needed later.
3. Better one column too many than one too few: if unsure, include it.
4. One CTE = one informative subset with a clear purpose (e.g. "ricoveri with
   ablazione in 2025"), named in a speaking snake_case.
5. CTEs can chain-reference each other **within the same file**; the last one in the
   file is the one that `tht cte test` will query (see the execution contract below).
6. Each file in `sessions/<id>/ctes/<name>.sql` contains ONLY the `WITH ... AS (...)`
   block (multi-CTE allowed), WITHOUT a trailing SELECT. A `SELECT ...` line after
   the WITH block causes an error in `tht cte test`: never add it. CTEs are tested
   **and approved (decision `cte_approved`) in plan order**: the next CTE is testable
   ONLY after the previous one is approved with `kind:"cte_result"`. The CLI refuses
   out-of-order CTEs (exit 5).
7. Filters: use field values verified with `tht search` (LSH match on real values),
   not imagined values.

## How `tht cte test` executes (complete contract — do not read the harness source)

- Each CTE file is **standalone**: the test reads ONLY `ctes/<name>.sql`, appends
  `SELECT * FROM <last CTE defined in that file>` and runs it read-only against the
  DWH with an injected LIMIT and statement timeout. Cross-file references are NOT
  resolved: to build on an earlier CTE, repeat its definition in the same `WITH`
  chain (that is why multi-CTE files are allowed). A test normally completes in
  well under a second.
- Before execution the SQL is validated statically: parsable, a single statement,
  read-only by structure, no blacklisted functions, and every referenced table must
  exist in the catalog (names defined in the `WITH` chain are exempt). Tables outside
  the promoted perimeter produce warnings. Unqualified columns are not statically
  checked — the DWH will catch them at run time.
- Test order is enforced by the CLI from the approved plan (exit 5 names the CTE
  whose turn it is). Every outcome (ok or error) is appended to `cte_tests.json`;
  the gate reads the persisted file + last test via `tht cte info`, so never paste
  SQL, columns or preview rows into the gate text.

Presentation to the reviewer, for each CTE in the plan:

> **<name>** — purpose: <one line>
> Tables used: <list> (all from the promoted perimeter)
> ```sql
> WITH <name> AS (...)
> ```

After confirmation (or for direct reviewer review) write the file and test:
`tht cte test --session <id> <name>`. On error or relevant warnings, discuss the
correction with the reviewer before rewriting the file. If the reviewer edits the
file by hand, RE-READ it before re-testing.