kodelyth-ecc 2.19.0 → 2.21.0

package/.gemini/skills/ecc-token-savings/SKILL.md

@@ -1,106 +0,0 @@
----
-name: ecc-token-savings
-description: Maximize token savings across an ECC-equipped session by combining the three shipped layers — RTK (input compression on shell output), Terse mode (output compression on AI replies), and the codebase graph (structural queries instead of file-by-file grep). Use when the user asks how to cut token cost, why a session is expensive, or how to use RTK/Terse/codebase-graph together.
-origin: ECC
----
-
-# ECC Token Savings Stack
-
-Kodelyth ECC ships three independent token-savings layers. They stack. Used together on a typical coding session they cut **55-65% of total token cost** — more on explain-heavy or exploration-heavy work. This skill is the unified playbook; the per-feature docs live in `docs/rtk.md`, `docs/terse-mode.md`, `docs/codebase-graph.md`.
-
-## The three layers (know which axis each cuts)
-
-| Layer | Cuts | How | Typical saving |
-|---|---|---|---|
-| **RTK** | Input tokens | Filters shell-command output before the LLM sees it | 60-90% on `git`/`ls`/`test`/`docker`/... |
-| **Terse mode** | Output tokens | Compresses what the AI writes, code stays byte-exact | 40-70% on replies |
-| **Codebase graph** | Input tokens | One structural query replaces dozens of grep/read cycles | ~99% on "who calls X" questions |
-
-They are orthogonal — RTK and codebase-graph shrink what goes *in*, Terse shrinks what comes *out*. Turning on all three compounds.
-
-## Verify what's active
-
-```bash
-kodelythecc rtk status        # RTK binary + wired IDEs + live ledger
-kodelythecc terse status      # skill installed? current ledger totals
-kodelythecc codebase status   # binary version + indexed projects
-```
-
-If any is missing, install it:
-
-```bash
-kodelythecc rtk enable --all              # wire RTK into every ECC-installed IDE
-kodelythecc terse enable --all            # install /terse + /terse-compress
-kodelythecc codebase install              # install codebase-memory-mcp + register
-```
-
-## The workflow — what to actually do
-
-### 1. Let RTK ride silently (already on after install)
-
-RTK is a PreToolUse hook. Once wired, every shell command the AI runs is auto-filtered. Nothing to do per-session. If you want the compact output in `Read`/`Grep` too, prefer shell (`rg`, `cat`, `find`) or explicit `rtk read`/`rtk grep` — the Bash hook doesn't cover the built-in file tools.
-
-### 2. Turn on Terse mode for the session
-
-```
-/terse full         # telegram-style fragments, ~50% output cut (default)
-/terse ultra        # maximum, ~70% cut — for expert users on familiar work
-/terse lite         # light trim, ~25% — when you still want readable prose
-/terse off          # restore normal voice (docs writing, teaching, onboarding)
-```
-
-Rule of thumb: `full` for day-to-day coding, `off` when the *output itself is the deliverable* (documentation, explanations for others, teaching).
-
-### 3. Query the graph instead of grepping
-
-Once a project is indexed (`"Index this project"` in your AI tool), replace exploration greps with structural queries:
-
-```bash
-kodelythecc codebase query search_graph '{"name_pattern": ".*Handler.*"}'
-kodelythecc codebase query trace_path   '{"function_name": "processOrder"}'
-kodelythecc codebase query get_architecture '{}'
-```
-
-"Who calls X", "what's the impact of changing Y", "show the architecture" — all one query, ~3k tokens, versus ~400k tokens of file-by-file reading.
-
-### 4. Compress persistent memory files once, save forever
-
-```bash
-kodelythecc terse compress CLAUDE.md          # ~30% smaller, code/URLs/paths byte-exact
-kodelythecc terse compress tasks/lessons.md
-```
-
-Every session that loads these files now costs ~30% fewer input tokens — permanently, not per-turn.
-
-## Measure it — don't guess
-
-```bash
-kodelythecc dashboard        # Token Savings tab: RTK (input) + Terse (output), live ledgers
-kodelythecc rtk gain --all   # raw RTK savings numbers
-kodelythecc terse stats      # output tokens saved, by level
-```
-
-The dashboard shows real ledger data, never estimates. Point the user there when they ask "how much am I actually saving."
-
-## Honest caveats — say these, don't oversell
-
-- **Terse adds ~800-1200 input tokens per turn** (the skill prompt). On turns under ~2k output tokens it can be net-negative — skip Terse for short back-and-forth.
-- **RTK only covers the Bash tool.** `Read`/`Grep`/`Glob` bypass it. Use shell equivalents to get RTK compression there.
-- **The codebase graph must be indexed first** and re-indexed after big changes (`"Index this project"` or `codebase-memory-mcp` auto-watch).
-- Native Windows RTK install is manual (`.zip` from releases); WSL and macOS/Linux auto-install.
-
-## Quick recommendation by session type
-
-| Session type | RTK | Terse | Graph |
-|---|:---:|:---:|:---:|
-| Day-to-day coding | on | `full` | query on explore |
-| Deep debugging | on | `lite` (keep reasoning readable) | `trace_path` heavily |
-| Codebase exploration / onboarding | on | `off` | primary tool |
-| Writing docs / teaching | on | `off` | as needed |
-| Expert on familiar code | on | `ultra` | query on explore |
-
-## See also
-
-- `docs/rtk.md`, `docs/terse-mode.md`, `docs/codebase-graph.md` — per-feature deep dives
-- Skills: [[terse-mode]], [[token-budget-advisor]], [[cost-aware-model-routing]]
-- The `cost-aware-model-routing` rule picks the model *tier*; this skill cuts the *token count* at whatever tier you're on.

package/.gemini/skills/ecc-tools-cost-audit/SKILL.md

@@ -1,160 +0,0 @@
----
-name: ecc-tools-cost-audit
-description: Evidence-first ECC Tools burn and billing audit workflow. Use when investigating runaway PR creation, quota bypass, premium-model leakage, duplicate jobs, or GitHub App cost spikes in the ECC Tools repo.
-origin: ECC
----
-
-# ECC Tools Cost Audit
-
-Use this skill when the user suspects the ECC Tools GitHub App is burning cost, over-creating PRs, bypassing usage limits, or routing free users into premium analysis paths.
-
-This is a focused operator workflow for the sibling [ECC-Tools](../../ECC-Tools) repo. It is not a generic billing skill and it is not a repo-wide code review pass.
-
-## Skill Stack
-
-Pull these ECC-native skills into the workflow when relevant:
-
-- `autonomous-loops` for bounded multi-step audits that cross webhooks, queues, billing, and retries
-- `agentic-engineering` for tracing the request path into discrete, provable units
-- `customer-billing-ops` when repo behavior and customer-impact math must be separated cleanly
-- `search-first` before inventing helpers or re-implementing repo-local utilities
-- `security-review` when auth, usage gates, entitlements, or secrets are touched
-- `verification-loop` for proving rerun safety and exact post-fix state
-- `tdd-workflow` when the fix needs regression coverage in the worker, router, or billing paths
-
-## When To Use
-
-- user says ECC Tools burn rate, PR recursion, over-created PRs, usage-limit bypass, or premium-model leakage
-- the task is in the sibling `ECC-Tools` repo and depends on webhook handlers, queue workers, usage reservation, PR creation logic, or paid-gate enforcement
-- a customer report says the app created too many PRs, billed incorrectly, or analyzed code without producing a usable result
-
-## Scope Guardrails
-
-- work in the sibling `ECC-Tools` repo, not in `kodelyth-ecc`
-- start read-only unless the user clearly asked for a fix
-- do not mutate unrelated billing, checkout, or UI flows while tracing analysis burn
-- treat app-generated branches and app-generated PRs as red-flag recursion paths until proved otherwise
-- separate three things explicitly:
-  - repo-side burn root cause
-  - customer-facing billing impact
-  - product or entitlement gaps that need backlog follow-up
-
-## Workflow
-
-### 1. Freeze repo scope
-
-- switch into the sibling `ECC-Tools` repo
-- check branch and local diff first
-- identify the exact surface under audit:
-  - webhook router
-  - queue producer
-  - queue consumer
-  - PR creation path
-  - usage reservation / billing path
-  - model routing path
-
-### 2. Trace ingress before theorizing
-
-- inspect `src/index.*` or the main entrypoint first
-- map every enqueue path before suggesting a fix
-- confirm which GitHub events share a queue type
-- confirm whether push, pull_request, synchronize, comment, or manual re-run events can converge on the same expensive path
-
-### 3. Trace the worker and side effects
-
-- inspect the queue consumer or scheduled worker that handles analysis
-- confirm whether a queued analysis always ends in:
-  - PR creation
-  - branch creation
-  - file updates
-  - premium model calls
-  - usage increments
-- if analysis can spend tokens and then fail before output is persisted, classify it as burn-with-broken-output
-
-### 4. Audit the high-signal burn paths
-
-#### PR multiplication
-
-- inspect PR helpers and branch naming
-- check dedupe, synchronize-event handling, and existing-PR reuse
-- if app-generated branches can re-enter analysis, treat that as a priority-0 recursion risk
-
-#### Quota bypass
-
-- inspect where quota is checked versus where usage is reserved or incremented
-- if quota is checked before enqueue but usage is charged only inside the worker, treat concurrent front-door passes as a real race
-
-#### Premium-model leakage
-
-- inspect model selection, tier branching, and provider routing
-- verify whether free or capped users can still hit premium analyzers when premium keys are present
-
-#### Retry burn
-
-- inspect retry loops, duplicate queue jobs, and deterministic failure reruns
-- if the same non-transient error can spend analysis repeatedly, fix that before quality improvements
-
-### 5. Fix in burn order
-
-If the user asked for code changes, prioritize fixes in this order:
-
-1. stop automatic PR multiplication
-2. stop quota bypass
-3. stop premium leakage
-4. stop duplicate-job fanout and pointless retries
-5. close rerun/update safety gaps
-
-Keep the pass bounded to one to three direct fixes unless the same root cause clearly spans multiple files.
-
-### 6. Verify with the smallest proving steps
-
-- rerun only the targeted tests or integration slices that cover the changed path
-- verify whether the burn path is now:
-  - blocked
-  - deduped
-  - downgraded to cheaper analysis
-  - or rejected early
-- state the final status exactly:
-  - changed locally
-  - verified locally
-  - pushed
-  - deployed
-  - still blocked
-
-## High-Signal Failure Patterns
-
-### 1. One queue type for all triggers
-
-If pushes, PR syncs, and manual audits all enqueue the same job and the worker always creates a PR, analysis equals PR spam.
-
-### 2. Post-enqueue usage reservation
-
-If usage is checked at the front door but only incremented in the worker, concurrent requests can all pass the gate and exceed quota.
-
-### 3. Free tier on premium path
-
-If free queued jobs can still route into Anthropic or another premium provider when keys exist, that is real spend leakage even if the user never sees the premium result.
-
-### 4. App-generated branches re-enter the webhook
-
-If `pull_request.synchronize`, branch pushes, or comment-triggered runs fire on app-owned branches, the app can recursively analyze its own output.
-
-### 5. Expensive work before persistence safety
-
-If the system can spend tokens and then fail on PR creation, file update, or branch collision, it is burning cost without shipping value.
-
-## Pitfalls
-
-- do not begin with broad repo wandering; settle webhook -> queue -> worker first
-- do not mix customer billing inference with code-backed product truth
-- do not fix lower-value quality issues before the highest-burn path is contained
-- do not claim burn is fixed until the narrow proving step was rerun
-- do not push or deploy unless the user asked
-- do not touch unrelated repo-local changes if they are already in progress
-
-## Verification
-
-- root causes cite exact file paths and code areas
-- fixes are ordered by burn impact, not code neatness
-- proving commands are named
-- final status distinguishes local change, verification, push, and deployment

package/.gemini/skills/email-ops/SKILL.md

@@ -1,121 +0,0 @@
----
-name: email-ops
-description: Evidence-first mailbox triage, drafting, send verification, and sent-mail-safe follow-up workflow for ECC. Use when the user wants to organize email, draft or send through the real mail surface, or prove what landed in Sent.
-origin: ECC
----
-
-# Email Ops
-
-Use this when the real task is mailbox work: triage, drafting, replying, sending, or proving a message landed in Sent.
-
-This is not a generic writing skill. It is an operator workflow around the actual mail surface.
-
-## Skill Stack
-
-Pull these ECC-native skills into the workflow when relevant:
-
-- `brand-voice` before drafting anything user-facing
-- `investor-outreach` for investor, partner, or sponsor-facing mail
-- `customer-billing-ops` when the thread is a billing/support incident rather than generic correspondence
-- `knowledge-ops` when the message or thread should be captured into durable context afterward
-- `research-ops` when a reply depends on fresh external facts
-
-## When to Use
-
-- user asks to triage inbox or archive low-signal mail
-- user wants a draft, reply, or new outbound email
-- user wants to know whether a mail was already sent
-- the user wants proof of which account, thread, or Sent entry was used
-
-## Guardrails
-
-- draft first unless the user clearly asked for a live send
-- never claim a message was sent without a real Sent-folder or client-side confirmation
-- do not switch sender accounts casually; choose the account that matches the project and recipient
-- do not delete uncertain business mail during cleanup
-- if the task is really DM or iMessage work, hand off to `messages-ops`
-
-## Workflow
-
-### 1. Resolve the exact surface
-
-Before acting, settle:
-
-- which mailbox account
-- which thread or recipient
-- whether the task is triage, draft, reply, or send
-- whether the user wants draft-only or live send
-
-### 2. Read the thread before composing
-
-If replying:
-
-- read the existing thread
-- identify the last outbound touch
-- identify any commitments, deadlines, or unanswered questions
-
-If creating a new outbound:
-
-- identify warmth level
-- select the correct channel and sender account
-- pull `brand-voice` before drafting
-
-### 3. Draft, then verify
-
-For draft-only work:
-
-- produce the final copy
-- state sender, recipient, subject, and purpose
-
-For live-send work:
-
-- verify the exact final body first
-- send through the chosen mail surface
-- confirm the message landed in Sent or the equivalent sent-copy store
-
-### 4. Report exact state
-
-Use exact status words:
-
-- drafted
-- approval-pending
-- sent
-- blocked
-- awaiting verification
-
-If the send surface is blocked, preserve the draft and report the exact blocker instead of improvising a second transport without saying so.
-
-## Output Format
-
-```text
-MAIL SURFACE
-- account
-- thread / recipient
-- requested action
-
-DRAFT
-- subject
-- body
-
-STATUS
-- drafted / sent / blocked
-- proof of Sent when applicable
-
-NEXT STEP
-- send
-- follow up
-- archive / move
-```
-
-## Pitfalls
-
-- do not claim send success without a sent-copy check
-- do not ignore the thread history and write a contextless reply
-- do not mix mailbox work with DM or text-message workflows
-- do not expose secrets, auth details, or unnecessary message metadata
-
-## Verification
-
-- the response names the account and thread or recipient
-- any send claim includes Sent proof or an explicit client-side confirmation
-- the final state is one of drafted / sent / blocked / awaiting verification

package/.gemini/skills/energy-procurement/SKILL.md

@@ -1,228 +0,0 @@
----
-name: energy-procurement
-description: >
-  Codified expertise for electricity and gas procurement, tariff optimization,
-  demand charge management, renewable PPA evaluation, and multi-facility energy
-  cost management. Informed by energy procurement managers with 15+ years
-  experience at large commercial and industrial consumers. Includes market
-  structure analysis, hedging strategies, load profiling, and sustainability
-  reporting frameworks. Use when procuring energy, optimizing tariffs, managing
-  demand charges, evaluating PPAs, or developing energy strategies.
-license: Apache-2.0
-version: 1.0.0
-homepage: https://github.com/sifxprime/kodelyth-ecc
-origin: ECC
-metadata:
-  author: evos
-  clawdbot:
-    emoji: ""
----
-
-# Energy Procurement
-
-## Role and Context
-
-You are a senior energy procurement manager at a large commercial and industrial (C&I) consumer with multiple facilities across regulated and deregulated electricity markets. You manage an annual energy spend of $15M–$80M across 10–50+ sites — manufacturing plants, distribution centers, corporate offices, and cold storage. You own the full procurement lifecycle: tariff analysis, supplier RFPs, contract negotiation, demand charge management, renewable energy sourcing, budget forecasting, and sustainability reporting. You sit between operations (who control load), finance (who own the budget), sustainability (who set emissions targets), and executive leadership (who approve long-term commitments like PPAs). Your systems include utility bill management platforms (Urjanet, EnergyCAP), interval data analytics (meter-level 15-minute kWh/kW), energy market data providers (ICE, CME, Platts), and procurement platforms (energy brokers, aggregators, direct ISO market access). You balance cost reduction against budget certainty, sustainability targets, and operational flexibility — because a procurement strategy that saves 8% but exposes the company to a $2M budget variance in a polar vortex year is not a good strategy.
-
-## When to Use
-
-- Running an RFP for electricity or natural gas supply across multiple facilities
-- Analyzing tariff structures and rate schedule optimization opportunities
-- Evaluating demand charge mitigation strategies (load shifting, battery storage, power factor correction)
-- Assessing PPA (Power Purchase Agreement) offers for on-site or virtual renewable energy
-- Building annual energy budgets and hedge position strategies
-- Responding to market volatility events (polar vortex, heat wave, regulatory changes)
-
-## How It Works
-
-1. Profile each facility's load shape using interval meter data (15-minute kWh/kW) to identify cost drivers
-2. Analyze current tariff structures and identify optimization opportunities (rate switching, demand response enrollment)
-3. Structure procurement RFPs with appropriate product specifications (fixed, index, block-and-index, shaped)
-4. Evaluate bids using total cost of energy (not just $/MWh) including capacity, transmission, ancillaries, and risk premium
-5. Execute contracts with staggered terms and layered hedging to avoid concentration risk
-6. Monitor market positions, rebalance hedges on trigger events, and report budget variance monthly
-
-## Examples
-
-- **Multi-site RFP**: 25 facilities across PJM and ERCOT with $40M annual spend. Structure the RFP to capture load diversity benefits, evaluate 6 supplier bids across fixed, index, and block-and-index products, and recommend a blended strategy that locks 60% of volume at fixed rates while maintaining 40% index exposure.
-- **Demand charge mitigation**: Manufacturing plant in Con Edison territory paying $28/kW demand charges on a 2MW peak. Analyze interval data to identify the top 10 demand-setting intervals, evaluate battery storage (500kW/2MWh) economics against load curtailment and power factor correction, and calculate payback period.
-- **PPA evaluation**: Solar developer offers a 15-year virtual PPA at $35/MWh with a $5/MWh basis risk at the settlement hub. Model the expected savings against forward curves, quantify basis risk exposure using historical node-to-hub spreads, and present the risk-adjusted NPV to the CFO with scenario analysis for high/low gas price environments.
-
-## Core Knowledge
-
-### Pricing Structures and Utility Bill Anatomy
-
-Every commercial electricity bill has components that must be understood independently — bundling them into a single "rate" obscures where real optimization opportunities exist:
-
-- **Energy charges:** The per-kWh cost for electricity consumed. Can be flat rate (same price all hours), time-of-use/TOU (different prices for on-peak, mid-peak, off-peak), or real-time pricing/RTP (hourly prices indexed to wholesale market). For large C&I customers, energy charges typically represent 40–55% of the total bill. In deregulated markets, this is the component you can competitively procure.
-- **Demand charges:** Billed on peak kW drawn during a billing period, measured in 15-minute intervals. The utility takes the highest single 15-minute average kW reading in the month and multiplies by the demand rate ($8–$25/kW depending on utility and rate class). Demand charges represent 20–40% of the bill for manufacturing facilities with variable loads. One bad 15-minute interval — a compressor startup coinciding with HVAC peak — can add $5,000–$15,000 to a monthly bill.
-- **Capacity charges:** In markets with capacity obligations (PJM, ISO-NE, NYISO), your share of the grid's capacity cost is allocated based on your peak load contribution (PLC) during the prior year's system peak hours (typically 1–5 hours in summer). PLC is measured at your meter during the system coincident peak. Reducing load during those few critical hours can cut capacity charges by 15–30% the following year. This is the single highest-ROI demand response opportunity for most C&I customers.
-- **Transmission and distribution (T&D):** Regulated charges for moving power from generation to your meter. Transmission is typically based on your contribution to the regional transmission peak (similar to capacity). Distribution includes customer charges, demand-based delivery charges, and volumetric delivery charges. These are generally non-bypassable — even with on-site generation, you pay distribution charges for being connected to the grid.
-- **Riders and surcharges:** Renewable energy standards compliance, nuclear decommissioning, utility transition charges, and regulatory mandated programs. These change through rate cases. A utility rate case filing can add $0.005–$0.015/kWh to your delivered cost — track open proceedings at your state PUC.
-
-### Procurement Strategies
-
-The core decision in deregulated markets is how much price risk to retain versus transfer to suppliers:
-
-- **Fixed-price (full requirements):** Supplier provides all electricity at a locked $/kWh for the contract term (12–36 months). Provides budget certainty. You pay a risk premium — typically 5–12% above the forward curve at contract signing — because the supplier is absorbing price, volume, and basis risk. Best for organizations where budget predictability outweighs cost minimization.
-- **Index/variable pricing:** You pay the real-time or day-ahead wholesale price plus a supplier adder ($0.002–$0.006/kWh). Lowest long-run average cost, but full exposure to price spikes. In ERCOT during Winter Storm Uri (Feb 2021), wholesale prices hit $9,000/MWh — an index customer on a 5 MW peak load faced a single-week energy bill exceeding $1.5M. Index pricing requires active risk management and a corporate culture that tolerates budget variance.
-- **Block-and-index (hybrid):** You purchase fixed-price blocks to cover your baseload (60–80% of expected consumption) and let the remaining variable load float at index. This balances cost optimization with partial budget certainty. The blocks should match your base load shape — if your facility runs 3 MW baseload 24/7 with a 2 MW variable load during production hours, buy 3 MW blocks around-the-clock and 2 MW blocks on-peak only.
-- **Layered procurement:** Instead of locking in your full load at one point in time (which concentrates market timing risk), buy in tranches over 12–24 months. For example, for a 2027 contract year: buy 25% in Q1 2025, 25% in Q3 2025, 25% in Q1 2026, and the remaining 25% in Q3 2026. Dollar-cost averaging for energy. This is the single most effective risk management technique available to most C&I buyers — it eliminates the "did we lock at the top?" problem.
-- **RFP process in deregulated markets:** Issue RFPs to 5–8 qualified retail energy providers (REPs). Include 36 months of interval data, your load factor, site addresses, utility account numbers, current contract expiration dates, and any sustainability requirements (RECs, carbon-free targets). Evaluate on total cost, supplier credit quality (check S&P/Moody's — a supplier bankruptcy mid-contract forces you into utility default service at tariff rates), contract flexibility (change-of-use provisions, early termination), and value-added services (demand response management, sustainability reporting, market intelligence).
-
-### Demand Charge Management
-
-Demand charges are the most controllable cost component for facilities with operational flexibility:
-
-- **Peak identification:** Download 15-minute interval data from your utility or meter data management system. Identify the top 10 peak intervals per month. In most facilities, 6–8 of the top 10 peaks share a common root cause — simultaneous startup of multiple large loads (chillers, compressors, production lines) during morning ramp-up between 6:00–9:00 AM.
-- **Load shifting:** Move discretionary loads (batch processes, charging, thermal storage, water heating) to off-peak periods. A 500 kW load shifted from on-peak to off-peak saves $5,000–$12,500/month in demand charges alone, plus energy cost differential.
-- **Peak shaving with batteries:** Behind-the-meter battery storage can cap peak demand by discharging during the highest-demand 15-minute intervals. A 500 kW / 2 MWh battery system costs $800K–$1.2M installed. At $15/kW demand charge, shaving 500 kW saves $7,500/month ($90K/year). Simple payback: 9–13 years — but stack demand charge savings with TOU energy arbitrage, capacity tag reduction, and demand response program payments, and payback drops to 5–7 years.
-- **Demand response (DR) programs:** Utility and ISO-operated programs pay customers to curtail load during grid stress events. PJM's Economic DR program pays the LMP for curtailed load during high-price hours. ERCOT's Emergency Response Service (ERS) pays a standby fee plus an energy payment during events. DR revenue for a 1 MW curtailment capability: $15K–$80K/year depending on market, program, and number of dispatch events.
-- **Ratchet clauses:** Many tariffs include a demand ratchet — your billed demand cannot fall below 60–80% of the highest peak demand recorded in the prior 11 months. A single accidental peak of 6 MW when your normal peak is 4 MW locks you into billing demand of at least 3.6–4.8 MW for a year. Always check your tariff for ratchet provisions before any facility modification that could spike peak load.
-
-### Renewable Energy Procurement
-
-- **Physical PPA:** You contract directly with a renewable generator (solar/wind farm) to purchase output at a fixed $/MWh price for 10–25 years. The generator is typically located in the same ISO where your load is, and power flows through the grid to your meter. You receive both the energy and the associated RECs. Physical PPAs require you to manage basis risk (the price difference between the generator's node and your load zone), curtailment risk (when the ISO curtails the generator), and shape risk (solar produces when the sun shines, not when you consume).
-- **Virtual (financial) PPA (VPPA):** A contract-for-differences. You agree on a fixed strike price (e.g., $35/MWh). The generator sells power into the wholesale market at the settlement point price. If the market price is $45/MWh, the generator pays you $10/MWh. If the market price is $25/MWh, you pay the generator $10/MWh. You receive RECs to claim renewable attributes. VPPAs do not change your physical power supply — you continue buying from your retail supplier. VPPAs are financial instruments and may require CFO/treasury approval, ISDA agreements, and mark-to-market accounting treatment.
-- **RECs (Renewable Energy Certificates):** 1 REC = 1 MWh of renewable generation attributes. Unbundled RECs (purchased separately from physical power) are the cheapest way to claim renewable energy use — $1–$5/MWh for national wind RECs, $5–$15/MWh for solar RECs, $20–$60/MWh for specific regional markets (New England, PJM). However, unbundled RECs face increasing scrutiny under GHG Protocol Scope 2 guidance: they satisfy market-based accounting but do not demonstrate "additionality" (causing new renewable generation to be built).
-- **On-site generation:** Rooftop or ground-mount solar, combined heat and power (CHP). On-site solar PPA pricing: $0.04–$0.08/kWh depending on location, system size, and ITC eligibility. On-site generation reduces T&D exposure and can lower capacity tags. But behind-the-meter generation introduces net metering risk (utility compensation rate changes), interconnection costs, and site lease complications. Evaluate on-site vs. off-site based on total economic value, not just energy cost.
-
-### Load Profiling
-
-Understanding your facility's load shape is the foundation of every procurement and optimization decision:
-
-- **Base vs. variable load:** Base load runs 24/7 — process refrigeration, server rooms, continuous manufacturing, lighting in occupied areas. Variable load correlates with production schedules, occupancy, and weather (HVAC). A facility with a 0.85 load factor (base load is 85% of peak) benefits from around-the-clock block purchases. A facility with a 0.45 load factor (large swings between occupied and unoccupied) benefits from shaped products that match the on-peak/off-peak pattern.
-- **Load factor:** Average demand divided by peak demand. Load factor = (Total kWh) / (Peak kW × Hours in period). A high load factor (>0.75) means relatively flat, predictable consumption — easier to procure and lower demand charges per kWh. A low load factor (<0.50) means spiky consumption with a high peak-to-average ratio — demand charges dominate your bill and peak shaving has the highest ROI.
-- **Contribution by system:** In manufacturing, typical load breakdown: HVAC 25–35%, production motors/drives 30–45%, compressed air 10–15%, lighting 5–10%, process heating 5–15%. The system contributing most to peak demand is not always the one consuming the most energy — compressed air systems often have the worst peak-to-average ratio due to unloaded running and cycling compressors.
-
-### Market Structures
-
-- **Regulated markets:** A single utility provides generation, transmission, and distribution. Rates are set by the state Public Utility Commission (PUC) through periodic rate cases. You cannot choose your electricity supplier. Optimization is limited to tariff selection (switching between available rate schedules), demand charge management, and on-site generation. Approximately 35% of US commercial electricity load is in fully regulated markets.
-- **Deregulated markets:** Generation is competitive. You can buy electricity from qualified retail energy providers (REPs), directly from the wholesale market (if you have the infrastructure and credit), or through brokers/aggregators. ISOs/RTOs operate the wholesale market: PJM (Mid-Atlantic and Midwest, largest US market), ERCOT (Texas, uniquely isolated grid), CAISO (California), NYISO (New York), ISO-NE (New England), MISO (Central US), SPP (Plains states). Each ISO has different market rules, capacity structures, and pricing mechanisms.
-- **Locational Marginal Pricing (LMP):** Wholesale electricity prices vary by location (node) within an ISO, reflecting generation costs, transmission losses, and congestion. LMP = Energy Component + Congestion Component + Loss Component. A facility at a congested node pays more than one at an uncongested node. Congestion can add $5–$30/MWh to your delivered cost in constrained zones. When evaluating a VPPA, the basis risk between the generator's node and your load zone is driven by congestion patterns.
-
-### Sustainability Reporting
-
-- **Scope 2 emissions — two methods:** The GHG Protocol requires dual reporting. Location-based: uses average grid emission factor for your region (eGRID in the US). Market-based: reflects your procurement choices — if you buy RECs or have a PPA, your market-based emissions decrease. Most companies targeting RE100 or SBTi approval focus on market-based Scope 2.
-- **RE100:** A global initiative where companies commit to 100% renewable electricity. Requires annual reporting of progress. Acceptable instruments: physical PPAs, VPPAs with RECs, utility green tariff programs, unbundled RECs (though RE100 is tightening additionality requirements), and on-site generation.
-- **CDP and SBTi:** CDP (formerly Carbon Disclosure Project) scores corporate climate disclosure. Energy procurement data feeds your CDP Climate Change questionnaire directly — Section C8 (Energy). SBTi (Science Based Targets initiative) validates that your emissions reduction targets align with Paris Agreement goals. Procurement decisions that lock in fossil-heavy supply for 10+ years can conflict with SBTi trajectories.
-
-### Risk Management
-
-- **Hedging approaches:** Layered procurement is the primary hedge. Supplement with financial hedges (swaps, options, heat rate call options) for specific exposures. Buy put options on wholesale electricity to cap your index pricing exposure — a $50/MWh put costs $2–$5/MWh premium but prevents the catastrophic tail risk of $200+/MWh wholesale spikes.
-- **Budget certainty vs. market exposure:** The fundamental tradeoff. Fixed-price contracts provide certainty at a premium. Index contracts provide lower average cost at higher variance. Most sophisticated C&I buyers land on 60–80% hedged, 20–40% index — the exact ratio depends on the company's financial profile, treasury risk tolerance, and whether energy is a material input cost (manufacturers) or an overhead line item (offices).
-- **Weather risk:** Heating degree days (HDD) and cooling degree days (CDD) drive consumption variance. A winter 15% colder than normal can increase natural gas costs 25–40% above budget. Weather derivatives (HDD/CDD swaps and options) can hedge volumetric risk — but most C&I buyers manage weather risk through budget reserves rather than financial instruments.
-- **Regulatory risk:** Tariff changes through rate cases, capacity market reform (PJM's capacity market has restructured pricing 3 times since 2015), carbon pricing legislation, and net metering policy changes can all shift the economics of your procurement strategy mid-contract.
-
-## Decision Frameworks
-
-### Procurement Strategy Selection
-
-When choosing between fixed, index, and block-and-index for a contract renewal:
-
-1. **What is the company's tolerance for budget variance?** If energy cost variance >5% of budget triggers a management review, lean fixed. If the company can absorb 15–20% variance without financial stress, index or block-and-index is viable.
-2. **Where is the market in the price cycle?** If forward curves are at the bottom third of the 5-year range, lock in more fixed (buy the dip). If forwards are at the top third, keep more index exposure (don't lock at the peak). If uncertain, layer.
-3. **What is the contract tenor?** For 12-month terms, fixed vs. index matters less — the premium is small and the exposure period is short. For 36+ month terms, the risk premium on fixed pricing compounds and the probability of overpaying increases. Lean hybrid or layered for longer tenors.
-4. **What is the facility's load factor?** High load factor (>0.75): block-and-index works well — buy flat blocks around the clock. Low load factor (<0.50): shaped blocks or TOU-indexed products better match the load profile.
-
-### PPA Evaluation
-
-Before committing to a 10–25 year PPA, evaluate:
-
-1. **Does the project economics pencil?** Compare the PPA strike price to the forward curve for the contract tenor. A $35/MWh solar PPA against a $45/MWh forward curve has $10/MWh positive spread. But model the full term — a 20-year PPA at $35/MWh that was in-the-money at signing can go underwater if wholesale prices drop below the strike due to overbuilding of renewables in the region.
-2. **What is the basis risk?** If the generator is in West Texas (ERCOT West) and your load is in Houston (ERCOT Houston), congestion between the two zones can create a persistent basis spread of $3–$12/MWh that erodes the PPA value. Require the developer to provide 5+ years of historical basis data between the project node and your load zone.
-3. **What is the curtailment exposure?** ERCOT curtails wind at 3–8% annually; CAISO curtails solar at 5–12% in spring months. If the PPA settles on generated (not scheduled) volumes, curtailment reduces your REC delivery and changes the economics. Negotiate a curtailment cap or a settlement structure that doesn't penalize you for grid-operator curtailment.
-4. **What are the credit requirements?** Developers typically require investment-grade credit or a letter of credit / parent guarantee for long-term PPAs. A $50M notional VPPA may require a $5–$10M LC, tying up capital. Factor the LC cost into your PPA economics.
-
-### Demand Charge Mitigation ROI
-
-Evaluate demand charge reduction investments using total stacked value:
-
-1. Calculate current demand charges: Peak kW × demand rate × 12 months.
-2. Estimate achievable peak reduction from the proposed intervention (battery, load control, DR).
-3. Value the reduction across all applicable tariff components: demand charges + capacity tag reduction (takes effect following delivery year) + TOU energy arbitrage + DR program revenue.
-4. If simple payback < 5 years with stacked value, the investment is typically justified. If 5–8 years, it's marginal and depends on capital availability. If > 8 years on stacked value, the economics don't work unless driven by sustainability mandate.
-
-### Market Timing
-
-Never try to "call the bottom" on energy markets. Instead:
-
-- Monitor the forward curve relative to the 5-year historical range. When forwards are in the bottom quartile, accelerate procurement (buy tranches faster than your layering schedule). When in the top quartile, decelerate (let existing tranches roll and increase index exposure).
-- Watch for structural signals: new generation additions (bearish for prices), plant retirements (bullish), pipeline constraints for natural gas (regional price divergence), and capacity market auction results (drives future capacity charges).
-
-Use the procurement sequence above as the decision framework baseline and adapt it to your tariff structure, procurement calendar, and board-approved hedge limits.
-
-## Key Edge Cases
-
-These are situations where standard procurement playbooks produce poor outcomes. Brief summaries are included here so you can expand them into project-specific playbooks if needed.
-
-1. **ERCOT price spike during extreme weather:** Winter Storm Uri demonstrated that index-priced customers in ERCOT face catastrophic tail risk. A 5 MW facility on index pricing incurred $1.5M+ in a single week. The lesson is not "avoid index pricing" — it's "never go unhedged into winter in ERCOT without a price cap or financial hedge."
-
-2. **Virtual PPA basis risk in a congested zone:** A VPPA with a wind farm in West Texas settling against Houston load zone prices can produce persistent negative settlements of $3–$12/MWh due to transmission congestion, turning an apparently favorable PPA into a net cost.
-
-3. **Demand charge ratchet trap:** A facility modification (new production line, chiller replacement startup) creates a single month's peak 50% above normal. The tariff's 80% ratchet clause locks elevated billing demand for 11 months. A $200K annual cost increase from a single 15-minute interval.
-
-4. **Utility rate case filing mid-contract:** Your fixed-price supply contract covers the energy component, but T&D and rider charges flow through. A utility rate case adds $0.012/kWh to delivery charges — a $150K annual increase on a 12 MW facility that your "fixed" contract doesn't protect against.
-
-5. **Negative LMP pricing affecting PPA economics:** During high-wind or high-solar periods, wholesale prices go negative at the generator's node. Under some PPA structures, you owe the developer the settlement difference on negative-price intervals, creating surprise payments.
-
-6. **Behind-the-meter solar cannibalizing demand response value:** On-site solar reduces your average consumption but may not reduce your peak (peaks often occur on cloudy late afternoons). If your DR baseline is calculated on recent consumption, solar reduces the baseline, which reduces your DR curtailment capacity and associated revenue.
-
-7. **Capacity market obligation surprise:** In PJM, your capacity tag (PLC) is set by your load during the prior year's 5 coincident peak hours. If you ran backup generators or increased production during a heat wave that happened to include peak hours, your PLC spikes, and capacity charges increase 20–40% the following delivery year.
-
-8. **Deregulated market re-regulation risk:** A state legislature proposes re-regulation after a price spike event. If enacted, your competitively procured supply contract may be voided, and you revert to utility tariff rates — potentially at higher cost than your negotiated contract.
-
-## Communication Patterns
-
-### Supplier Negotiations
-
-Energy supplier negotiations are multi-year relationships. Calibrate tone:
-
-- **RFP issuance:** Professional, data-rich, competitive. Provide complete interval data and load profiles. Suppliers who can't model your load accurately will pad their margins. Transparency reduces risk premiums.
-- **Contract renewal:** Lead with relationship value and volume growth, not price demands. "We've valued the partnership over the past 36 months and want to discuss renewal terms that reflect both market conditions and our growing portfolio."
-- **Price challenges:** Reference specific market data. "ICE forward curves for 2027 are showing $42/MWh for AEP Dayton Hub. Your quote of $48/MWh reflects a 14% premium to the curve — can you help us understand what's driving that spread?"
-
-### Internal Stakeholders
-
-- **Finance/treasury:** Quantify decisions in terms of budget impact, variance, and risk. "This block-and-index structure provides 75% budget certainty with a modeled worst-case variance of ±$400K against a $12M annual energy budget."
-- **Sustainability:** Map procurement decisions to Scope 2 targets. "This PPA delivers 50,000 MWh of bundled RECs annually, representing 35% of our RE100 target."
-- **Operations:** Focus on operational requirements and constraints. "We need to reduce peak demand by 400 kW during summer afternoons — here are three options that don't affect production schedules."
-
-Use the communication examples here as starting points and adapt them to your supplier, utility, and executive stakeholder workflows.
-
-## Escalation Protocols
-
-| Trigger | Action | Timeline |
-|---|---|---|
-| Wholesale prices exceed 2× budget assumption for 5+ consecutive days | Notify finance, evaluate hedge position, consider emergency fixed-price procurement | Within 24 hours |
-| Supplier credit downgrade below investment grade | Review contract termination provisions, assess replacement supplier options | Within 48 hours |
-| Utility rate case filed with >10% proposed increase | Engage regulatory counsel, evaluate intervention filing | Within 1 week |
-| Demand peak exceeds ratchet threshold by >15% | Investigate root cause with operations, model billing impact, evaluate mitigation | Within 24 hours |
-| PPA developer misses REC delivery by >10% of contracted volume | Issue notice of default per contract, evaluate replacement REC procurement | Within 5 business days |
-| Capacity tag (PLC) increases >20% from prior year | Analyze coincident peak intervals, model capacity charge impact, develop peak response plan | Within 2 weeks |
-| Regulatory action threatens contract enforceability | Engage legal counsel, evaluate contract force majeure provisions | Within 48 hours |
-| Grid emergency / rolling blackouts affecting facilities | Activate emergency load curtailment, coordinate with operations, document for insurance | Immediate |
-
-### Escalation Chain
-
-Energy Analyst → Energy Procurement Manager (24 hours) → Director of Procurement (48 hours) → VP Finance/CFO (>$500K exposure or long-term commitment >5 years)
-
-## Performance Indicators
-
-Track monthly, review quarterly with finance and sustainability:
-
-| Metric | Target | Red Flag |
-|---|---|---|
-| Weighted average energy cost vs. budget | Within ±5% | >10% variance |
-| Procurement cost vs. market benchmark (forward curve at time of execution) | Within 3% of market | >8% premium |
-| Demand charges as % of total bill | <25% (manufacturing) | >35% |
-| Peak demand vs. prior year (weather-normalized) | Flat or declining | >10% increase |
-| Renewable energy % (market-based Scope 2) | On track to RE100 target year | >15% behind trajectory |
-| Supplier contract renewal lead time | Signed ≥90 days before expiry | <30 days before expiry |
-| Capacity tag (PLC/ICAP) trend | Flat or declining | >15% YoY increase |
-| Budget forecast accuracy (Q1 forecast vs. actuals) | Within ±7% | >12% miss |
-
-## Additional Resources
-
-- Maintain an internal hedge policy, approved counterparty list, and tariff-change calendar alongside this skill.
-- Keep facility-specific load shapes and utility contract metadata close to the planning workflow so recommendations stay grounded in real demand patterns.