nerc-gads-reporting

Overview

This skill converts raw generating-unit operational data into validated NERC GADS event reports and IEEE 762 / NERC standard performance indexes. GADS is NERC's mandatory program for collecting generating unit performance data. The skill parses raw event data from plant historians, CMMS systems, or manual logs, classifies events against the NERC event type taxonomy, calculates the standard performance indexes, validates data for submission readiness, and produces outputs suitable for eGADS upload or internal performance review. The user provides raw operational data and the roster of unit capacities; the skill returns validated, submission-ready reports.

Use it when a compliance or reliability analyst needs event classification, index calculation, cause code analysis, fleet benchmarking, or a pre-submission validation pass. The skill does the computational work: parsing timelines, resolving overlapping derates, computing equivalent hours, and generating deliverables. Time-sensitive regulatory values (thresholds, deadlines, benchmark averages) are verified from authoritative sources at runtime, never assumed.

Workflow

<Workflow - Generate GADS Report description="Parse raw generator event data, classify events, calculate performance indexes, validate submission readiness, and produce GADS deliverables." tools=[get_current_time, file_read, file_read_pdf, run_python, web_search, url_fetch, open_in_session_tab] triggers=["User asks to prepare or validate a GADS report", "User asks to calculate EFOR, EAF, or other generator availability indexes", "User asks to classify generating unit events or analyze outage cause codes"] preferred_model=smart

1. [Ask user] Request the inputs: the event log(s) (CSV, Excel, or PDF), the unit roster with capacities (Net Maximum Capacity and Net Dependable Capacity per unit), the target reporting period (quarter and year), and where deliverables should be saved. Validate: At least one event log, one roster with NMC and NDC, and a reporting period are provided, plus an output location. If fails: Re-ask, naming the specific missing input and an example of its form.
2. [Agent] Verify time-sensitive reference data before any calculation. Call get_current_time. Identify which regulatory values this run needs (reporting thresholds and effective dates for the unit types present, submission deadline for the period, and any benchmark figures to be used in step 8). For each, fetch the current value from the authoritative source in references/thresholds-and-deadlines.md via web_search or url_fetch. Validate: Every time-sensitive value needed downstream has a verified source fetched this session or supplied by the user. If fails: Per Rule 1, stop and ask the user to confirm or provide the value before continuing.
3. [Agent] Parse the input data with run_python (pandas/openpyxl for CSV/Excel, file_read_pdf then parsing for PDF). For each event record extract: Unit ID, Event Start DateTime, Event End DateTime, Event Type Code, Net MW Available During Event, Cause Code (System/Component/Amplification), Contributing Operating Condition (if post-2024), and any verbal description. Validate: Records load into a structured table with the fields above; row count matches the source. If fails: Report the parse error and the offending rows; ask the user for a corrected file or column mapping.
4. [Think] Validate required fields and flag issues against references/classification-rules.md: missing event end dates (open events); overlapping events on the same unit without primary/contributing classification; events under 1 minute that are not unit trips; derates below the reporting threshold (greater of 10 MW or 2% NDC); U1 events missing a valid amplification code (84, T1, or T2); and any post-2024 event missing a COC code.
5. [Decide] If validation errors exist, present a summary table (issue, affected record(s), recommended resolution) and [Ask user] to confirm corrections before proceeding. If none, continue. Validate: Either no errors, or the user has confirmed how to resolve each. If fails: Hold at this step until the user resolves or accepts each flagged item.
6. [Agent] With run_python, compute Period Hours for the reporting period (exact calendar hours, leap-year aware, no DST adjustment). Then per unit compute all time-state components (SH, RSH, FOH, MOH, POH) and equivalent derated hours (EFDH, EMDH, EPDH) using the definitions in references/performance-indexes.md, capping overlapping derates at NDC per references/classification-rules.md. Validate: For each unit, PH equals the sum of all state hours plus inactive hours within +/- 0.1 hour. If fails: Report the imbalance per unit and the events that do not reconcile; ask the user to resolve before computing indexes.
7. [Agent] With run_python, compute all performance indexes per unit using the exact formulas in references/performance-indexes.md (EAF, EFOR, EFORd, NCF, GCF, SF, AF, FOF, POF, MOF, FOR, MTBF, MTTR), rounded to one decimal place. Validate: Every listed index is produced for every unit and rounded correctly. If fails: Recompute the missing or malformed index; do not omit it silently.
8. [Agent] Perform cause code analysis using references/cause-codes.md: group events by Level 1 system, total hours lost and MW-hours lost per code, identify the top 5 by frequency and by impact, and flag any cause code inconsistent with its event type (for example a weather code on a planned outage). Compare each unit's EFOR against the verified benchmark from step 2. Validate: Cause code groupings and top-5 lists are produced; benchmark comparison uses only the value verified in step 2. If fails: Recompute from the classified event table; if the benchmark was not verified, return to step 2.
9. [Agent] Generate the deliverables and save them to the user's chosen location, then open each with open_in_session_tab:
   • GADS Event Report as an Excel workbook matching the eGADS import template structure (one record per event, sorted by Unit ID then Event Start, dates as MM/DD/YYYY HH:MM, primary/contributing relationships) via canvas_xlsx.
   • Performance Index Summary (Excel via canvas_xlsx, PDF via canvas_pdf).
   • Cause Code Analysis Report as a PDF with charts via canvas_pdf, using html_design and highcharts guidance for any visualizations.
   • Unit Comparison Dashboard ranking units by EAF and color-coding EFOR against the verified benchmark thresholds, as an HTML artifact (html_design + highcharts) or PDF.
   • Validation Checklist as Markdown via canvas_md, one PASS/FAIL line per DRI readiness item (mandatory fields populated, cause codes valid for unit type, time accounting balanced, no overlapping primary events, design data record present per unit). Each deliverable must carry the Rule 7 disclaimer. Validate: Every deliverable is written to the chosen location, opened in a session tab, and includes the disclaimer. If fails: Report which deliverable could not be produced and why; retry that one.
10. [Agent] Notify the user with a summary. If any validation checklist item is FAIL, list those items first and state that the data is not submission-ready until they are resolved. Validate: The summary names the output location, lists each deliverable, and surfaces every FAIL item. If fails: Re-send the summary with the missing detail.

</Workflow - Generate GADS Report>