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