Skip to main content

/generate-report

Generate QA reports for Clear Rates (consistency, accuracy, or PR-based QA). Runs Trino queries, produces markdown, and copies output to tq-api-docs.

Usage​

/generate-report <product> <report-type> <version> [old_version or run params]

Examples:

/generate-report clear-rates consistency v2_4_3 v2_4_2
/generate-report clear-rates accuracy v2_4_3
/generate-report clear-rates pr-qa cld-v2.4.3 {"schema_name": "tq_dev.internal_dev_csong_cld_", "version": "v2_4_3", "sub_version": "2026_01", "filter_payer_ids": ["388"], "provider_types": ["Hospital", "ASC"]}

What It Does​

Consistency Report​

Compares two CLD versions to detect regressions. Runs 23 SQL queries covering:

  • Summary statistics — ROID, payer, network, provider, code counts by provider_type and bill_type
  • Dropoffs — entities present in old version but missing in new (providers, payers, networks, provider-network combos, bill type-code combos)
  • Rate swings >10% — average canonical rate and % of Medicare changes at bill+provider, network+provider, and network levels
  • ROID count swings >10% — by service line, provider type, state, payer network, health system, rate score, rate class, rate source, contract methodology, crosswalk method, gross charge type

Output: tq-api-docs/cld/docs/qa/consistency_reports/{old_version}_to_{new_version}.md

Accuracy Report​

Analyzes canonical rate quality for a single version against Medicare benchmarks:

  • Outlier score counts
  • Rates vs CBSA and facility-specific Medicare rates (below 80%, above 15x)
  • Canonical rate score distribution (overall and by provider type)
  • Extreme rate ratios by code (top 20 codes < 0.2x or > 10x Medicare)

Output: tq-api-docs/cld/docs/qa/accuracy_reports/{version}.md

PR QA Report​

Interactive, PR-driven QA workflow:

  1. Lists all PRs merged into the version branch
  2. Reviews each PR diff and classifies the change
  3. Designs 2-5 targeted QA checks per PR
  4. Executes Trino queries and writes results
  5. Assesses each PR as PASS, NEEDS ATTENTION, or FAIL

Output: qa/clear_rates/<version>/YYYY_MM_DD_cld_<version>_payer_<payer_ids>_qa.md

Inputs​

  • product — clear-rates (more products planned)
  • report-type — consistency, accuracy, or pr-qa
  • version — CLD version (e.g. v2_4_3; dots normalized to underscores)
  • old_version — previous version (required for consistency)
  • run params — JSON with schema_name, version, sub_version, filter_payer_ids, provider_types (for pr-qa)

Outputs​

  • Markdown report written to tq-api-docs (for consistency/accuracy) or local qa/ directory (for pr-qa)
  • For consistency/accuracy: creates a PR in tq-api-docs

Adding New Products​

Currently only clear-rates is supported. To add a new product (e.g. SSP, Consumer), add a reference file at .claude/skills/generate-report/references/<product>.md describing the report types, source tables, SQL queries, and output paths. The skill routes on the <product> argument and reads the matching reference file for context.

On this page: