@smicolon/ai-kit 0.1.0 → 0.2.0

package/packs/django/skills/migration-safety-checker/SKILL.md

@@ -0,0 +1,375 @@
+---
+name: migration-safety-checker
+description: This skill should be used when the user asks to "create a migration", "run makemigrations", "modify a model field", "rename a column", or mentions "schema change", "alter table", "database migration". Validates migrations are production-safe.
+---
+
+# Migration Safety Checker
+
+Validates Django migrations are production-safe before they cause data loss.
+
+## Activation Triggers
+
+This skill activates when:
+- Running `makemigrations`
+- Modifying model fields
+- Mentioning "migration", "schema", "alter table"
+- Adding/removing/renaming fields
+- Changing field types
+- Creating or modifying migration files
+
+## Safety Requirements
+
+All migrations MUST be:
+- ✅ **Reversible** - Can roll back safely
+- ✅ **No data loss** - Preserve existing data
+- ✅ **Tested** - Run on staging first
+- ✅ **Safe for production** - No downtime operations
+- ✅ **Documented** - Explain what changes and why
+
+## High-Risk Operations
+
+These operations require special attention:
+
+### 🔴 CRITICAL RISK - Data Loss Possible
+
+1. **Dropping columns** without data migration
+2. **Renaming fields** without data migration
+3. **Changing field types** (data conversion issues)
+4. **Adding non-nullable fields** without default
+5. **Removing tables** with data
+
+### 🟡 MEDIUM RISK - Requires Careful Planning
+
+1. **Adding indexes** on large tables (use `CONCURRENTLY`)
+2. **Adding unique constraints** (check for duplicates first)
+3. **Changing `max_length`** (data truncation risk)
+
+### 🟢 LOW RISK - Generally Safe
+
+1. **Adding nullable fields**
+2. **Adding fields with defaults**
+3. **Creating new tables**
+4. **Adding non-unique indexes**
+
+## Validation Process
+
+### Step 1: Analyze Migration File
+
+When migration is created:
+
+```python
+# Generated migration
+class Migration(migrations.Migration):
+    operations = [
+        migrations.RemoveField(
+            model_name='user',
+            name='old_email',  # 🔴 DATA LOSS RISK!
+        ),
+    ]
+```
+
+### Step 2: Identify Risks
+
+Detect:
+- Operation type: `RemoveField`
+- Field: `old_email`
+- **Risk:** 🔴 CRITICAL - Dropping column loses data!
+
+### Step 3: Block Unsafe Migration
+
+> **⛔ UNSAFE MIGRATION DETECTED**
+>
+> **Operation:** `RemoveField(model_name='user', name='old_email')`
+>
+> **Risk:** 🔴 CRITICAL - Data loss!
+>
+> **Problem:**
+> - Drops `old_email` column immediately
+> - All existing email data will be PERMANENTLY LOST
+> - Cannot be rolled back after data is gone
+>
+> **Safe Approach:**
+> Use 3-step migration pattern:
+> 1. Data migration: Archive `old_email` data
+> 2. Wait for deployment
+> 3. Drop column in separate migration
+>
+> Should I generate the safe migration sequence?
+
+### Step 4: Generate Safe Migration
+
+If user approves, create:
+
+```python
+# Migration 1: Archive data
+class Migration(migrations.Migration):
+    dependencies = [('users', '0001_initial')]
+
+    operations = [
+        migrations.RunPython(archive_old_emails, reverse_code=restore_old_emails),
+    ]
+
+def archive_old_emails(apps, schema_editor):
+    """Archive old_email data before dropping."""
+    User = apps.get_model('users', 'User')
+    EmailArchive = apps.get_model('users', 'EmailArchive')
+
+    for user in User.objects.all():
+        if user.old_email:
+            EmailArchive.objects.create(
+                user_id=user.id,
+                email=user.old_email
+            )
+
+def restore_old_emails(apps, schema_editor):
+    """Restore old_email data on rollback."""
+    User = apps.get_model('users', 'User')
+    EmailArchive = apps.get_model('users', 'EmailArchive')
+
+    for archive in EmailArchive.objects.all():
+        User.objects.filter(id=archive.user_id).update(
+            old_email=archive.email
+        )
+
+# Migration 2: Drop column (run after deployment)
+class Migration(migrations.Migration):
+    dependencies = [('users', '0002_archive_emails')]
+
+    operations = [
+        migrations.RemoveField(
+            model_name='user',
+            name='old_email',
+        ),
+    ]
+```
+
+## Safe Migration Patterns
+
+### Pattern 1: Renaming Field (3 Steps)
+
+**❌ UNSAFE:**
+```python
+operations = [
+    migrations.RenameField('user', 'email', 'email_address'),  # ❌ Risky!
+]
+```
+
+**✅ SAFE (3-Step):**
+```python
+# Step 1: Add new field
+operations = [
+    migrations.AddField('user', 'email_address',
+                       models.EmailField(null=True))
+]
+
+# Step 2: Data migration (copy old → new)
+operations = [
+    migrations.RunPython(copy_email_to_email_address)
+]
+
+# Step 3: Drop old field (separate deployment)
+operations = [
+    migrations.RemoveField('user', 'email')
+]
+```
+
+### Pattern 2: Changing Field Type (3 Steps)
+
+**❌ UNSAFE:**
+```python
+operations = [
+    migrations.AlterField('product', 'price',
+                         models.DecimalField(max_digits=10, decimal_places=2))
+]
+```
+
+**✅ SAFE:**
+```python
+# Step 1: Add new field with new type
+operations = [
+    migrations.AddField('product', 'price_decimal',
+                       models.DecimalField(max_digits=10, decimal_places=2, null=True))
+]
+
+# Step 2: Data migration (convert & copy)
+operations = [
+    migrations.RunPython(convert_price_to_decimal)
+]
+
+# Step 3: Drop old field, rename new field
+operations = [
+    migrations.RemoveField('product', 'price'),
+    migrations.RenameField('product', 'price_decimal', 'price')
+]
+```
+
+### Pattern 3: Adding Non-Nullable Field (2 Steps)
+
+**❌ UNSAFE:**
+```python
+operations = [
+    migrations.AddField('user', 'organization',
+                       models.ForeignKey('Organization'))  # ❌ No default!
+]
+```
+
+**✅ SAFE:**
+```python
+# Step 1: Add as nullable
+operations = [
+    migrations.AddField('user', 'organization',
+                       models.ForeignKey('Organization', null=True))
+]
+
+# Step 2: Populate + make non-nullable
+operations = [
+    migrations.RunPython(assign_default_organizations),
+    migrations.AlterField('user', 'organization',
+                         models.ForeignKey('Organization', null=False))
+]
+```
+
+### Pattern 4: Adding Unique Constraint (Check First)
+
+**❌ UNSAFE:**
+```python
+operations = [
+    migrations.AlterField('user', 'email',
+                         models.EmailField(unique=True))  # ❌ Fails if duplicates!
+]
+```
+
+**✅ SAFE:**
+```python
+# Step 1: Check for duplicates
+operations = [
+    migrations.RunPython(check_and_fix_duplicate_emails)
+]
+
+# Step 2: Add unique constraint
+operations = [
+    migrations.AlterField('user', 'email',
+                         models.EmailField(unique=True))
+]
+```
+
+## Production-Safe Practices
+
+### Use CONCURRENT Index Creation
+
+```python
+from django.db import migrations
+from django.contrib.postgres.operations import AddIndexConcurrently
+
+class Migration(migrations.Migration):
+    atomic = False  # Required for CONCURRENT operations
+
+    operations = [
+        AddIndexConcurrently(
+            model_name='user',
+            index=models.Index(fields=['email'], name='user_email_idx')
+        )
+    ]
+```
+
+### Data Migration Template
+
+```python
+def forward_migration(apps, schema_editor):
+    """
+    Safe data migration with batching.
+    """
+    Model = apps.get_model('app', 'Model')
+    batch_size = 1000
+
+    total = Model.objects.count()
+    for offset in range(0, total, batch_size):
+        batch = Model.objects.all()[offset:offset + batch_size]
+        for obj in batch:
+            # Transform data
+            obj.new_field = transform(obj.old_field)
+            obj.save(update_fields=['new_field'])
+
+def reverse_migration(apps, schema_editor):
+    """
+    Reverse the migration.
+    """
+    Model = apps.get_model('app', 'Model')
+    Model.objects.all().update(new_field=None)
+
+class Migration(migrations.Migration):
+    operations = [
+        migrations.RunPython(forward_migration, reverse_migration)
+    ]
+```
+
+## Migration Testing Checklist
+
+Before applying migration:
+
+- ✅ Run on copy of production database
+- ✅ Verify data integrity after migration
+- ✅ Test rollback works
+- ✅ Check migration duration (< 5 minutes ideal)
+- ✅ Review SQL with `sqlmigrate`
+- ✅ Confirm no downtime required
+- ✅ Have rollback plan ready
+
+## Validation Commands
+
+Suggest running:
+
+```bash
+# Review SQL before applying
+python manage.py sqlmigrate users 0002
+
+# Check for issues
+python manage.py makemigrations --check
+
+# Dry run
+python manage.py migrate --plan
+
+# Apply to staging first
+python manage.py migrate --database=staging
+```
+
+## Integration with CI/CD
+
+```yaml
+# .github/workflows/migrations.yml
+- name: Check migrations safety
+  run: |
+    python manage.py makemigrations --check --dry-run --no-input
+    python manage.py migrate --plan
+```
+
+## Success Criteria
+
+✅ No data loss migrations
+✅ All migrations tested on staging
+✅ Rollback plan exists
+✅ Large table migrations use CONCURRENT
+✅ Data migrations properly batched
+✅ Reversible migrations
+
+## Behavior
+
+**Proactive enforcement:**
+- Analyze migrations without being asked
+- Block unsafe migrations immediately
+- Suggest safe 3-step patterns
+- Generate data migration code
+- Explain WHY the migration is risky
+
+**Never:**
+- Allow data loss migrations
+- Let users skip safety checks
+- Apply migrations without review
+- Just warn without blocking unsafe operations
+
+**When migration is unsafe:**
+- Stop the process
+- Explain the risk
+- Provide safe alternative
+- Generate corrected migration code
+- User must acknowledge before proceeding

package/packs/django/skills/model-entity-validator/SKILL.md

@@ -0,0 +1,298 @@
+---
+name: model-entity-validator
+description: This skill should be used when the user asks to "create a model", "add a Django model", "create database table", "add entity", "define schema", or when writing class definitions inheriting from models.Model. Validates BaseModel inheritance pattern.
+---
+
+# Model/Entity Validator
+
+Enforces Smicolon's BaseModel inheritance pattern for all Django models.
+
+## Activation Triggers
+
+This skill activates when:
+- Creating new model files
+- Modifying existing models
+- Mentioning "model", "database", "schema", "table"
+- Writing class inheriting from `models.Model`
+- Running migrations
+- Discussing data structure
+
+## Core Principle: BaseModel Inheritance
+
+**NEVER repeat UUID/timestamp fields.** All models inherit from BaseModel.
+
+```python
+# ❌ WRONG - Repeating fields
+class User(models.Model):
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+    is_deleted = models.BooleanField(default=False)
+    email = models.EmailField()
+
+# ✅ CORRECT - Inherit from BaseModel
+import core.models as _core_models
+
+class User(_core_models.BaseModel):
+    email = models.EmailField(unique=True)
+```
+
+## Validation Process
+
+### Step 1: Check if BaseModel Exists
+
+Before any action, check if the project has a BaseModel:
+
+```python
+# Search for BaseModel in (in order):
+# 1. core/models.py
+# 2. shared/models.py
+# 3. common/models.py
+# 4. {app}/base.py
+```
+
+**If BaseModel found:** Suggest inheritance (Step 2a)
+**If BaseModel NOT found:** Create BaseModel first (Step 2b)
+
+### Step 2a: BaseModel Exists - Suggest Inheritance
+
+When seeing:
+```python
+class Product(models.Model):
+    name = models.CharField(max_length=255)
+```
+
+Fix to:
+```python
+import core.models as _core_models
+
+class Product(_core_models.BaseModel):
+    """Product model - inherits id, timestamps, soft delete from BaseModel."""
+
+    name = models.CharField(max_length=255)
+    price = models.DecimalField(max_digits=10, decimal_places=2)
+
+    class Meta:
+        db_table = 'products'
+```
+
+### Step 2b: BaseModel NOT Found - Create It First
+
+If no BaseModel exists, create it:
+
+```python
+# core/models.py
+import uuid
+from django.db import models
+
+class BaseModel(models.Model):
+    """
+    Abstract base model providing:
+    - UUID primary key
+    - Automatic timestamps (created_at, updated_at)
+    - Soft delete support (is_deleted)
+
+    All models MUST inherit from this class.
+    """
+
+    id = models.UUIDField(
+        primary_key=True,
+        default=uuid.uuid4,
+        editable=False
+    )
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+    is_deleted = models.BooleanField(default=False)
+
+    class Meta:
+        abstract = True
+        ordering = ['-created_at']
+
+    def soft_delete(self) -> None:
+        """Soft delete the record."""
+        self.is_deleted = True
+        self.save(update_fields=['is_deleted', 'updated_at'])
+
+    def restore(self) -> None:
+        """Restore a soft-deleted record."""
+        self.is_deleted = False
+        self.save(update_fields=['is_deleted', 'updated_at'])
+
+
+class ActiveManager(models.Manager):
+    """Manager that excludes soft-deleted records."""
+
+    def get_queryset(self):
+        return super().get_queryset().filter(is_deleted=False)
+```
+
+Report to developer:
+> **BaseModel Created**
+>
+> Created `core/models.py` with BaseModel. All models should now inherit from it:
+> ```python
+> import core.models as _core_models
+>
+> class YourModel(_core_models.BaseModel):
+>     # Your fields here - DO NOT add id, created_at, updated_at, is_deleted
+> ```
+
+### Step 3: Detect Duplicate Fields
+
+If seeing a model with explicit id/timestamp fields that inherits from BaseModel:
+
+```python
+# ❌ WRONG - Duplicate fields
+class User(_core_models.BaseModel):
+    id = models.UUIDField(...)  # Already in BaseModel!
+    created_at = models.DateTimeField(...)  # Already in BaseModel!
+    email = models.EmailField()
+```
+
+Remove them:
+```python
+# ✅ CORRECT - Only custom fields
+class User(_core_models.BaseModel):
+    email = models.EmailField(unique=True)
+```
+
+### Step 4: Validate Indexes
+
+Check if appropriate indexes exist:
+
+```python
+class Product(_core_models.BaseModel):
+    name = models.CharField(max_length=255)
+    sku = models.CharField(max_length=100, unique=True)
+
+    class Meta:
+        db_table = 'products'
+        indexes = [
+            models.Index(fields=['sku']),  # Suggest for unique lookups
+            models.Index(fields=['name']),  # Suggest for search
+        ]
+```
+
+## Complete Model Examples
+
+### Standard Model
+
+```python
+# products/models.py
+from django.db import models
+import core.models as _core_models
+
+class Product(_core_models.BaseModel):
+    """Product model."""
+
+    name = models.CharField(max_length=255)
+    description = models.TextField(blank=True)
+    price = models.DecimalField(max_digits=10, decimal_places=2)
+    sku = models.CharField(max_length=100, unique=True, db_index=True)
+    is_active = models.BooleanField(default=True)
+
+    class Meta:
+        db_table = 'products'
+        verbose_name = 'Product'
+        verbose_name_plural = 'Products'
+        indexes = [
+            models.Index(fields=['name']),
+            models.Index(fields=['is_active', 'is_deleted']),
+        ]
+
+    def __str__(self):
+        return self.name
+```
+
+### User Model (with AbstractUser)
+
+```python
+# users/models.py
+import uuid
+from django.db import models
+from django.contrib.auth.models import AbstractUser
+
+class User(AbstractUser):
+    """
+    Custom User model with UUID and timestamps.
+
+    Note: For User, override AbstractUser directly since it has its own
+    ID handling. Add the standard fields manually.
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+    is_deleted = models.BooleanField(default=False)
+
+    email = models.EmailField(unique=True)
+
+    USERNAME_FIELD = 'email'
+    REQUIRED_FIELDS = []
+
+    class Meta:
+        db_table = 'users'
+```
+
+### Through Model (Many-to-Many)
+
+```python
+# users/models.py
+import core.models as _core_models
+
+class UserOrganization(_core_models.BaseModel):
+    """Through model for user-organization relationship."""
+
+    user = models.ForeignKey('User', on_delete=models.CASCADE)
+    organization = models.ForeignKey('Organization', on_delete=models.CASCADE)
+    role = models.CharField(max_length=50)
+
+    class Meta:
+        db_table = 'user_organizations'
+        unique_together = [['user', 'organization']]
+```
+
+## Custom Managers
+
+BaseModel provides soft delete. Add a custom manager for convenience:
+
+```python
+import core.models as _core_models
+
+class Product(_core_models.BaseModel):
+    name = models.CharField(max_length=255)
+
+    objects = models.Manager()  # All records
+    active = _core_models.ActiveManager()  # Excludes soft-deleted
+
+# Usage
+Product.active.all()  # Only non-deleted
+Product.objects.all()  # All including deleted
+```
+
+## Validation Checklist
+
+When reviewing a model, check:
+
+1. ✅ Inherits from `BaseModel` (or has explicit required fields for special cases)
+2. ✅ Does NOT duplicate fields from BaseModel
+3. ✅ Uses absolute import: `import core.models as _core_models`
+4. ✅ Has appropriate `db_table` name (singular or plural, snake_case)
+5. ✅ Has indexes on frequently queried fields
+6. ✅ Foreign keys have `on_delete` specified
+7. ✅ Has docstring explaining the model
+8. ✅ Has `__str__` method for admin display
+
+## Behavior
+
+**Proactive enforcement:**
+- Check if BaseModel exists FIRST
+- Suggest inheritance instead of field duplication
+- Remove duplicate fields automatically
+- Create BaseModel if missing
+- Explain WHY inheritance is better
+
+**Never:**
+- Add duplicate id/timestamp fields to models
+- Let developers repeat base fields
+- Ignore existing BaseModel in the project