backend-pr-workflow

What this skill does

# 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 flo