catalyst-cooperative/pudl-dev

PUDL Developer Guide

Use this skill for broad PUDL development tasks where code behavior, metadata, and data products are tightly coupled.

Trigger phrases

• "help me contribute to PUDL"
• "how do I run PUDL locally"
• "which commands should I run for this PUDL change"
• "where is the metadata for this table"
• "how do I validate this data change"
• "how does this PUDL table relate to source docs"
• "what docs should I update for this PUDL PR"
• "how do I release or operate PUDL builds"

How to use this skill

1. Identify the primary workflow from the reference index below.
2. Read the relevant reference file(s) before answering.
3. Prefer repository-native commands (pixi run ...) and existing conventions.
4. For specialized workflows, also use related skills:
   • pytest
   • dbt
   • code-quality
   • alembic
   • pudl (data-access focused)
   • dagster-expert

Shared data context

Data/metadata/source/methodology guidance is centralized in the pudl skill. Use the linked "Shared" entries in the reference index below rather than maintaining duplicates in pudl-dev.

Canonical-source policy

The files in this skill are distilled for coding agents. Canonical project guidance remains in PUDL documentation and source code. Each reference points to canonical docs.

Reference index

• Contributor Workflow - PR flow, contribution norms, communication, and planning.
• Dev Setup and ETL - environment setup, running ETL, datastore context, and local execution.
• Testing and Validation - pytest scopes, dbt validation workflow, and quality checks.
• Metadata and Schema - metadata source-of-truth files, dbt schema coupling, and migrations.
• Dagster and Assets - Dagster-oriented project structure and asset orchestration context.
• Docs Generation Traceability - map generated artifacts to build hooks, templates, and metadata classes.
• Releases and Operations - release workflow, nightly build context, and operational docs.
• ID Mapping and Entity Linkages - historical and practical guidance for cross-dataset entity matching.