policyengine-review-patterns

The policyengine-review-patterns skill provides a comprehensive framework for conducting rigorous code reviews within the PolicyEngine ecosystem. Designed for engineers and policy modelers, it ensures that implementations of tax and benefit programs are accurate, performant, and maintainable. The skill emphasizes the 'WHY' behind code changes, requiring reviewers to distinguish between necessary state-specific logic and redundant wrapper variables that bloat the codebase without providing value. By enforcing consistent standards, this skill helps prevent common errors such as vectorization violations, hard-coded numeric values, and inadequate documentation of regulatory sources.

• Automated and manual checklist for identifying critical failures like vectorization bugs and invalid parameter sources.

• Patterns for detecting 'wrapper' variables that unnecessarily mirror federal variables without transformation.

• Standardized feedback templates to streamline communications between reviewers and contributors.

• Rigorous documentation requirements, including the verification of USC, CFR, and state-specific primary sources.

• Best practices for test structures, ensuring test cases use proper naming, correct periods, and documented calculation logic.

• Guidance on identifying hard-coded values that reduce model flexibility and scalability.

• Ensure all logic involving households or individuals is fully vectorized to support microsimulation performance.

• Verify that external links point to authoritative sources like administrative codes or statutes, not generic government websites.

• When reviewing state-specific implementations, confirm that state parameters are actually utilized and that formulas perform meaningful transformations.

• Use the provided review response templates to ensure constructive, actionable feedback is consistently delivered to PR authors.

• Pay close attention to unit tests to ensure they include proper numeric separators and accurate calculation annotations.

• Remember that PolicyEngine relies on a declarative structure; avoid manual control flow structures like if-elif-else statements for data-driven calculations, favoring instead the 'where' and 'select' methods.