refactor-dictionaries

Audit dictionary usage against the Dictionary Usage Doctrine.Produces a severity-grouped report with minimal refactor suggestions.

⭐5stars🔀0forks📁View on GitHub🕐Updated Jan 10, 2026

When & Why to Use This Skill

The refactor-dictionaries skill is a specialized static analysis tool designed to audit Python dictionary usage against the 'Dictionary Usage Doctrine.' It focuses on improving code maintainability and type safety by identifying improper dynamic dictionary patterns, especially within public APIs and across module boundaries. By providing severity-grouped reports and actionable refactoring suggestions, it helps developers transition from loose dictionaries to structured types like Dataclasses and TypedDicts.

Use Cases

  • Legacy Code Refactoring: Scan existing codebases to identify where unstructured dictionaries are used to store complex data, providing a roadmap to migrate toward type-safe Dataclasses.
  • API Design Audit: Review public-facing interfaces to ensure they don't expose dynamic dictionaries, which often lead to runtime errors and poor documentation for end-users.
  • Type Safety Enforcement: Detect 'dictionary-ly typed' code where data structures cross module boundaries, ensuring that type-checking invariants are maintained throughout the application architecture.
  • Pre-merge Quality Checks: Integrate into the code review process to automatically flag violations of dictionary usage best practices before they reach production.
namerefactor-dictionaries
licenseMIT
description|
authorJordan Godau

Instructions

Read all references in references/ before using this skill.

Signals

  • Reviewing public APIs for improper dict usage
  • Detecting dynamic-vs-known structure violations
  • Dictionaries crossing module boundaries or encoding state
  • The user asks to "audit dictionaries" or "check dict usage"

References

Directory: references/

  • 01_GOAL.md
  • 02_DEFINITIONS.md
  • 03_INVARIANTS.md
  • 04_SCOPE.md
  • 05_CHECKS.md
  • 06_OUTPUT.md