[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7AVKJAX05CM47KER5DCYHRS":3,"skill-same:01M7AVKJAX05CM47KER5DCYHRS":61},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":29,"updatedAt":30,"install":31,"resources":44},"01M7AVKJAX05CM47KER5DCYHRS","bigquery-augmented-analytics",null,"Execute in-database augmented analytics in Google BigQuery using Table-Valued Functions (TVFs) for automated metric anomaly detection, multi-dimensional root-cause attribution, and ARIMA_PLUS counterfactual causal inference. Do not use for generic SQL CRUD or external pandas exports.","SpectreDeath\u002FBrain-Harness","SpectreDeath","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F207463416?v=4","01M7AVGR1D4X8ADT47APKGVH2Z","JL","01M7AVGR2HSGD23BA5DBTJJTVN",0,"MIT","https:\u002F\u002Fgithub.com\u002FSpectreDeath\u002FBrain-Harness\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fbigquery-augmented-analytics\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: bigquery-augmented-analytics\ndescription: Execute in-database augmented analytics in Google BigQuery using Table-Valued Functions (TVFs) for automated metric anomaly detection, multi-dimensional root-cause attribution, and ARIMA_PLUS counterfactual causal inference. Do not use for generic SQL CRUD or external pandas exports.\n---\n\n# BigQuery Augmented Analytics: In-Database Anomaly, Attribution & Causal Engine\n\n`bigquery-augmented-analytics` is the autonomous data investigation engine that executes in-database AI, ML, and statistical inference directly inside Google BigQuery via Table-Valued Functions (TVFs). Based on the Google Cloud framework authored by Jenny Ortiz and Haoming Chen, this skill empowers agents to diagnose *why* business metrics change, detect structural step-level shifts, isolate high-dimensional segment drivers via Apriori rules, and quantify true causal lift against synthetic counterfactual baselines—all without exporting a single row of raw data.\n\nRather than succumbing to the **\"Data Egress Tax\"** (pulling millions of rows into local memory for pandas or R), this skill chains compact, expressive BigQuery TVFs where computation is pushed down directly into the distributed columnar storage engine.\n\n```\n[1. Temporal Profiling] ➔ [2. Shift Isolation] ➔ [3. Combinatorial Attribution] ➔ [4. Causal Lift] ➔ [5. Executive Synthesis]\n  ML.TREND \u002F SEASONALITY    ML.DETECT_CHANGE_POINTS    AI.KEY_DRIVERS \u002F CORRELATION     AI.CAUSAL_EFFECT     Root-Cause Brief\n```\n\nSee [CARD.md](CARD.md) for the companion summary card, TVF reference table, and verification checklist.\nConsult [data-management-architect](..\u002Fdata-management-architect\u002FSKILL.md) for data contracts and [deterministic-validation-loop](..\u002Fdeterministic-validation-loop\u002FSKILL.md) for structured observation validation.\n\n---\n\n## 1. Temporal Profiling & Noise Stripping\n\nBefore diagnosing metric changes, decompose raw time-series into underlying structural trajectories and predictable cyclical rhythms. This prevents treating regular seasonal variations as structural anomalies.\n\n1. **Trend Decomposition via `ML.TREND`**:\n   - Strips high-frequency noise and transient spikes from the underlying growth or decline trajectory.\n   - Example BigQuery SQL:\n     ```sql\n     WITH daily_metrics AS (\n       SELECT\n         DATE(timestamp) AS metric_date,\n         COUNT(*) AS total_events\n       FROM `bigquery-public-data.austin_bikeshare.bikeshare_trips`\n       GROUP BY metric_date\n     )\n     SELECT *\n     FROM ML.TREND(\n       TABLE daily_metrics,\n       data_col => 'total_events',\n       timestamp_col => 'metric_date'\n     )\n     ORDER BY metric_date;\n     ```\n2. **Cyclical Periodicity Discovery via `ML.SEASONALITY`**:\n   - Identifies recurring daily, weekly, monthly, and quarterly patterns across metric values.\n   - Example BigQuery SQL:\n     ```sql\n     SELECT *\n     FROM ML.SEASONALITY(\n       TABLE daily_metrics,\n       data_col => 'total_events',\n       timestamp_col => 'metric_date',\n       seasonalities => ['WEEKLY', 'MONTHLY']\n     )\n     ORDER BY metric_date;\n     ```\n\n> **Completion criterion**: Underlying trend direction separated from short-term noise; dominant recurring cycles documented; raw variance normalized against expected seasonality.\n\n---\n\n## 2. Structural Shift & Change-Point Isolation\n\nIsolate the exact historical dates or intervals where a metric experienced a statistically significant, persistent regime shift rather than a transitory fluctuation.\n\n1. **Step-Change Detection via `ML.DETECT_CHANGE_POINTS`**:\n   - Employs scalable Bayesian change-point algorithms capable of evaluating millions of distinct time series in seconds.\n   - Example BigQuery SQL:\n     ```sql\n     WITH baseline_series AS (\n       SELECT\n         DATE(start_time) AS trip_date,\n         COUNT(*) AS daily_trips\n       FROM `bigquery-public-data.austin_bikeshare.bikeshare_trips`\n       GROUP BY trip_date\n     )\n     SELECT\n       start_time,\n       end_time,\n       mean,\n       variance,\n       change_point_prob\n     FROM ML.DETECT_CHANGE_POINTS(\n       TABLE baseline_series,\n       data_col => 'daily_trips',\n       timestamp_col => 'trip_date'\n     )\n     WHERE change_point_prob >= 0.95\n     ORDER BY start_time DESC;\n     ```\n2. **Dynamic Boundary Parameterization**:\n   - Extract the primary shift timestamp ($t_0$) with the highest change probability or longest duration.\n   - Designate the pre-shift interval ($t \u003C t_0$) as the **Reference Group** and the post-shift interval ($t \\ge t_0$) as the **Interest Group** for downstream TVF chaining.\n\n> **Completion criterion**: Statistically significant change-point timestamp $t_0$ isolated with probability $\\ge 95\\%$; time horizons parameterized for attribution.\n\n---\n\n## 3. Combinatorial Attribution & Multi-Dimensional Slicing\n\nScan high-dimensional categorical features across millions of rows to explain the exact drivers of the metric variance between the reference and interest cohorts.\n\n1. **Multi-Dimensional Driver Analysis via `AI.KEY_DRIVERS`**:\n   - Uses Apriori association rule mining to identify combinations of dimensions (segments) that disproportionately explain the delta in metric volume.\n   - Example BigQuery SQL:\n     ```sql\n     WITH cohort_partitioned AS (\n       SELECT\n         trip_id,\n         subscriber_type,\n         bike_type,\n         start_station_name,\n         end_station_name,\n         (DATE(start_time) >= '2018-02-01') AS is_interest_period\n       FROM `bigquery-public-data.austin_bikeshare.bikeshare_trips`\n       WHERE DATE(start_time) BETWEEN '2017-09-01' AND '2018-06-30'\n     )\n     SELECT\n       segment,\n       metric_delta,\n       percentage_change,\n       segment_contribution\n     FROM AI.KEY_DRIVERS(\n       TABLE cohort_partitioned,\n       metric_col => 'trip_id',\n       dimension_cols => ['subscriber_type', 'bike_type', 'end_station_name'],\n       interest_label_col => 'is_interest_period',\n       min_apriori_support => 0.01,\n       top_k => 20\n     )\n     ORDER BY segment_contribution DESC;\n     ```\n2. **Pairwise Metric Correlation via `ML.CORRELATION`**:\n   - Evaluates directional strength between metric pairs across categorical dimensions to identify mediating mechanisms.\n   - Example BigQuery SQL:\n     ```sql\n     SELECT\n       segment,\n       corr_col,\n       correlation,\n       segment_size\n     FROM ML.CORRELATION(\n       TABLE `bigquery-public-data.chicago_taxi_trips.taxi_trips`,\n       target_col => 'trip_total',\n       target_correlation_cols => ['trip_miles', 'trip_seconds'],\n       dimension_cols => ['payment_type', 'company']\n     )\n     ORDER BY segment_size DESC;\n     ```\n\n> **Completion criterion**: Top contributing dimension segments identified; percentage lift and absolute contribution quantified; confounding sub-dimensions ranked.\n\n---\n\n## 4. Counterfactual Impact & Causal Lift Estimation\n\nDifferentiate between organic trajectory growth and the true return on investment (ROI) or causal impact of an intervention, policy change, or campaign launch.\n\n1. **Synthetic Counterfactual Modeling via `AI.CAUSAL_EFFECT`**:\n   - Builds an internal `ARIMA_PLUS` predictive model to project what the metric baseline would have been had the intervention never occurred.\n   - Compares the observed trajectory against this synthetic control to isolate the true causal lift.\n   - Example BigQuery SQL:\n     ```sql\n     WITH time_series_input AS (\n       SELECT\n         DATE(start_time) AS trip_date,\n         COUNT(*) AS trip_count\n       FROM `bigquery-public-data.austin_bikeshare.bikeshare_trips`\n       WHERE DATE(start_time) BETWEEN '2017-01-01' AND '2018-12-31'\n       GROUP BY trip_date\n     )\n     SELECT\n       actual,\n       counterfactual_baseline,\n       absolute_effect,\n       relative_effect,\n       prob_causal_effect\n     FROM AI.CAUSAL_EFFECT(\n       TABLE time_series_input,\n       data_col => 'trip_count',\n       timestamp_col => 'trip_date',\n       intervention_timestamp => '2018-02-01',\n       output_time_series => FALSE\n     );\n     ```\n2. **Time-Series Counterfactual Trajectory**:\n   - When inspecting post-intervention divergence curves over time, set `output_time_series => TRUE` to extract daily confidence intervals (`lower_bound`, `upper_bound`).\n\n> **Completion criterion**: True incremental lift and causal effect probability calculated; organic trend isolated from program impact.\n\n---\n\n## 5. Executive Diagnostic Synthesis & Delivery\n\nTransform technical TVF outputs into actionable business diagnoses and decisions:\n\n1. **Synthesize the 4-Point Diagnostic Narrative**:\n   - **When**: Shift timestamp and persistence duration (from Stage 2).\n   - **What**: Magnitude of change and decomposed trend slope (from Stage 1).\n   - **Who\u002FWhere**: Disproportionate contributing segments and dimension combinations (from Stage 3).\n   - **Impact**: True incremental causal lift over organic baseline (from Stage 4).\n2. **Conversational Analytics Seam**:\n   - Format results as deterministic Markdown tables and structured JSON observations for ReAct agent step consumption and conversational presentation.\n\n> **Completion criterion**: Executive root-cause brief produced with verified TVF backing; recommendations grounded in causal evidence.\n\n---\n\n## Visual Brief Pillar\n\nBefore executing heavy or multi-stage TVF pipelines on large-scale datasets, agents must generate an interactive HTML Visual Brief to visually communicate query parameters, DAG execution sequences, and preliminary data topologies:\n\n1. **Target File Location**:\n   - Save to `%TEMP%\\bigquery-augmented-analytics-\u003Ctimestamp>.html` (Windows) or `\u002Ftmp\u002Fbigquery-augmented-analytics-\u003Ctimestamp>.html` (Unix).\n2. **Styling & Components**:\n   - Dark theme (`#0d1117`) loading Tailwind CSS and Mermaid.js via CDN.\n   - Render a **TVF Investigative Chaining DAG** showing the data flow from `ML.DETECT_CHANGE_POINTS` $\\to$ `AI.KEY_DRIVERS` $\\to$ `AI.CAUSAL_EFFECT`.\n   - Render a **Cohort Partitioning Table** showing the reference vs interest definitions.\n   - Render the **Diagnostic Evaluation Scorecard Table**.\n3. **Delivery**:\n   - Present the absolute, clickable HTML file path to the user.\n\n---\n\n## Mandatory Checkpoint Gate\n\nTo prevent excessive BigQuery slot consumption, unintended partition scans, or misconfigured multi-stage queries, agents must enforce a mandatory human-in-the-loop review gate:\n\n1. Prior to executing write-intensive TVF queries or multi-million-row scans, present an `implementation_plan.md` artifact detailing:\n   - Target dataset and table identifiers.\n   - Incurred byte scan estimates and partition filters.\n   - Formulated TVF chain parameters (`data_col`, `dimension_cols`, `min_apriori_support`).\n   - Planned post-intervention horizon and confidence level.\n2. Set `RequestFeedback: true` in artifact metadata.\n3. **STOP and wait** for explicit user approval before triggering production TVF jobs.\n\n---\n\n## Programmatic IoC Service Seam (Rule 49)\n\nAutonomous ReAct agent step loops and swarm workers dynamically resolve the BigQuery Augmented Analytics engine directly in-memory via the typed micro-kernel key:\n\n```python\nfrom harness.kernel.context import ServiceContext\nfrom harness.services.bigquery_augmented_analytics import (\n    BIGQUERY_AUGMENTED_ANALYTICS_SERVICE_KEY,\n    BigQueryAugmentedAnalyticsService,\n)\n\nasync def run_investigation(context: ServiceContext) -> None:\n    bq_service: BigQueryAugmentedAnalyticsService = context.require(\n        BIGQUERY_AUGMENTED_ANALYTICS_SERVICE_KEY\n    )\n    result = bq_service.run_investigation(\n        target_table=\"bigquery-public-data.austin_bikeshare.bikeshare_trips\",\n        metric_col=\"trip_id\",\n        timestamp_col=\"start_time\",\n        dimension_cols=[\"subscriber_type\", \"bike_type\"],\n    )\n    print(\"When:\", result.narrative.when)\n    print(\"Impact:\", result.narrative.impact)\n```\n\n---\n\n## Domain-Partitioned Plugin Tools (Rule 18 & Rule 45)\n\nThe co-located plugin in `plugins\u002Fdata_engineering\u002Fbigquery_augmented_analytics\u002F` exposes modular tool actions for ReAct agent step dispatch:\n\n- `bigquery_temporal_profile`: Decomposes trend slope and weekly\u002Fmonthly seasonality cycles via `ML.TREND` and `ML.SEASONALITY`.\n- `bigquery_detect_change_points`: Isolates persistent structural regime shifts ($t_0$) with probability $\\ge 0.95$ via `ML.DETECT_CHANGE_POINTS`.\n- `bigquery_attribute_drivers`: Identifies high-dimensional Apriori segment rules explaining cohort deltas via `AI.KEY_DRIVERS`.\n- `bigquery_causal_lift`: Estimates true incremental impact against synthetic counterfactual control via `AI.CAUSAL_EFFECT`.\n- `bigquery_augmented_pipeline`: Orchestrates the complete 5-stage investigation end-to-end.\n- `bigquery_visual_brief`: Renders a dark-theme interactive HTML visual brief with Tailwind CSS and Mermaid DAG topology.\n\n---\n\n## Headless Click CLI Seam (Rule 10 & Rule 6)\n\nDevelopers, CI\u002FCD verification runners, and headless agents can inspect and dry-run TVF compilation without cloud credentials via `harness bq` or `harness bigquery`:\n\n```bash\n# Compile and dry-run Stage 1 Temporal Profiling TVF SQL\nharness bq profile --table austin_bikeshare.trips --data-col trip_id --timestamp-col start_time --dry-run\n\n# Isolate structural regime shifts (probability >= 95%)\nharness bq change-points --table austin_bikeshare.trips --data-col trip_id --timestamp-col start_time --min-prob 0.95\n\n# Scan combinatorial Apriori driver segments\nharness bq drivers --table austin_bikeshare.trips --metric-col trip_id --dims subscriber_type,bike_type --interest-cond \"DATE(start_time) >= '2026-02-15'\" --min-support 0.01\n\n# Model synthetic counterfactual causal lift\nharness bq causal --table austin_bikeshare.trips --data-col trip_id --timestamp-col start_time --intervention 2026-02-15\n\n# Execute end-to-end 5-stage pipeline and generate visual brief\nharness bq pipeline --table austin_bikeshare.trips --metric-col trip_id --timestamp-col start_time --dims subscriber_type,bike_type --dry-run --brief report.html\n```\n\n---\n\n## Anti-Patterns\n\n- **The Data Egress Tax** — Exporting millions of rows from BigQuery to local pandas or R memory instead of executing in-engine SQL TVFs.\n- **Fluctuation Hallucination** — Mistaking recurring cyclical seasonality or random noise for structural change points without verifying via ML.TREND and ML.SEASONALITY.\n- **Naive Pre\u002FPost Attribution** — Attributing 100% of post-intervention delta to an event without estimating the ARIMA_PLUS counterfactual baseline.\n- **Unparameterized Date Hardcoding** — Hardcoding arbitrary date cuts in AI.KEY_DRIVERS instead of chaining dynamic timestamps from ML.DETECT_CHANGE_POINTS.\n- **Micro-Segment Noise Flooding** — Setting min_apriori_support to zero without pruning, leading to thousands of statistically insignificant micro-cohorts.\n","# BigQuery Augmented Analytics: In-Database Anomaly, Attribution & Causal Engine\n\n`bigquery-augmented-analytics` is the autonomous data investigation engine that executes in-database AI, ML, and statistical inference directly inside Google BigQuery via Table-Valued Functions (TVFs). Based on the Google Cloud framework authored by Jenny Ortiz and Haoming Chen, this skill empowers agents to diagnose *why* business metrics change, detect structural step-level shifts, isolate high-dimensional segment drivers via Apriori rules, and quantify true causal lift against synthetic counterfactual baselines—all without exporting a single row of raw data.\n\nRather than succumbing to the **\"Data Egress Tax\"** (pulling millions of rows into local memory for pandas or R), this skill chains compact, expressive BigQuery TVFs where computation is pushed down directly into the distributed columnar storage engine.\n\n```\n[1. Temporal Profiling] ➔ [2. Shift Isolation] ➔ [3. Combinatorial Attribution] ➔ [4. Causal Lift] ➔ [5. Executive Synthesis]\n  ML.TREND \u002F SEASONALITY    ML.DETECT_CHANGE_POINTS    AI.KEY_DRIVERS \u002F CORRELATION     AI.CAUSAL_EFFECT     Root-Cause Brief\n```\n\nSee [CARD.md](CARD.md) for the companion summary card, TVF reference table, and verification checklist.\nConsult [data-management-architect](..\u002Fdata-management-architect\u002FSKILL.md) for data contracts and [deterministic-validation-loop](..\u002Fdeterministic-validation-loop\u002FSKILL.md) for structured observation validation.\n\n---\n\n## 1. Temporal Profiling & Noise Stripping\n\nBefore diagnosing metric changes, decompose raw time-series into underlying structural trajectories and predictable cyclical rhythms. This prevents treating regular seasonal variations as structural anomalies.\n\n1. **Trend Decomposition via `ML.TREND`**:\n   - Strips high-frequency noise and transient spikes from the underlying growth or decline trajectory.\n   - Example BigQuery SQL:\n     ```sql\n     WITH daily_metrics AS (\n       SELECT\n         DATE(timestamp) AS metric_date,\n         COUNT(*) AS total_events\n       FROM `bigquery-public-data.austin_bikeshare.bikeshare_trips`\n       GROUP BY metric_date\n     )\n     SELECT *\n     FROM ML.TREND(\n       TABLE daily_metrics,\n       data_col => 'total_events',\n       timestamp_col => 'metric_date'\n     )\n     ORDER BY metric_date;\n     ```\n2. **Cyclical Periodicity Discovery via `ML.SEASONALITY`**:\n   - Identifies recurring daily, weekly, monthly, and quarterly patterns across metric values.\n   - Example BigQuery SQL:\n     ```sql\n     SELECT *\n     FROM ML.SEASONALITY(\n       TABLE daily_metrics,\n       data_col => 'total_events',\n       timestamp_col => 'metric_date',\n       seasonalities => ['WEEKLY', 'MONTHLY']\n     )\n     ORDER BY metric_date;\n     ```\n\n> **Completion criterion**: Underlying trend direction separated from short-term noise; dominant recurring cycles documented; raw variance normalized against expected seasonality.\n\n---\n\n## 2. Structural Shift & Change-Point Isolation\n\nIsolate the exact historical dates or intervals where a metric experienced a statistically significant, persistent regime shift rather than a transitory fluctuation.\n\n1. **Step-Change Detection via `ML.DETECT_CHANGE_POINTS`**:\n   - Employs scalable Bayesian change-point algorithms capable of evaluating millions of distinct time series in seconds.\n   - Example BigQuery SQL:\n     ```sql\n     WITH baseline_series AS (\n       SELECT\n         DATE(start_time) AS trip_date,\n         COUNT(*) AS daily_trips\n       FROM `bigquery-public-data.austin_bikeshare.bikeshare_trips`\n       GROUP BY trip_date\n     )\n     SELECT\n       start_time,\n       end_time,\n       mean,\n       variance,\n       change_point_prob\n     FROM ML.DETECT_CHANGE_POINTS(\n       TABLE baseline_series,\n       data_col => 'daily_trips',\n       timestamp_col => 'trip_date'\n     )\n     WHERE change_point_prob >= 0.95\n     ORDER BY start_time DESC;\n     ```\n2. **Dynamic Boundary Parameterization**:\n   - Extract the primary shift timestamp ($t_0$) with the highest change probability or longest duration.\n   - Designate the pre-shift interval ($t \u003C t_0$) as the **Reference Group** and the post-shift interval ($t \\ge t_0$) as the **Interest Group** for downstream TVF chaining.\n\n> **Completion criterion**: Statistically significant change-point timestamp $t_0$ isolated with probability $\\ge 95\\%$; time horizons parameterized for attribution.\n\n---\n\n## 3. Combinatorial Attribution & Multi-Dimensional Slicing\n\nScan high-dimensional categorical features across millions of rows to explain the exact drivers of the metric variance between the reference and interest cohorts.\n\n1. **Multi-Dimensional Driver Analysis via `AI.KEY_DRIVERS`**:\n   - Uses Apriori association rule mining to identify combinations of dimensions (segments) that disproportionately explain the delta in metric volume.\n   - Example BigQuery SQL:\n     ```sql\n     WITH cohort_partitioned AS (\n       SELECT\n         trip_id,\n         subscriber_type,\n         bike_type,\n         start_station_name,\n         end_station_name,\n         (DATE(start_time) >= '2018-02-01') AS is_interest_period\n       FROM `bigquery-public-data.austin_bikeshare.bikeshare_trips`\n       WHERE DATE(start_time) BETWEEN '2017-09-01' AND '2018-06-30'\n     )\n     SELECT\n       segment,\n       metric_delta,\n       percentage_change,\n       segment_contribution\n     FROM AI.KEY_DRIVERS(\n       TABLE cohort_partitioned,\n       metric_col => 'trip_id',\n       dimension_cols => ['subscriber_type', 'bike_type', 'end_station_name'],\n       interest_label_col => 'is_interest_period',\n       min_apriori_support => 0.01,\n       top_k => 20\n     )\n     ORDER BY segment_contribution DESC;\n     ```\n2. **Pairwise Metric Correlation via `ML.CORRELATION`**:\n   - Evaluates directional strength between metric pairs across categorical dimensions to identify mediating mechanisms.\n   - Example BigQuery SQL:\n     ```sql\n     SELECT\n       segment,\n       corr_col,\n       correlation,\n       segment_size\n     FROM ML.CORRELATION(\n       TABLE `bigquery-public-data.chicago_taxi_trips.taxi_trips`,\n       target_col => 'trip_total',\n       target_correlation_cols => ['trip_miles', 'trip_seconds'],\n       dimension_cols => ['payment_type', 'company']\n     )\n     ORDER BY segment_size DESC;\n     ```\n\n> **Completion criterion**: Top contributing dimension segments identified; percentage lift and absolute contribution quantified; confounding sub-dimensions ranked.\n\n---\n\n## 4. Counterfactual Impact & Causal Lift Estimation\n\nDifferentiate between organic trajectory growth and the true return on investment (ROI) or causal impact of an intervention, policy change, or campaign launch.\n\n1. **Synthetic Counterfactual Modeling via `AI.CAUSAL_EFFECT`**:\n   - Builds an internal `ARIMA_PLUS` predictive model to project what the metric baseline would have been had the intervention never occurred.\n   - Compares the observed trajectory against this synthetic control to isolate the true causal lift.\n   - Example BigQuery SQL:\n     ```sql\n     WITH time_series_input AS (\n       SELECT\n         DATE(start_time) AS trip_date,\n         COUNT(*) AS trip_count\n       FROM `bigquery-public-data.austin_bikeshare.bikeshare_trips`\n       WHERE DATE(start_time) BETWEEN '2017-01-01' AND '2018-12-31'\n       GROUP BY trip_date\n     )\n     SELECT\n       actual,\n       counterfactual_baseline,\n       absolute_effect,\n       relative_effect,\n       prob_causal_effect\n     FROM AI.CAUSAL_EFFECT(\n       TABLE time_series_input,\n       data_col => 'trip_count',\n       timestamp_col => 'trip_date',\n       intervention_timestamp => '2018-02-01',\n       output_time_series => FALSE\n     );\n     ```\n2. **Time-Series Counterfactual Trajectory**:\n   - When inspecting post-intervention divergence curves over time, set `output_time_series => TRUE` to extract daily confidence intervals (`lower_bound`, `upper_bound`).\n\n> **Completion criterion**: True incremental lift and causal effect probability calculated; organic trend isolated from program impact.\n\n---\n\n## 5. Executive Diagnostic Synthesis & Delivery\n\nTransform technical TVF outputs into actionable business diagnoses and decisions:\n\n1. **Synthesize the 4-Point Diagnostic Narrative**:\n   - **When**: Shift timestamp and persistence duration (from Stage 2).\n   - **What**: Magnitude of change and decomposed trend slope (from Stage 1).\n   - **Who\u002FWhere**: Disproportionate contributing segments and dimension combinations (from Stage 3).\n   - **Impact**: True incremental causal lift over organic baseline (from Stage 4).\n2. **Conversational Analytics Seam**:\n   - Format results as deterministic Markdown tables and structured JSON observations for ReAct agent step consumption and conversational presentation.\n\n> **Completion criterion**: Executive root-cause brief produced with verified TVF backing; recommendations grounded in causal evidence.\n\n---\n\n## Visual Brief Pillar\n\nBefore executing heavy or multi-stage TVF pipelines on large-scale datasets, agents must generate an interactive HTML Visual Brief to visually communicate query parameters, DAG execution sequences, and preliminary data topologies:\n\n1. **Target File Location**:\n   - Save to `%TEMP%\\bigquery-augmented-analytics-\u003Ctimestamp>.html` (Windows) or `\u002Ftmp\u002Fbigquery-augmented-analytics-\u003Ctimestamp>.html` (Unix).\n2. **Styling & Components**:\n   - Dark theme (`#0d1117`) loading Tailwind CSS and Mermaid.js via CDN.\n   - Render a **TVF Investigative Chaining DAG** showing the data flow from `ML.DETECT_CHANGE_POINTS` $\\to$ `AI.KEY_DRIVERS` $\\to$ `AI.CAUSAL_EFFECT`.\n   - Render a **Cohort Partitioning Table** showing the reference vs interest definitions.\n   - Render the **Diagnostic Evaluation Scorecard Table**.\n3. **Delivery**:\n   - Present the absolute, clickable HTML file path to the user.\n\n---\n\n## Mandatory Checkpoint Gate\n\nTo prevent excessive BigQuery slot consumption, unintended partition scans, or misconfigured multi-stage queries, agents must enforce a mandatory human-in-the-loop review gate:\n\n1. Prior to executing write-intensive TVF queries or multi-million-row scans, present an `implementation_plan.md` artifact detailing:\n   - Target dataset and table identifiers.\n   - Incurred byte scan estimates and partition filters.\n   - Formulated TVF chain parameters (`data_col`, `dimension_cols`, `min_apriori_support`).\n   - Planned post-intervention horizon and confidence level.\n2. Set `RequestFeedback: true` in artifact metadata.\n3. **STOP and wait** for explicit user approval before triggering production TVF jobs.\n\n---\n\n## Programmatic IoC Service Seam (Rule 49)\n\nAutonomous ReAct agent step loops and swarm workers dynamically resolve the BigQuery Augmented Analytics engine directly in-memory via the typed micro-kernel key:\n\n```python\nfrom harness.kernel.context import ServiceContext\nfrom harness.services.bigquery_augmented_analytics import (\n    BIGQUERY_AUGMENTED_ANALYTICS_SERVICE_KEY,\n    BigQueryAugmentedAnalyticsService,\n)\n\nasync def run_investigation(context: ServiceContext) -> None:\n    bq_service: BigQueryAugmentedAnalyticsService = context.require(\n        BIGQUERY_AUGMENTED_ANALYTICS_SERVICE_KEY\n    )\n    result = bq_service.run_investigation(\n        target_table=\"bigquery-public-data.austin_bikeshare.bikeshare_trips\",\n        metric_col=\"trip_id\",\n        timestamp_col=\"start_time\",\n        dimension_cols=[\"subscriber_type\", \"bike_type\"],\n    )\n    print(\"When:\", result.narrative.when)\n    print(\"Impact:\", result.narrative.impact)\n```\n\n---\n\n## Domain-Partitioned Plugin Tools (Rule 18 & Rule 45)\n\nThe co-located plugin in `plugins\u002Fdata_engineering\u002Fbigquery_augmented_analytics\u002F` exposes modular tool actions for ReAct agent step dispatch:\n\n- `bigquery_temporal_profile`: Decomposes trend slope and weekly\u002Fmonthly seasonality cycles via `ML.TREND` and `ML.SEASONALITY`.\n- `bigquery_detect_change_points`: Isolates persistent structural regime shifts ($t_0$) with probability $\\ge 0.95$ via `ML.DETECT_CHANGE_POINTS`.\n- `bigquery_attribute_drivers`: Identifies high-dimensional Apriori segment rules explaining cohort deltas via `AI.KEY_DRIVERS`.\n- `bigquery_causal_lift`: Estimates true incremental impact against synthetic counterfactual control via `AI.CAUSAL_EFFECT`.\n- `bigquery_augmented_pipeline`: Orchestrates the complete 5-stage investigation end-to-end.\n- `bigquery_visual_brief`: Renders a dark-theme interactive HTML visual brief with Tailwind CSS and Mermaid DAG topology.\n\n---\n\n## Headless Click CLI Seam (Rule 10 & Rule 6)\n\nDevelopers, CI\u002FCD verification runners, and headless agents can inspect and dry-run TVF compilation without cloud credentials via `harness bq` or `harness bigquery`:\n\n```bash\n# Compile and dry-run Stage 1 Temporal Profiling TVF SQL\nharness bq profile --table austin_bikeshare.trips --data-col trip_id --timestamp-col start_time --dry-run\n\n# Isolate structural regime shifts (probability >= 95%)\nharness bq change-points --table austin_bikeshare.trips --data-col trip_id --timestamp-col start_time --min-prob 0.95\n\n# Scan combinatorial Apriori driver segments\nharness bq drivers --table austin_bikeshare.trips --metric-col trip_id --dims subscriber_type,bike_type --interest-cond \"DATE(start_time) >= '2026-02-15'\" --min-support 0.01\n\n# Model synthetic counterfactual causal lift\nharness bq causal --table austin_bikeshare.trips --data-col trip_id --timestamp-col start_time --intervention 2026-02-15\n\n# Execute end-to-end 5-stage pipeline and generate visual brief\nharness bq pipeline --table austin_bikeshare.trips --metric-col trip_id --timestamp-col start_time --dims subscriber_type,bike_type --dry-run --brief report.html\n```\n\n---\n\n## Anti-Patterns\n\n- **The Data Egress Tax** — Exporting millions of rows from BigQuery to local pandas or R memory instead of executing in-engine SQL TVFs.\n- **Fluctuation Hallucination** — Mistaking recurring cyclical seasonality or random noise for structural change points without verifying via ML.TREND and ML.SEASONALITY.\n- **Naive Pre\u002FPost Attribution** — Attributing 100% of post-intervention delta to an event without estimating the ARIMA_PLUS counterfactual baseline.\n- **Unparameterized Date Hardcoding** — Hardcoding arbitrary date cuts in AI.KEY_DRIVERS instead of chaining dynamic timestamps from ML.DETECT_CHANGE_POINTS.\n- **Micro-Segment Noise Flooding** — Setting min_apriori_support to zero without pruning, leading to thousands of statistically insignificant micro-cohorts.\n",{"name":5,"description":7},"main","eff3b00e36d1d233ad4a4389605c82fbfa0326d3",".agents\u002Fskills\u002Fbigquery-augmented-analytics","https:\u002F\u002Fgithub.com\u002FSpectreDeath\u002FBrain-Harness","https:\u002F\u002Fgithub.com\u002FSpectreDeath","I'm here to manage stress so I wouldn't expect earth shattering break throughs I'm just an enthusiast that likes making stuff. ","2026-11-15 05:32:58",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add SpectreDeath\u002FBrain-Harness --skill bigquery-augmented-analytics",{"tool":37,"command":38},"bunx","bunx skills add SpectreDeath\u002FBrain-Harness --skill bigquery-augmented-analytics",{"tool":40,"command":41},"pnpm","pnpm dlx skills add SpectreDeath\u002FBrain-Harness --skill bigquery-augmented-analytics","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FSpectreDeath\u002FBrain-Harness\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fbigquery-augmented-analytics\u002FSKILL.md",true,[45,51,55],{"path":46,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":49,"sourceHtmlUrl":50},"CARD.md","REFERENCE","参考文档",4612,"https:\u002F\u002Fgithub.com\u002FSpectreDeath\u002FBrain-Harness\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fbigquery-augmented-analytics\u002FCARD.md",{"path":52,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":53,"sourceHtmlUrl":54},"config.default.yaml",330,"https:\u002F\u002Fgithub.com\u002FSpectreDeath\u002FBrain-Harness\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fbigquery-augmented-analytics\u002Fconfig.default.yaml",{"path":56,"resourceType":57,"resourceTypeDesc":58,"sizeBytes":59,"sourceHtmlUrl":60},"scripts\u002Fbigquery_augmented_analytics.py","SCRIPT","脚本",52957,"https:\u002F\u002Fgithub.com\u002FSpectreDeath\u002FBrain-Harness\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fbigquery-augmented-analytics\u002Fscripts\u002Fbigquery_augmented_analytics.py",[62,69,76,83,90,97],{"skillNo":63,"name":64,"nameZh":6,"description":65,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":66,"categories":67,"keywords":68,"publishedAt":19},"01M7E0W6FR68J2N9CXCZTAQJFX","ui-behavior-primitive-architect","Architect, audit, and verify zero-dependency headless UI behavior primitives, WebMCP agent bridges, WAI-ARIA\u002FSSR\u002FRTL tri-modal checks, and framework expert routing. Do not use for static CSS theme styling or backend database migrations.","https:\u002F\u002Fgithub.com\u002FSpectreDeath\u002FBrain-Harness\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fui-behavior-primitive-architect\u002FSKILL.md",[],[],{"skillNo":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":19},"01M7E0VZ7JQNW34G271DENFGYP","trustgraph-ontology-governor","Govern knowledge graphs, SHACL-AF triple policies, OntologyRAG subclass validation, PROV-O dual named graphs, and Laya entropy decision scoring. Do not use for relational SQL queries or generic web scraping.","https:\u002F\u002Fgithub.com\u002FSpectreDeath\u002FBrain-Harness\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Ftrustgraph-ontology-governor\u002FSKILL.md",[],[],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":19},"01M7E0VQ6Z7R45Q8QAZ4MT39EK","shim-harness-governor","Govern universal CLI agent loops, 4-tier tool permissions, ancestor-symlink workspace sandboxes, deterministic-first command routing, collision-safe MCP namespacing, and layered skill loading. Do not use for static UI styling or external SQL analytics.","https:\u002F\u002Fgithub.com\u002FSpectreDeath\u002FBrain-Harness\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fshim-harness-governor\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":19},"01M7E0VC18NMP1QBSRJ3TPQ7MB","graphiti-zep-memory-governor","Govern bi-temporal knowledge graphs with Graphiti future-edge clamping, MinHash\u002FLSH entity dedup, RRF\u002FMMR reranking, and Zep typed ontologies. Do not use for static SQL joins or generic web crawling.","https:\u002F\u002Fgithub.com\u002FSpectreDeath\u002FBrain-Harness\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fgraphiti-zep-memory-governor\u002FSKILL.md",[],[],{"skillNo":91,"name":92,"nameZh":6,"description":93,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":94,"categories":95,"keywords":96,"publishedAt":19},"01M7E0V12ABE1RW3ZRCST8VH5Z","agora-mcp-workbench-architect","Architect, audit, and orchestrate Agora Workbench MCP servers, loopback sidecars, unified state graphs, gateway\u002Fdispatcher connectors, and policy-enforced data lakes. Do not use for static frontend CSS styling or non-MCP desktop GUI automation.","https:\u002F\u002Fgithub.com\u002FSpectreDeath\u002FBrain-Harness\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fagora-mcp-workbench-architect\u002FSKILL.md",[],[],{"skillNo":98,"name":99,"nameZh":6,"description":100,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":101,"categories":102,"keywords":103,"publishedAt":19},"01M7BFYG6QT3484VC57TZ19V7P","skill-eval-assurance-runner","Evaluate and assure agent skills using small-N Wilson confidence intervals, unbiased pass^k reliability, deterministic trajectory graders, preflight boundary honesty, and sealed digest verification. Do not use for subjective prose review or unconstrained production deployment.","https:\u002F\u002Fgithub.com\u002FSpectreDeath\u002FBrain-Harness\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fskill-eval-assurance-runner\u002FSKILL.md",[],[]]