Backend Pr Workflow

Backend PR Workflow Skill

When to Use This Skill

Use this Skill whenever you are:

• Creating or reviewing a backend PR that touches Django models, migrations, or production data.
• Preparing a PR for Django4Lyfe / Workforce backend or a similar repo that uses ClickUp as the primary ticket system.
• Planning a release or hotfix and want to ensure the workflow (branches, tags, and migrations) is correct and downtime-safe.

If local AGENTS.md / CLAUDE.md in the target repo conflict with anything here, treat those files as the source of truth and use this Skill as the default baseline.

Example Prompts

• “Use the backend-pr-workflow skill to review this Django4Lyfe PR’s branch name, ClickUp linkage, migrations, and downtime-safety. Here are the branch name, base branch, and PR title: …”
• “Before I open this backend PR, run backend-pr-workflow on my planned title, description, and migration summary and tell me all [BLOCKING] and [SHOULD_FIX] issues.”
• “For this hotfix PR on Django4Lyfe, use backend-pr-workflow to check that my base branch, title, and release plan follow our backend workflow.”
• “I’ve added a new nullable field and a backfill migration. Use backend-pr-workflow to verify that my migrations and rollout plan are downtime-safe.”

Severity Tags & Output Shape

When this Skill reviews a PR or workflow plan, the response must be structured and tagged:

• Start with a 1–3 sentence summary of what was checked.
• Then use sections:
  • What’s aligned – bullets of things that follow the workflow.
  • Needs changes – bullets with severity tags:
    • [BLOCKING] – must fix before merge or deploy.
    • [SHOULD_FIX] – important but not strictly blocking for merge.
    • [NIT] – minor consistency or documentation suggestions.

Each bullet in Needs changes should:

• Point to the specific item (branch name, PR title, description, migration file, release plan).
• State the problem and the concrete correction the author should make.

Example bullet:

• [BLOCKING] Branch name 'feature/my-thing' does not follow the required 'clickup_<ticket_id>' convention, and CI may not run. Rename to something like 'clickup_GH-1234_my-thing'.

Inputs This Skill Expects

Before giving a full review, this Skill should gather:

• The repository and context (e.g. Django4Lyfe backend / monolith).
• The branch name.
• The PR title and PR description (or the planned ones).
• The base branch (what the PR targets: release, master, etc.).
• Whether the PR:
  • Includes Django model changes.
  • Adds, modifies, or deletes migrations.
  • Is a normal feature/bugfix, a hotfix, or a release PR.

If any of these are missing or unclear, ask the user to provide them before doing a full workflow review.

Checklist 1 – ClickUp & Branch / PR Naming

This Skill treats ClickUp linkage as non-negotiable.

1.1 Branch name

Check the branch name:

• It must start with clickup_<custom_ticket_id>:
  • Examples:
    • clickup_GH-785
    • clickup_GH-785_world_domination
• The ticket ID must be the ClickUp custom ticket ID (e.g. GH-785), not the numeric internal ID.
• Rationale:
  • CI (e.g. CircleCI) is configured to run only for branches starting with clickup_.
  • ClickUp uses the custom ticket ID to automatically link branches, PRs, and commits to tickets.

If the branch does not follow this pattern, emit:

• [BLOCKING] – with a suggested corrected branch name.

1.2 Multi-repo work and sub-tickets

When a feature spans multiple repositories, enforce:

• Do not reuse the same ClickUp ID across multiple repos.
• Instead, require:
  • One parent ClickUp ticket for the overall feature.
  • Separate sub-tickets per repo:
    • Backend: GH-2961
    • Frontend: GH-2962
    • Data Science: GH-2963
    • Infra: GH-2964
• Each sub-ticket gets its own branch, PR, and commit series, following the same naming rules.

Explain risks of reusing the same ID across repos:

• Automation may update status prematurely or incorrectly.
• PRs from different repos can be linked to the wrong task.
• Ownership and progress become ambiguous.

If the user appears to be reusing the same ID across repos, emit:

• [SHOULD_FIX] – recommending sub-tickets and distinct branch/PR naming.

1.3 Commit messages

Check or remind the user that:

• All commits for the PR should start with the ticket ID:
  • GH-785: Find another meaning of life
• This is often enforced by commit_msg_hook.py and pre-commit hooks, but the Skill should still call out obvious violations.

If commit messages clearly lack ticket IDs (based on user input), emit:

• [SHOULD_FIX] – asking the author to fix future commits and, where practical, to rewrite recent history before merge.

1.4 PR title

The PR title must:

• Begin with [<clickup_ticket_id>].
  • Example: [GH-785] Found meaning of life

If not, emit:

• [BLOCKING] – and propose a corrected title that includes the ticket ID.

Remind the user that:

• Correct titles allow ClickUp to auto-link the PR and expose PR status, reviewers, and activity directly in the ticket.

Checklist 2 – WIP Signalling & Base Branch

2.1 WIP / draft status

Check whether the work is still in progress:

• If the author indicates the PR is not ready for review yet:
  • The PR should be in draft mode, or
  • The title or label should clearly include WIP / [WIP].

If not, emit:

• [SHOULD_FIX] – asking the author to convert to draft or annotate the PR as WIP to avoid premature review.

2.2 Base branch selection

Confirm the base branch matches the project’s release workflow:

• Normal feature / bugfix work:
  • Base branch should be release (for repos following the Django4Lyfe pattern).
• Hotfix that must bypass the current release contents:
  • Base branch should be master.

If a PR targets the wrong base branch:

• Emit [BLOCKING] and recommend the correct base, explaining whether the change belongs in release or should be a master hotfix.

If the repo’s docs specify a different default (e.g. custom long-lived branches documented in CLAUDE.md), follow that instead.

Checklist 3 – PR Description & Self-Review

This Skill expects PR authors to be their own first reviewer.

3.1 PR description quality

Check that the description (or planned description):

• Follows any existing PR template for the repo, if one exists.
• Clearly explains:
  • What changed.
  • Why it changed (the problem or goal).
  • Whether there are any breaking changes and what reviewers should inspect carefully.
  • Any required secrets, DB dumps, or setup information, with guidance to share secrets via 1Password / Slack and to clean up messages.
  • Any manual steps needed for deploy:
    • Env vars to add/update.
    • Buckets or external resources to create.
    • Management commands or scripts to run.
    • Whether a DB snapshot is recommended before deploy (for heavy data changes).

If key context is missing, emit:

• [SHOULD_FIX] – listing the missing items and suggesting how to include them.

3.2 Self-review checklist

Prompt the author to confirm they have checked:

• Branch is up to date with the base branch; diff is not polluted by unrelated files.
• All debugging code is removed:
  • No print() / ipdb / pdb left behind.
• Tests have been added or updated for new functionality.
• Tests are passing in CI.
• Pre-commit hooks and coding conventions have been applied.
• Code coverage has not regressed significantly.
• For Django changes: migrations have been cleaned up and regenerated if there were multiple schema iterations.

If any of these fail obviously based on the PR description or user input, emit appropriate [SHOULD_FIX] or [BLOCKING] bullets.

Checklist 4 – Releases, Hotfixes, and Tags

This Skill enforces a clean release flow.

4.1 Normal release flow (via release branch)

For normal deployments, check that:

• Feature/bugfix PRs merge into release.
• Before cutting a release:
  • The version (e.g. in pyproject.toml) is bumped to the intended release version, using CalVer (e.g. 2025-08-19).
  • If direct pushes to release are not allowed, a small PR is created to bump the version on release.
• When ready to deploy:
  • A PR is created from release → master with a title like:
    • Release: 2025-08-19
    • Release 2: 2025-08-19 (for multiple releases in one day).
  • The release PR lists all tickets / PRs included in the description.

Post-deployment:

• A GitHub Release is created targeting master.
• Tag name uses date-based versioning (CalVer):
  • YYYY-MM-DD or YYYY-MM-DD-2.

If any of these are obviously missing from the plan, emit [SHOULD_FIX].

4.2 Hotfix flow

For hotfixes, enforce:

• The hotfix PR targets master (not release).
• The title clearly indicates a hotfix, e.g.:
  • Hotfix release: 2025-08-19
• After deployment:
  • Changes are merged back into release so it stays ahead of or equal to master.
  • A GitHub Release is created and tagged using the same CalVer scheme.

If a supposed hotfix PR is targeting release, or a hotfix is not planned to be merged back into release, emit [BLOCKING].

Checklist 5 – Migrations: Cleanup and Regeneration

When the PR includes Django model changes, this Skill should be pedantic about migrations.

5.1 Avoid noisy chains of migrations from one PR

If the PR has multiple intermediate migrations for the same feature (...x1.py, ...x2.py, ...x3.py, etc.), recommend cleaning them up before merge:

• Identify which migrations were added by this PR vs. which already exist on the main branches.
• Conceptual cleanup workflow:
  • Migrate back to the migration just before the first PR-specific migration.
  • Delete only the migrations introduced by this PR.
  • Regenerate a minimal set of migrations representing the final schema.
  • Apply the new migrations locally and ensure tests pass.

Never recommend deleting migrations that are already on production.

If the PR clearly contains many iterative migrations for one feature, emit:

• [SHOULD_FIX] – asking the author to collapse them into a clean final migration set.

5.2 Respect environment-specific tooling

When suggesting commands, align with the repo’s tooling:

• For Django4Lyfe / Optimo, prefer:
  • uv run / .bin/django wrappers as documented in AGENTS.md / CLAUDE.md.

This Skill should conceptually describe the migration cleanup steps, not hard code commands that may become outdated.

Checklist 6 – Downtime-Safe Schema Changes

This is the most critical part of the Skill for production stability.

6.1 Deleting a field or table

If the PR both:

• Removes a field from the database (or drops a table), and
• Removes or changes code that uses that field,

then:

• Highlight the deployment risk:
  • Between the time migrations run and the time all web workers are updated, old code can still expect the field and will throw errors if it is already dropped.

Enforce the safe two-step pattern:

1. PR 1 – Code-only removal
   • Remove all usage of the field/table from code (queries, serializers, forms, admin, etc.).
   • Keep the field in the DB so old and new code can still run.
   • Deploy fully.
2. PR 2 – Schema removal
   • Add a migration that drops the field/table.
   • Deploy once no running code expects it.

If a single PR contains both the schema drop and remaining code references, or removes code and schema at once in a way that risks downtime, emit:

• [BLOCKING] – and explicitly recommend splitting into two PRs as above.

6.2 Adding a non-volatile default on a large table

For a new column on a large / hot table with a static default (e.g. is_active = True):

• Explain the risk:
  • A naive AddField with default can cause a long-running table rewrite and lock, blocking writes and potentially causing errors.

Enforce a safe pattern:

1. Migration 1 – Add nullable column, no default
   • Add the column with null=True and no default.
   • This ensures the ALTER TABLE ... ADD COLUMN is fast.
2. Migration 2 – Set default and backfill
   • For Postgres 11+:
     • Use RunSQL to set the default for new rows only, avoiding a full table rewrite.
   • For existing rows:
     • Use a data migration, background job, or batched updates to set the value in manageable chunks, ideally with atomic = False for large operations.

If the PR adds a non-nullable column with a default on a table that likely has many rows, emit:

• [SHOULD_FIX] or [BLOCKING] depending on table size and risk, and describe the two-step pattern above.

6.3 Adding a volatile default (e.g. UUID, timestamps)

For defaults that require dynamic values (e.g. generate UUIDs, timestamps):

• Warn that:
  • Setting such defaults on existing rows inside an atomic migration, for a large table, can be very slow and lock-heavy.

Recommend:

1. Add the column as nullable without default.
2. Backfill in batches using a non-atomic migration or out-of-band job.
3. Only then, if needed, add a default for new rows.

If a PR uses a volatile default in a way that will backfill a large table inside an atomic migration, emit:

• [BLOCKING] – and propose the batched, non-atomic backfill approach.

How This Skill Should Behave in Practice

When invoked, this Skill should:

1. Gather the inputs listed above (branch, PR title/description, base branch, migration/schema summary).
2. Apply each checklist in order:
   • ClickUp & naming.
   • WIP & base branch.
   • PR description & self-review.
   • Release/hotfix flow.
   • Migrations.
   • Downtime-safe schema changes.
3. Emit:
   • A short summary paragraph.
   • What’s aligned bullets.
   • Needs changes bullets with [BLOCKING], [SHOULD_FIX], [NIT].
4. Be direct and pedantic but constructive:
   • Treat automation, traceability, and downtime-safety as hard requirements, not nice-to-haves.
   • Always provide specific, actionable corrections rather than vague guidance.

Compatibility Notes

This Skill is designed to work with both Claude Code and OpenAI Codex.

• Claude Code: install the corresponding plugin and use its slash commands (see plugins/backend-pr-workflow/commands/).
• Codex: install the Skill directory and invoke name: backend-pr-workflow.

For installation, see this repo's README.md.