pech

Runs L2 Budget Boundary Detection after each ledger write: increments per-scope counters, compares against ceilings in state/budgets.json, emits pech.budget.threshold.crossed on first crossing of each threshold within each scope-window. Use when: a PostToolUse hook fires and cost-tracker has already written the ledger row. Do not use for forecasting (see forecast-cost) or anomaly detection (see detect-anomaly).

Writes a single ledger row for the most recent tool-use call: reads the API response's usage field (authoritative), looks up the model rate in shared/rate-card.json, applies prompt-cache modifiers (1.25× write, 0.1× read), computes billed cost, and appends to plugins/cost-tracker/state/ledger-YYYY-MM.jsonl. Use when: a PostToolUse hook fires for any tool and attribution metadata is available via ENCHANTED_ATTRIBUTION env. Do not use for forecasting (see /pech-forecast → forecast-cost) or for anomaly detection (see budget-watcher/detect-anomaly).

Updates shared/rate-card.json with a new per-model rate table. Validates the proposed update against the existing schema, diffs prices against the current card, and produces a commit-ready diff for human review. Use when: CI nightly job detects a pricing change on Anthropic's published rate page, or when the developer runs /refresh-rate-card after verifying a price change. Do not use at runtime during a Claude Code session — this skill runs in CI or at developer invocation, never inside the observation hot path.

Token-bucket advisory rate limiter per skill+session. Surfaces runaway tool-call loops in real time before pech/budget-watcher reports them post-hoc. Auto-fires on PreToolUse. Configurable per-skill limits via state/buckets.json. Do not use for cost reporting (see budget-watcher) or for blocking installs (see package-gate).

OPT-IN BLOCKING token-bucket rate limiter. Pairs with pech-rate-limiter (advisory). When state/rate-policy.json sets enabled:true, this shield blocks (exits 2) any tool call once the active (session, skill) bucket is empty. Reads buckets from rate-limiter's state/buckets.json when present; gracefully degrades when absent. Use when the developer asks why a tool call was rate-blocked, wants to enable or tune the rate policy, or reviews a stderr "rate-shield (BLOCKED)" message. Default disabled. Do not use for advisory-only velocity signals (see rate-limiter) or for cost reporting (see budget-watcher).

Updates per-developer cost-pattern accumulator in state/learnings.json with the current session's observations. Rolls μ and σ per (skill, session_type, model) axis using a slow exponential update (α = 0.05) so one noisy session doesn't skew learned patterns. Exports a cross-plugin-readable snapshot to shared/learnings.json. Use when: PreCompact hook fires (end-of-session or compaction trigger). Do not use during an active session — runtime invocation mid-session would distort the pattern.

Runs L3 Z-Score Cost Anomaly detection against the last 30 ledger rows matching the same attribution tuple (plugin, sub_plugin, skill, agent_tier, model). Fires pech.anomaly.detected when |z| > 3, for both spikes and drops. Use when: a PostToolUse hook fires and the ledger row is in place. Do not use when the attribution tuple has fewer than 30 historical matches — emit insufficient_data instead of false-positive anomaly.

Formats Pech state into human-readable terminal output (or JSON) for /pech-cost and /pech-attribute. Reads ledger + session snapshot + budget-watcher counters; renders grouped tables with percentages; flags orphan attribution prominently. Use when: /pech-cost or /pech-attribute slash command fires. Do not use for forecasting (see forecast-cost) or PDF generation (see generate-report).

Aggregates state across all 5 Pech sub-plugins and renders a dark-themed single-page PDF cost audit. Invokes anomaly-narrator agent (Opus) once per anomaly for human-readable diagnoses; invokes forecaster agent (Sonnet) for the forecast block. Use when: /pech-report slash command fires. Do not use for live session display (see cost-display) — report generation is a heavy operation costing ~$0.04 + $0.005 per anomaly.

Computes L1 Exponential Smoothing forecast over the current session's ledger to project end-of-session, end-of-day, and end-of-month spend with ±2σ confidence bands. Use when: /pech-forecast slash command fires, or an anomaly in L3 requires the current trajectory for narrative context. Do not use for raw totals (see /pech-cost → cost-display) or for threshold checks (see budget-watcher).

Reads state/learnings.json and returns the historical μ/σ/p50/p95 for a requested attribution key (plugin:skill:agent_tier). Used by L3 Z-Score Cost Anomaly as a historical prior when the current session has fewer than 30 matching observations. Use when: detect-anomaly needs a prior and in-session N is insufficient. Do not use to compute costs or fire events — this skill is purely a read over the accumulator.

Loads shared/rate-card.json at SessionStart, validates the schema via the rate-card-validator agent (Haiku), checks staleness, and emits warning events if the rate card is > 60 days old. Use when: a SessionStart hook fires. Do not use for computing per-call costs (see observe-call) — this skill only loads and validates the card; it does not perform cost math.