--- name: do-oop-audit description: "Audit Python classes and OOP code for structural anti-patterns, naming inconsistencies, and data modeling issues. Use when reviewing class design, checking model health, validating object boundaries, or after refactoring. Also triggered by 'check my classes', 'review the data model', 'are there OOP problems', 'scan for design issues', 'lint class structure', 'audit models', 'validate OOP', or 'review object hierarchy'." allowed-tools: Read, Grep, Glob, Bash disable-model-invocation: true --- # OOP / Data Modeling Audit Scans Python class definitions for 14 structural anti-patterns covering field semantics, object boundaries, inheritance design, naming consistency, and coupling. Framework-agnostic: works with Django, SQLAlchemy, Pydantic, dataclasses, and vanilla Python. Produces a severity-grouped findings report and pauses for human review. ## What this skill does 1. Scans the target path for all `.py` files containing class definitions 2. Runs 14 semantic checks against each class and its relationships 3. Produces a structured findings report organized by severity (CRITICAL, WARNING, INFO) 4. Pauses for discussion — no auto-fix, findings only ## Invocation ``` /do-oop-audit [path] [--framework django|sqlalchemy|pydantic|auto] [--severity critical|warning|info] ``` - `path`: Directory or file to audit. Defaults to current project root. - `--framework`: Force a framework context. Default is `auto` (detect from imports and base classes). - `--severity`: Minimum severity to include in the report. Default: show all. ## Quick start 1. **Enumerate**: Find all `.py` files in the target path containing `class ` definitions 2. **Detect framework**: Identify Django / SQLAlchemy / Pydantic / dataclasses / vanilla (see Framework Detection below) 3. **Check**: Run each of the 14 audit checks against every class and cross-class relationship 4. **Filter**: If `--severity` is set, exclude findings below the threshold 5. **Report**: Present findings grouped by severity 6. **Pause**: Wait for human review — never modify source files --- ## Framework Detection Before running checks, detect the framework(s) in use. A project may use multiple frameworks. | Framework | Detection signals | |-----------|------------------| | **Django** | `from django.db import models`, base class `models.Model`, `class Meta:`, `ForeignKey`, `ManyToManyField` | | **SQLAlchemy** | `__tablename__`, `Column()`, `relationship()`, `declarative_base()`, `mapped_column()` | | **Pydantic** | `BaseModel` base class, `model_config`, `Field()`, `model_validator` | | **dataclasses** | `@dataclass` decorator, `field()` from `dataclasses` | | **Vanilla** | Plain `class` with `__init__`, no ORM/validation framework detected | Apply framework-specific heuristics when relevant: - Django: `ForeignKey` implies relationships; `Meta.ordering` hints at query patterns - SQLAlchemy: `relationship()` back-references reveal coupling - Pydantic: `Field(...)` validators reveal semantic types - dataclasses: `field(default_factory=...)` hints at mutable defaults --- ## Audit Checks ### 1. bool-should-be-timestamp Fields like `is_verified: bool` lose temporal information. A `verified_at: datetime | None` preserves *when* something happened, not just *whether* it happened, enabling time-based queries and debugging. **Severity**: WARNING ### 2. stringly-typed-field Fields storing structured data as raw strings: JSON blobs, comma-separated lists, encoded enums, URLs-as-str. These bypass validation and make the schema lie about its types. The fix is a proper type (dict, list, Enum, `HttpUrl`, etc.). **Severity**: WARNING ### 3. misnamed-field Field names that no longer match their actual usage after codebase evolution. Example: `description` now holds markdown content, `email` now holds a username. Misleading names cause bugs when new developers trust the name over the implementation. **Severity**: WARNING ### 4. derived-field-not-property Fields whose value is always computed from other fields and never set independently. These should be `@property` (or `@computed_field` in Pydantic) to avoid stale data and redundant storage. **Severity**: INFO ### 5. missing-semantic-type Raw `str` or `int` where a domain type (Email, URL, Money, PhoneNumber, etc.) would add clarity and validation. Using primitive types for domain concepts scatters validation logic across the codebase instead of centralizing it. **Severity**: INFO ### 6. god-object Classes with 15+ fields spanning multiple concerns. These resist testing, resist change, and accumulate merge conflicts. Should be decomposed into focused classes with relationships. **Severity**: CRITICAL ### 7. merge-candidates Two classes with nearly identical fields, always used together, or connected by a 1:1 relationship that adds no value. The extra indirection increases complexity without benefit. Suggest merging or flattening. **Severity**: WARNING ### 8. missing-base-class Multiple classes sharing 3+ identical fields or methods that should inherit from a common base or mixin. Duplicated structure means duplicated bugs and divergent evolution. **Severity**: WARNING ### 9. missing-junction-model Many-to-many relationships with extra data stored on one side instead of a proper junction/through model. The extra data becomes impossible to query independently and creates awkward update patterns. **Severity**: WARNING ### 10. deep-inheritance Inheritance trees 3+ levels deep where composition or mixins would be cleaner. Deep hierarchies create fragile coupling: changing a grandparent breaks grandchildren unpredictably. **Severity**: WARNING ### 11. empty-subclass Subclasses that add no fields or methods beyond what the parent provides. These should typically be a field or enum value on the parent instead. The type system is being abused for data that belongs in a column. **Severity**: INFO ### 12. inconsistent-naming The same concept named differently across classes. Examples: `created_at` vs `date_created` vs `creation_date`, or `user_id` vs `owner_id` for the same FK. Inconsistency forces developers to memorize arbitrary conventions per class. **Severity**: WARNING ### 13. circular-reference Classes that import each other, creating dependency cycles. These resist refactoring, cause import-order bugs, and make the dependency graph unpredictable. Break with lazy imports, protocols, or architectural layering. **Severity**: CRITICAL ### 14. over-coupled-class A class that directly references 5+ other domain classes (via fields, type hints, or method signatures). High fan-out means changes ripple unpredictably — this class is a change amplifier that should be simplified or mediated. **Severity**: WARNING --- ## Output Format Present findings using this structure. Adapt the content to actual findings. ``` ## OOP Audit Report ### Items Scanned - ClassName (N fields, M methods) — path/to/file.py [Framework: Django | SQLAlchemy | Pydantic | dataclass | vanilla] ### Findings #### CRITICAL - [check-name] ClassName: specific finding with evidence and recommendation #### WARNING - [check-name] ClassName: specific finding with evidence and recommendation #### INFO - [check-name] ClassName: specific finding with evidence and recommendation ### Summary PASS: N WARN: N FAIL: N ``` ### Example: E-commerce models ``` ## OOP Audit Report ### Items Scanned - User (12 fields, 3 methods) — models/user.py [Django] - Order (23 fields, 8 methods) — models/order.py [Django] - OrderItem (6 fields, 2 methods) — models/order.py [Django] - ShippingAddress (9 fields) — models/shipping.py [Django] - BillingAddress (8 fields) — models/shipping.py [Django] ### Findings #### CRITICAL - [god-object] Order: 23 fields spanning order details, shipping, billing, and payment status — split into Order + OrderShipping + OrderBilling - [circular-reference] models/user.py <-> models/order.py: User imports Order for `recent_orders()`, Order imports User for `placed_by` — break with lazy import or move `recent_orders` to a service #### WARNING - [bool-should-be-timestamp] User.is_verified: boolean loses when verification happened — use `verified_at: datetime | None` - [bool-should-be-timestamp] Order.is_shipped: same pattern — use `shipped_at: datetime | None` - [inconsistent-naming] created_at vs date_created: User uses `created_at`, Order uses `date_created` — standardize to `created_at` - [merge-candidates] ShippingAddress + BillingAddress: 7 of 9 fields identical, always used together — merge into Address with `address_type` enum - [missing-base-class] User, Order, ShippingAddress: all define `created_at`, `updated_at`, `is_active` — extract TimestampedMixin - [stringly-typed-field] Order.payment_meta: stores JSON as TextField — use JSONField or a structured PaymentInfo model #### INFO - [derived-field-not-property] Order.total_price: always computed as sum of OrderItem prices — should be @property or @cached_property - [missing-semantic-type] User.email: raw CharField — use EmailField for built-in validation ### Summary PASS: 60 WARN: 6 FAIL: 2 ``` ### Example: Pydantic API schemas ``` ## OOP Audit Report ### Items Scanned - UserCreate (5 fields) — schemas/user.py [Pydantic] - UserResponse (8 fields) — schemas/user.py [Pydantic] - APIConfig (18 fields, 2 validators) — config/settings.py [Pydantic] ### Findings #### CRITICAL - [god-object] APIConfig: 18 fields covering database, auth, email, storage, and feature flags — split into DatabaseConfig, AuthConfig, EmailConfig, etc. #### WARNING - [missing-base-class] UserCreate, UserResponse: share 5 identical fields — extract UserBase #### INFO - [empty-subclass] UserResponse: only adds `id` and `created_at` to UserCreate fields — consider a single User model with optional fields ### Summary PASS: 38 WARN: 1 FAIL: 1 ``` --- ## After the Audit Findings only. The skill never modifies source files. Next steps are decided by the human: - Fix critical findings first (god objects, circular references) - Batch warning-level fixes into a refactoring PR - Track info-level findings as tech debt for future sprints - Re-run the audit after fixes to verify resolution ## Version history - v1.0.0 (2026-03-24): Initial — 14 checks, framework detection, severity filtering