diagnose-months

Detect foreign key resolution failures and month-level data gaps in staged financial data.

Updated Mar 1, 2026
One-click install
npx skills add https://github.com/clenisa/optimal-cli --skill diagnose-months
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: diagnose-months
Source: https://github.com/clenisa/optimal-cli/tree/main/skills/diagnose-months
Command: npx skills add https://github.com/clenisa/optimal-cli --skill diagnose-months

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Diagnoses foreign key resolution failures and month-level data gaps in staged financial records to quickly identify why audit accuracy falls below 100%. It helps teams find orphaned account codes, unresolved program IDs, missing client mappings, and months with unexpectedly low or zero staging rows so they can remediate ETL and mapping issues.

Core Features & Use Cases

  • Scan one or multiple YYYY-MM months in the staging table and count rows per month to detect gaps and zero-data months.
  • Attempt FK resolution by joining account_code to dim_account, master_program_id to dim_master_program, and client_id to dim_client and summarize unresolved rows by type and month.
  • Provide verbose output to list individual failing rows for debugging and integration with activity logging for audit trails.
  • Use case: run after an audit-financials check reports accuracy below 100% to identify exactly which rows and months failed resolution.

Quick Start

Diagnose FK resolution failures and data gaps for months 2026-01 and 2025-12 and show individual failing rows by running the diagnose-months skill with months 2026-01,2025-12 and verbose enabled.

Frequently Asked Questions about diagnose-months

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I diagnose foreign key resolution failures in staged financial data?

To diagnose foreign key resolution failures in staged financial data, join account_code to dim_account, master_program_id to dim_master_program, and client_id to dim_client to summarize unresolved rows by type and month.

What causes month-level data gaps in Supabase staging tables?

Month-level data gaps in Supabase staging tables occur when ETL processes fail to load records for specific YYYY-MM periods, resulting in unexpectedly low or zero staging rows that require row-count validation to detect.

How do I validate staged financials for orphaned account codes and missing client mappings?

You validate staged financials for orphaned account codes and missing client mappings by running a diagnostic skill against stg_financials_raw that attempts dimension table joins and flags unresolved rows for ETL remediation.

Do I need Supabase environment credentials to detect unresolved joins in financial staging data?

Yes, you need the RETURNPRO_SUPABASE_URL and RETURNPRO_SUPABASE_SERVICE_KEY environment credentials to access Supabase staging and dimension tables for detecting unresolved joins in financial staging data.

Can I list individual failing rows when diagnosing monthly data gaps in Supabase?

Yes, you can list individual failing rows when diagnosing monthly data gaps in Supabase by enabling verbose output, which provides detailed debugging information and integrates with activity logging for audit trails.

When should I run a foreign key resolution check on financial staging tables?

You should run a foreign key resolution check on financial staging tables immediately after an audit-financials check reports accuracy below 100%, allowing you to identify exactly which rows and months failed resolution.