@mrciphersmith/keryx 0.3.5 → 0.3.6

package/src/gdskills/bundled/stacks/django/skills/django-code-review/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: django-code-review
+description: "Use when reviewing Django changes for correctness and injection-class risks -- checks N+1 queries missing select_related/prefetch_related, mark_safe/|safe applied to user-traceable data, raw()/extra() built by string interpolation, @csrf_exempt on a session-authenticated view, missing/hand-edited migrations, and settings.py misconfiguration (DEBUG, SECRET_KEY, ALLOWED_HOSTS). Read-only: reports findings, does not edit code."
+triggers:
+  - "review this django diff"
+  - "check this django change before merging"
+  - "review django code changes"
+  - "audit this django view for csrf or xss gaps"
+  - "check this django model change for N+1"
+  - "review this django migration"
+metadata:
+  origin: authored
+  category: review
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# Django code review
+
+Review a set of Django changes for correctness, query-performance, and
+security risk specific to the framework. Read-only: this skill reports
+findings, it never edits code. Scoped to Django-specific defects; for
+generic Python defects (mutable defaults, bare `except`, resource leaks) use
+`python-code-review`, for a language-agnostic security sweep use
+`review-security-code`, for fixing what this skill finds use
+`django-build-fix` (checker failures) or hand the report to the author.
+
+## Workflow
+
+### Step 1: Scope the review
+
+1. Identify the changed Django files (`git diff` against the review base,
+   or the files the requester names) — models, views, forms/serializers,
+   templates, migrations, settings.
+2. Read `settings.py` for `DEBUG`, `ALLOWED_HOSTS`, and whether DRF/
+   `pytest-django` are installed, so findings can be judged against the
+   project's actual configuration.
+3. Read enough of the surrounding view/template/serializer to judge whether
+   a flagged pattern is a real bug in context (e.g. does the template
+   actually dereference the relation this queryset didn't eager-load).
+
+### Step 2: Check each changed file against these categories
+
+**Query performance (N+1)**
+- A queryset iterated in a view, template, or serializer that dereferences
+  a `ForeignKey`/`OneToOneField` per row with no `select_related`, or a
+  many-valued relation per row with no `prefetch_related`.
+- A loop calling `.save()`/`.delete()` per row where `bulk_create`/
+  `bulk_update`/`.update()`/`.delete()` on the queryset would collapse it to
+  one (or a few) queries.
+
+**Cross-site scripting**
+- `mark_safe()`/the `|safe` template filter/`format_html()`'s raw-string
+  form applied to a value that traces back to user input (a form field, a
+  query parameter, stored user-submitted content) — Django's own
+  auto-escaping is the correct default; only application-controlled markup
+  should ever bypass it.
+
+**SQL injection**
+- `.raw()`/`.extra()` built with an f-string/`%`/`.format()` instead of the
+  `params` argument.
+
+**CSRF**
+- `@csrf_exempt` added to a view that still relies on session/cookie
+  authentication — an exemption is only correct alongside an equivalent
+  protection (signed webhook signature, non-cookie token auth).
+
+**Migrations**
+- A model field/constraint change with no corresponding migration file in
+  the diff, or a migration file whose `operations` look hand-edited rather
+  than `makemigrations`-generated (no matching model diff for what the
+  operations do).
+- A `RunPython` data migration with no reverse function (or explicit
+  `RunPython.noop`) when reversal is meaningful for the data being changed.
+
+**Settings and secrets**
+- `SECRET_KEY` hard-coded or the `django-insecure-` placeholder left in a
+  settings module used outside local dev.
+- `DEBUG = True` or an empty/`["*"]` `ALLOWED_HOSTS` in a settings module
+  reachable in production.
+
+**Forms/serializers**
+- `fields = "__all__"` on a `ModelForm`/`ModelSerializer` that accepts
+  user-submitted input.
+
+### Step 3: Report
+
+For each finding: file:line, category, what's wrong, and the safe
+alternative (cite the exact API, e.g. "add `.select_related(\"author\")` to
+this queryset").
+
+```
+django-code-review: 3 findings
+  [n+1] views.py:22 — `Book.objects.all()` iterated with `book.author.name`
+    in the template; add `.select_related("author")`
+  [xss] profile.py:15 — `mark_safe(profile.bio)` on a user-submitted field;
+    remove mark_safe and let auto-escaping handle it
+  [csrf] webhooks.py:8 — `@csrf_exempt` on a view still using
+    `SessionAuthentication`; either drop the exemption or switch to a
+    signed-payload auth scheme
+```
+
+## Rules
+
+- NEVER edit the files under review — report findings only.
+- Cite the specific line and the specific safe alternative; a vague "this
+  could be an issue" finding is not actionable.
+- Do not duplicate a finding the project's own configured `ruff`/`mypy`/
+  `manage.py check` already enforce and would catch on their own — focus on
+  what static tooling misses (N+1 patterns needing template/serializer
+  context, `mark_safe` on genuinely user-traceable data, migration/model
+  drift).
+- Distinguish a real bug from a stylistic preference; a stylistic point
+  belongs in `rules/coding-style.mdc`/`rules/patterns.mdc`, not a review
+  finding blocking the change.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "The `mark_safe` call is fine, it's inside an admin-only view" | An admin-only view still renders content a user submitted through some earlier form; check where the value actually originated, not just where it's rendered |
+| "It's just a review, I'll add select_related myself since it's one line" | This skill is read-only; even a trivial fix belongs to the author or `django-implementation`, not a silent edit during review |
+| "The N+1 loop only ever runs over 3 rows in the demo data" | Demo/test data size does not bound production data size; flag it regardless of current call sites |
+| "The migration file looks fine, I don't need to check it matches the model diff" | A hand-edited or missing migration is invisible until deploy; always cross-check migration operations against the actual model change |
+
+## Verification
+
+Do not report the review done until all of the following hold:
+
+- Every changed Django file in scope was checked against all seven
+  categories in Step 2.
+- No finding duplicates something the project's own configured linter/type
+  checker/`manage.py check` already flags and enforces.
+- Every finding names a file:line, the specific problem, and a specific
+  fix — no vague findings.
+- No file under review was modified.

package/src/gdskills/bundled/stacks/django/skills/django-code-review/evals.json

@@ -0,0 +1,48 @@
+{
+  "triggers": {
+    "positive": [
+      "Can you look over the changes in this Django PR (#482) and flag any N+1 query risk before it ships?",
+      "Check this Django PR for CSRF or XSS issues",
+      "Audit this Django view for security problems around user input",
+      "Review this Django migration to make sure it matches the model change",
+      "Does this queryset in our Django Order model hit the DB once per row, or is select_related missing somewhere?",
+      "Review this Django REST Framework serializer for mass-assignment risk"
+    ],
+    "negative": [
+      "Implement this new feature in this Django view, don't just review it",
+      "Review this plain Python module for bare except clauses",
+      "Review this FastAPI endpoint for missing auth or CORS misconfiguration",
+      "Review this Node.js Express route for injection vulnerabilities",
+      "Fix the failing Django migration, don't just report what's wrong",
+      "Write pytest tests covering this Django view's permission checks",
+      "Review this React component for unnecessary re-renders"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "flag-raw-query-string-interpolation",
+      "prompt": "Review this Django code for security issues:\n\n```python\ndef search_orders(request):\n    status = request.GET.get(\"status\", \"\")\n    orders = Order.objects.raw(\n        f\"SELECT * FROM orders_order WHERE status = '{status}'\"\n    )\n    return render(request, \"orders/search.html\", {\"orders\": orders})\n```",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct review flags that the `status` query parameter is interpolated directly into the raw SQL string with an f-string, which is a SQL injection vulnerability, and recommends passing it through `raw()`'s `params` argument instead.",
+          "pass_criteria": [
+            "identifies the f-string interpolation of `status` into the raw SQL string as a SQL injection vulnerability, citing the specific line/code",
+            "recommends the fix concretely: pass `status` via the `params` argument (e.g. `Order.objects.raw(\"SELECT * FROM orders_order WHERE status = %s\", [status])`), not just \"sanitize the input\" in the abstract"
+          ],
+          "fail_criteria": [
+            "reviews the code without flagging the f-string SQL interpolation as a vulnerability, or suggests a fix that still builds the query string by interpolating `status` (e.g. escaping quotes manually) instead of using `params`. Mentioning that raw() with string interpolation is dangerous only as background context, while still flagging this exact line, is not this failure."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "```\n[security] views.py:4 — `Order.objects.raw(f\"...status = '{status}'\")` builds the raw SQL by\n  interpolating the `status` GET parameter directly into the string with an\n  f-string. This is a SQL injection vulnerability: a value like\n  `x' OR '1'='1` breaks out of the intended WHERE clause. Fix: pass status\n  through raw()'s params argument instead --\n  `Order.objects.raw(\"SELECT * FROM orders_order WHERE status = %s\", [status])`\n  -- so the database driver parameterizes it rather than the string being\n  built by hand.\n```\nThis names the exact line, explains the injection mechanism (breaking out of the string literal), and gives the concrete `params`-based fix rather than a general warning.",
+        "known_wrong": "```\nThe search_orders view looks fine -- it reads the status filter from the\nquery string and returns matching orders. raw() is a normal way to run a\ncustom query when the ORM's query builder doesn't fit, and status here is\njust a simple filter value.\n```\nThis approves the code without flagging that `status` is interpolated directly into the raw SQL string via an f-string, which is exactly the SQL injection pattern Django's own raw() documentation warns against.",
+        "vague": "Watch out for SQL injection risk anywhere user input reaches a raw query in this codebase.",
+        "subtle_wrong": "```\n[note] views.py:4 — the status filter is built with an f-string into the raw\n  SQL. Since `request.GET.get(\"status\", \"\")` only returns simple query-string\n  values (not file uploads or JSON bodies), and the orders_order table has no\n  sensitive columns beyond what's already shown in the search results, this is\n  low risk in practice. Worth cleaning up eventually but not blocking.\n```\nThis correctly locates the f-string interpolation but downgrades it to a non-blocking style note by reasoning that GET-parameter input is inherently lower risk and the table has no sensitive columns -- a plausible-sounding risk assessment that still recommends merging code with a live SQL injection vector, since any GET parameter is exactly the kind of value an attacker controls directly through the URL."
+      },
+      "anti_patterns": ["f-string"]
+    }
+  ]
+}

package/src/gdskills/bundled/stacks/django/skills/django-implementation/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: django-implementation
+description: "Use when implementing or extending a feature in a Django (5.x) project -- covers models and migrations, class-based/function-based views, forms and serializers, querysets with select_related/prefetch_related to avoid N+1, the framework's CSRF/escaping defaults, and the code-level changes for a Django major-version upgrade (e.g. 4.x to 5.x; pair with django-migrate for any accompanying schema migration discipline). Not for plain Python with no Django import (see python-implementation)."
+triggers:
+  - "add a django model for..."
+  - "write a django rest view that..."
+  - "implement this django feature"
+  - "add a new django app for..."
+  - "write a class-based view for..."
+  - "add a form/serializer that validates..."
+  - "implement a django queryset that..."
+  - "add a manager method to this django model"
+metadata:
+  origin: authored
+  category: implement
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# Django implementation
+
+Implement or extend a feature in a Django (5.x) project: models and
+migrations, views (class-based or function-based), forms/serializers, and
+query patterns that avoid the framework's most common performance and
+security pitfalls. Scoped to writing production code in a Django project —
+for plain Python with no Django import use `python-implementation`, for
+writing/fixing tests use `django-testing`, for reviewing a diff without
+editing it use `django-code-review`, for fixing a broken build/check use
+`django-build-fix`, for a Django-version-major upgrade use `django-migrate`.
+
+## Workflow
+
+### Step 1: Discover the project's own conventions
+
+1. Read `settings.py`/`settings/` to find: installed apps, the configured
+   database backend, `AUTH_USER_MODEL`, whether Django REST Framework is
+   installed, and whether `pytest-django` is configured.
+2. Identify the target app (or whether a new app is warranted) — one app per
+   cohesive domain concern, per `rules/coding-style.mdc`.
+3. Read 1-2 neighboring `models.py`/`views.py`/`forms.py` in the same app
+   for: CBV vs FBV convention, `related_name` style, how validation is
+   split between model/form/serializer, and response-shape conventions
+   (plain Django views + templates vs. a DRF API).
+4. Check `requires-python`/CI config and the pinned Django version before
+   using a feature specific to a recent Django release.
+
+### Step 2: Design the change
+
+- Model layer: choose fields, `related_name`, `Meta.constraints`
+  (`UniqueConstraint`, `CheckConstraint`) for invariants the database itself
+  should enforce, not only a form's `clean()`. See `rules/patterns.mdc`.
+- Decide the view shape: a generic class-based view (`ListView`,
+  `DetailView`, `CreateView`, or a DRF `APIView`/`ViewSet`) for standard
+  CRUD, a function-based view or a CBV method override when the logic
+  doesn't map onto a generic view's hooks.
+- Plan the query path before writing the view body: which related objects
+  will be accessed per row, and whether `select_related`/`prefetch_related`
+  is needed to avoid N+1 (see `rules/patterns.mdc`).
+- Decide validation ownership: a per-field/cross-field rule that must hold
+  for every write path goes on the model (`Meta.constraints`,
+  `clean()`/`full_clean()`); a rule specific to one submission path goes on
+  that `Form`/`Serializer`.
+
+### Step 3: Implement
+
+1. Add/update the model, then generate the migration:
+   ```bash
+   python manage.py makemigrations
+   ```
+   Review the generated migration file; never hand-write `operations` to
+   match a model edit by guesswork.
+2. Write the view, applying `select_related`/`prefetch_related` on the
+   queryset for every relation the view or its template/serializer accesses
+   per row.
+3. Write the form/serializer with an explicit `fields = [...]` list (never
+   `"__all__"` on user-submitted input) and a `clean_<field>`/`validate_<field>`
+   method for interdependent validation.
+4. Wire the URL with `path()`, namespaced under the app, reversed with
+   `reverse()`/`{% url %}` rather than a hand-built path string.
+5. Follow `rules/coding-style.mdc` for naming/layout, `rules/patterns.mdc`
+   for query/migration idiom; check `rules/security.mdc` before touching
+   `mark_safe`/`|safe`, `.raw()`/`.extra()`, CSRF decorators, or settings.
+
+### Step 4: Verify
+
+```bash
+python manage.py check
+python manage.py makemigrations --check --dry-run
+ruff check .
+ruff format --check .
+mypy .   # with django-stubs, if configured
+python manage.py test   # or: pytest, if pytest-django is configured
+```
+
+Prefix each command with the project's own run prefix (`uv run`, `poetry
+run`) when it uses one — discovered in Step 1.
+
+### Step 5: Report
+
+```
+Implemented: billing/models.py, billing/views.py, billing/migrations/0007_add_invoice_status.py
+  - added `Invoice.status` field + `Status` choices, migration generated and reviewed
+  - `InvoiceListView` uses select_related("customer") to avoid N+1
+  - manage.py check / makemigrations --check / ruff / mypy / test: all green
+```
+
+## Rules
+
+- ALWAYS discover and match the project's own conventions (Step 1) before
+  assuming DRF, `pytest-django`, or a specific Django version's features.
+- ALWAYS run `makemigrations` to generate a migration from a model change;
+  never hand-write migration `operations` to match an edit by guesswork.
+- NEVER apply `mark_safe()`/`|safe` to a value that traces back to user
+  input, and never add `@csrf_exempt` to make a failing request succeed
+  without confirming an equivalent protection exists first (`rules/security.mdc`).
+- NEVER build a `.raw()`/`.extra()` query by interpolating a value into the
+  SQL string; pass it through the `params` argument.
+- NEVER leave `fields = "__all__"` on a `ModelForm`/`ModelSerializer` that
+  accepts user-submitted data.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll just loop and call `.save()` per row, it's simpler than `bulk_create`" | An N+1 on the write side; use `bulk_create`/`bulk_update` for a batch write |
+| "This template value is safe, I'll mark it `\|safe` to stop the escaping" | If the value ever traces back to user input, this reintroduces XSS; escape it properly or sanitize before rendering instead |
+| "`@csrf_exempt` makes the POST succeed, I'll leave it" | A passing request after exempting CSRF proves the exemption works, not that it's safe on a session-authenticated endpoint |
+| "I'll hand-edit the migration file, `makemigrations` produced something odd" | The generated file reflects the real model diff; fix the model or the migration's logic, don't paper over a mismatch by hand |
+
+## Verification
+
+Do not report the work done until all of the following hold:
+
+- Every model change has a corresponding migration generated by
+  `makemigrations` and reviewed, not hand-written.
+- A queryset the view/serializer iterates and dereferences per row uses
+  `select_related`/`prefetch_related` for the relations it accesses.
+- `python manage.py check`, `makemigrations --check --dry-run`, `ruff
+  check .`, `ruff format --check .`, `mypy .` (or the project's configured
+  equivalents) all exit 0.
+- `python manage.py test`/`pytest` (whichever the project configures)
+  passes; if the feature needs new tests, hand off to `django-testing`
+  rather than writing test files as part of this skill's own change set.
+- No `mark_safe`/`|safe` on user-traceable data, no `.raw()`/`.extra()`
+  built by string interpolation, and no `@csrf_exempt` added, introduced by
+  this change.

package/src/gdskills/bundled/stacks/django/skills/django-implementation/evals.json

@@ -0,0 +1,75 @@
+{
+  "triggers": {
+    "positive": [
+      "Add a Django model for Invoice with a status field and generate the migration",
+      "Write a Django REST Framework view that lists a customer's orders with their line items",
+      "Implement a class-based view in Django that shows a book's detail page along with its author",
+      "We need a standalone app to own the subscription-billing logic -- can you scaffold a Django app with models, admin, and urls set up?",
+      "Write a Django form that validates a signup submission with cross-field checks",
+      "Implement a queryset method on this Django model that returns only pending orders",
+      "Add a manager method to the Order model that avoids N+1 when listing items"
+    ],
+    "negative": [
+      "Implement this in plain Python with no framework, just a script that parses a CSV",
+      "Implement this FastAPI path operation that returns a list of users, not a Django view",
+      "Write a pytest test for this FastAPI endpoint that returns a list of users",
+      "Review this Node.js Express route for security issues",
+      "Add type hints to this untyped Python function in our shared utils package",
+      "Implement a React component that renders a list of the same orders",
+      "Fix this ModuleNotFoundError when importing mypkg.util in our plain Python service"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "select-related-n1",
+      "prompt": "Write a Django view function `book_list` that renders every Book in a template, where the template also displays each book's author name.",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer builds the queryset with `select_related` on the author foreign key so the author's name is fetched in the same query as the books, rather than triggering one extra query per book when the template accesses `book.author.name`.",
+          "pass_criteria": [
+            "the queryset passed to the template is built with `Book.objects.select_related(\"author\")` (or an equivalent named relation) shown in actual code, not merely described as an intention",
+            "the view returns/renders that queryset so the template's per-book access to `book.author.name` does not trigger an additional query per row"
+          ],
+          "fail_criteria": [
+            "iterates or renders `Book.objects.all()` (or any queryset with no `select_related`/`prefetch_related` for the author relation) while the template accesses `book.author` per row, causing one query per book. Mentioning select_related only to describe the problem is not a failure."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "```python\nfrom django.shortcuts import render\n\ndef book_list(request):\n    books = Book.objects.select_related(\"author\").all()\n    return render(request, \"books/list.html\", {\"books\": books})\n```\n`select_related(\"author\")` performs a SQL join and pulls each book's author row into the same query as the books themselves, so the template's `{{ book.author.name }}` on every row hits data already loaded in Python instead of issuing a fresh query per book. This is the right choice specifically because `author` is a `ForeignKey` (single-valued) -- `select_related` only works for foreign-key/one-to-one relations; a many-valued relation would need `prefetch_related` instead.",
+        "known_wrong": "```python\nfrom django.shortcuts import render\n\ndef book_list(request):\n    books = Book.objects.all()\n    return render(request, \"books/list.html\", {\"books\": books})\n```\nThis just fetches all the books and hands them to the template -- simple and it works, since the template can access `book.author.name` on each one via Django's normal relation traversal, and `Book.objects.all()` is the standard way to list every row in a table.",
+        "vague": "Make sure the author lookup doesn't cause a separate query for every book in the list -- optimize the queryset before it reaches the template.",
+        "subtle_wrong": "```python\nfrom django.shortcuts import render\n\ndef book_list(request):\n    books = Book.objects.select_related(\"publisher\")\n    return render(request, \"books/list.html\", {\"books\": books})\n```\nAdding `select_related(\"publisher\")` eager-loads the book-publisher join in the same query, which is exactly the kind of optimization this queryset needed -- it turns what would otherwise be a per-row lookup into a single upfront join, so the view no longer pays a query-per-book cost when the template walks the list."
+      }
+    },
+    {
+      "id": "no-mark-safe-on-user-bio",
+      "prompt": "Implement a Django view that renders a user's bio -- submitted earlier through a profile-edit form -- on their public profile page template.",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer renders the user-submitted bio through Django's normal template auto-escaping and does not call `mark_safe()` or apply the `|safe` filter to it, since the bio is user-controlled data and marking it safe would reintroduce stored XSS.",
+          "pass_criteria": [
+            "passes the bio to the template as an ordinary context variable rendered with normal auto-escaping (no `mark_safe()` call and no `|safe` filter applied to the bio anywhere in the view or template code shown)",
+            "shows the actual view/template code implementing this, not just a description of the approach"
+          ],
+          "fail_criteria": [
+            "wraps the bio in `mark_safe()` or renders it with the `|safe` template filter so it bypasses Django's auto-escaping. Mentioning `mark_safe`/`|safe` only to warn that they must not be used on user input is not a failure."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "```python\n# views.py\ndef profile_detail(request, username):\n    profile = get_object_or_404(Profile, user__username=username)\n    return render(request, \"profiles/detail.html\", {\"profile\": profile})\n```\n```html+django\n<!-- profiles/detail.html -->\n<p>{{ profile.bio }}</p>\n```\nThe bio is passed straight through as a normal context variable, so Django's template auto-escaper HTML-escapes it before rendering -- any `<script>` a user typed into their bio renders as inert text, not executable markup. No `mark_safe()`/`|safe` is used anywhere, because the bio is user-submitted data and marking it safe would let a user's own script tag execute in every visitor's browser (stored XSS).",
+        "known_wrong": "```python\n# views.py\nfrom django.utils.safestring import mark_safe\n\ndef profile_detail(request, username):\n    profile = get_object_or_404(Profile, user__username=username)\n    bio_html = mark_safe(profile.bio)\n    return render(request, \"profiles/detail.html\", {\"bio_html\": bio_html})\n```\nWrapping the bio in `mark_safe()` before passing it to the template lets it render exactly as the user typed it, including any basic formatting they added -- `mark_safe` is the documented way to tell Django a string is already safe HTML, so this is the standard tool for showing user content as-is.",
+        "vague": "Be careful with how the bio gets rendered so a user can't inject a script into their own profile page that runs for other visitors.",
+        "subtle_wrong": "```python\n# views.py\ndef profile_detail(request, username):\n    profile = get_object_or_404(Profile, user__username=username)\n    return render(request, \"profiles/detail.html\", {\"profile\": profile})\n```\n```html+django\n<!-- profiles/detail.html -->\n<p>{{ profile.bio|safe }}</p>\n```\nThe view itself stays simple and passes the profile through untouched -- the `|safe` filter is applied only in the template, right where the bio is displayed, which keeps the escaping decision colocated with the markup instead of scattered across the view layer."
+      },
+      "anti_patterns": [
+        "mark_safe"
+      ]
+    }
+  ]
+}

package/src/gdskills/bundled/stacks/django/skills/django-migrate/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: django-migrate
+description: "Use when generating, reviewing, or safely applying Django schema/data migrations -- makemigrations for a model change, RunPython data migrations with forward/reverse functions, merge migrations for divergent branches, and staged rollout for a migration that must ship alongside a multi-phase deploy (e.g. a column removal). Not for a Django major-version framework upgrade (there is no separate django-upgrade skill in this pack; the code-level upgrade work is owned by django-implementation) or for fixing a broken/conflicting migration that's blocking the build (see django-build-fix)."
+triggers:
+  - "generate a django migration for this model change"
+  - "write a data migration to backfill this field"
+  - "make this django migration reversible"
+  - "how do I safely drop this column in django"
+  - "squash these django migrations"
+  - "write a RunPython migration"
+  - "stage this django schema change across two deploys"
+metadata:
+  origin: authored
+  category: migrate
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# Django migrate
+
+Generate, review, and safely apply Django schema and data migrations:
+`makemigrations` for a model change, `RunPython` for data transforms with
+forward/reverse functions, and staged rollout for a migration whose schema
+change would break code still running the previous release. Scoped to the
+migration itself — for the model/view/form code change that motivates the
+migration use `django-implementation`; for resolving a migration that is
+already conflicting or blocking the build use `django-build-fix`.
+
+## Workflow
+
+### Step 1: Establish what's changing and why
+
+1. Diff the model change driving the migration (new field, changed
+   constraint, removed field, renamed field/table) against the current
+   migration graph's state for that app.
+2. Decide whether this is schema-only (Django can express it entirely as
+   `AddField`/`AlterField`/etc.) or needs a data transform (backfilling a
+   new non-nullable field, splitting one column into two, converting a
+   value's representation) — a data transform needs a `RunPython` step, not
+   just the schema operation.
+3. Check whether the change is destructive for code still running the
+   previous release (a column removal, a rename, a type narrowing) — if the
+   project deploys code and migrations as separate steps, this needs a
+   staged rollout (Step 4), not a single migration.
+
+### Step 2: Generate the migration
+
+```bash
+python manage.py makemigrations <app_label>
+```
+
+Let Django diff the models against the existing migration graph; never
+hand-write `operations` to match a model edit by guesswork. Review the
+generated file: correct operation types, correct `dependencies`, and no
+unexpected side operation (an accidental `AlterField` on an untouched field
+usually means the model's `Meta` or a field kwarg drifted from what the
+last migration recorded).
+
+### Step 3: Add data-transform logic when needed
+
+- Add a `migrations.RunPython(forward, reverse)` operation for any
+  transform that touches existing row data. Write both directions:
+  `forward` performs the transform, `reverse` undoes it (or use
+  `migrations.RunPython.noop` for `reverse` only when undoing is genuinely
+  not meaningful, e.g. an irreversible data merge — state that explicitly
+  rather than omitting the argument).
+- Fetch models inside `RunPython` via `apps.get_model("app", "Model")` (the
+  historical, frozen-at-this-migration model), never by importing the
+  live model class — the live model can have fields this migration's
+  historical state doesn't, which breaks replaying migration history from
+  scratch.
+- For a backfill on a large table, batch the update (`.iterator()` +
+  chunked `.bulk_update()`, or `Model.objects.filter(...).update(...)` when
+  the value doesn't depend on per-row computation) rather than a single
+  `.save()`-per-row loop.
+
+### Step 4: Stage a destructive/breaking change
+
+For a schema change that would break code from the previous release still
+running during a rolling deploy (removing a column code still reads, a
+rename, `NOT NULL` added without a default):
+
+1. **Release N:** ship the code change that stops reading/writing the old
+   shape, while the schema still has it (e.g. stop reading the old column,
+   start reading/writing the new one; add the new nullable column alongside
+   the old one).
+2. **Release N+1:** once release N is fully rolled out, ship the migration
+   that actually drops/alters the old schema — nothing still running reads
+   it by then.
+3. Never combine "stop using the old column in code" and "drop the old
+   column in the same migration" in one release when the project's deploy
+   process can run old code against the new schema for any window (rolling
+   deploy, canary, multiple app servers) — that window is exactly when a
+   still-running old-code instance would break.
+
+### Step 5: Merge conflicting migrations
+
+When two branches added divergent migrations from the same parent:
+
+```bash
+python manage.py makemigrations --merge
+```
+
+Review the generated merge migration; never hand-edit either migration's
+`dependencies` to force a resolution instead (see `django-build-fix` if this
+is blocking a currently-broken build).
+
+### Step 6: Verify and report
+
+```bash
+python manage.py makemigrations --check --dry-run
+python manage.py migrate --plan
+python manage.py test   # or: pytest, if pytest-django is configured
+```
+
+```
+Migrated: accounts app
+  - 0012_backfill_display_name.py: RunPython forward fills display_name from
+    first_name+last_name for existing rows; reverse clears it back to ""
+  - staged: this release only adds the nullable display_name column and
+    backfills it; a follow-up release will make it NOT NULL and stop
+    accepting the old two-field form
+  - makemigrations --check, migrate --plan, test: all green
+```
+
+## Rules
+
+- ALWAYS generate migrations with `makemigrations`; never hand-write
+  `operations` to match a model edit by guesswork.
+- ALWAYS write both `forward` and `reverse` for a `RunPython` data
+  migration, or explicitly use `RunPython.noop` with a stated reason when
+  reversal isn't meaningful.
+- ALWAYS fetch models inside a `RunPython` function via
+  `apps.get_model(...)`, never the live imported model class.
+- NEVER combine dropping/breaking a schema shape with removing the last
+  code that reads it in the same release when the deploy process can run
+  old code against the new schema for any window — stage it across two
+  releases instead.
+- NEVER hand-edit a migration's `dependencies`/`operations` to resolve a
+  conflict — generate a merge migration and review it.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll drop the old column and update the code in the same migration/release" | Breaks any old-code instance still running against the new schema during a rolling deploy; stage it across two releases |
+| "I'll import the live model in this RunPython function, it's simpler" | The live model can drift from what this migration's historical state expects, breaking a from-scratch replay of migration history; use `apps.get_model(...)` |
+| "This data migration doesn't need a reverse, I'll just leave it out" | Leaves `migrate <app> <previous>` broken for this migration; use `RunPython.noop` explicitly if reversal truly isn't meaningful |
+| "I'll hand-edit the migration's `dependencies` to resolve this merge conflict" | Desyncs the migration graph from what other environments already recorded as applied; use `makemigrations --merge` |
+
+## Verification
+
+Do not report the work done until all of the following hold:
+
+- The migration was generated by `makemigrations` (or `--merge`), not
+  hand-written from scratch.
+- Any data transform uses `RunPython` with both `forward` and `reverse` (or
+  an explicit, justified `RunPython.noop`), fetching models via
+  `apps.get_model(...)`.
+- A destructive/breaking schema change is staged across two releases when
+  the project's deploy process can run old and new code concurrently.
+- `makemigrations --check --dry-run` and `migrate --plan` both succeed with
+  no unexpected pending operation, and the test suite passes.
+- No migration file's `dependencies`/`operations` was hand-edited outside
+  what `makemigrations`/`--merge` generated.

package/src/gdskills/bundled/stacks/django/skills/django-migrate/evals.json

@@ -0,0 +1,49 @@
+{
+  "triggers": {
+    "positive": [
+      "Generate a Django migration for this new required field on the Order model",
+      "The display_name column needs to be populated from existing first_name/last_name values on all existing rows -- what's the right way to do that as a Django migration?",
+      "This Django migration only defines a forward RunPython operation -- how do I add the reverse function so it can be rolled back cleanly with `migrate`?",
+      "We're removing the `legacy_phone` column from a Django model via a rolling deploy -- what's the safe sequencing so instances running the old code don't break mid-rollout?",
+      "The accounts app in our Django project has accumulated 40+ migration files going back two years -- can you collapse them into a smaller set?",
+      "Write a RunPython migration that normalizes existing phone numbers",
+      "We want to rename a column but can't do it in one shot with our rolling deploy setup -- how should I split this Django schema change into multiple releases?"
+    ],
+    "negative": [
+      "Fix this Django migration conflict that's currently blocking makemigrations from running",
+      "Implement the actual view logic that will use this new field, not the migration",
+      "Write a database migration for our Node.js service using Knex",
+      "Write an Alembic migration for our FastAPI service's SQLAlchemy models",
+      "Add a pytest-django test for this model's new field",
+      "Run a Prisma migration for our TypeScript backend",
+      "Review this Django migration for correctness, don't write a new one"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "stage-destructive-column-drop",
+      "prompt": "We deploy Django app code and run migrations as separate steps, with a rolling deploy across several app servers. The `User` model has an old `full_name` column that's now replaced by separate `first_name`/`last_name` columns; all reads/writes of `full_name` in the codebase have already been removed in the code we're about to ship. How should the migration to actually drop the `full_name` column be sequenced?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer ships the code that stops reading/writing full_name in one release, and only drops the full_name column in a later, separate release/migration once that release's rollout has been confirmed complete -- not merely scheduled after the deploy step in a pipeline. Placing a migration step after a deploy step in the same pipeline run does not, by itself, prove every instance has finished rolling onto the new code (a stalled or partially-failed rollout can leave old-code instances running well after the deploy step reports success), and keeping the drop in the same release as the code change is unsafe regardless of step ordering or added verification within that release -- the column drop must be its own, later release, gated on confirming the prior release's rollout is fully complete.",
+          "pass_criteria": [
+            "states that dropping the `full_name` column must happen in a separate, later migration/release from the code change that stops using it, and that this later step should only run once the prior release's rollout is confirmed complete (not merely scheduled after it in a pipeline)",
+            "explains why: during a rolling deploy, some app server instances still run the old code (which still reads/writes `full_name`) while others already run the new code, so dropping the column before every instance has actually finished rolling onto the new code would break the old instances"
+          ],
+          "fail_criteria": [
+            "recommends dropping the `full_name` column in the same release/migration as the code change that removes its usage. Noting that combining them would be 'faster' only to then reject it as unsafe is not this failure.",
+            "treats scheduling the migration step to run after the deploy step within the same release's pipeline as sufficient on its own to guarantee every old-code instance is gone, with no verification (e.g. checking rollout/replica status or a health check) that the rollout actually completed"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "Ship the code change (already done here, since the codebase no longer reads/writes `full_name`) as its own release first, and confirm it has fully rolled out to every app server -- e.g. checking that the deployment shows 100% of instances on the new revision, not just that the deploy step exited successfully. Only after that confirmation -- in a separate, later release -- generate and apply the migration that actually drops the `full_name` column:\n```bash\npython manage.py makemigrations accounts   # in the follow-up release\n```\nThis produces a `RemoveField` operation for `full_name`. The reason for the two-release split plus the explicit confirmation: during a rolling deploy some servers are still running the previous release's code, which still references `full_name`, while others already run the new code, and a deploy step reporting success doesn't guarantee every instance has actually finished cycling onto the new code (a stuck pod, a slow canary, or a failed health check can leave old instances running past that point). Splitting into a later release and confirming rollout completion before touching the schema removes that window entirely.",
+        "known_wrong": "Since the code no longer reads or writes `full_name` at all, it's safe to include the column drop in this same release -- generate the migration now:\n```bash\npython manage.py makemigrations accounts\n```\nand ship it alongside the code change. There's no reason to wait for a second release since the application layer is already fully decoupled from that column.",
+        "vague": "Don't drop the column and remove the code that uses it at the same time -- give it some separation so nothing breaks during the rollout.",
+        "subtle_wrong": "You can ship the column drop in this same release as long as the migration step is placed after the code-deploy step in the pipeline definition, rather than before or during it -- since the pipeline runs steps in order, by the time the migration step executes every server is guaranteed to already be on the new code. That keeps it to one release instead of splitting into two: the ordering of steps within the pipeline is what actually matters, not which release they belong to, and a deploy step that has exited successfully means the rollout is done."
+      }
+    }
+  ]
+}