refactor-dictionaries
Audit dictionary usage against the Dictionary Usage Doctrine.Produces a severity-grouped report with minimal refactor suggestions.
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.
| name | refactor-dictionaries |
|---|---|
| license | MIT |
| description | | |
| author | Jordan 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.md02_DEFINITIONS.md03_INVARIANTS.md04_SCOPE.md05_CHECKS.md06_OUTPUT.md